TealfabricLibrary

Agent payload contracts

Complex console forms are not duplicated in MCP tool schemas. Agents use a four-layer contract so payloads stay small and accurate.

Layers

LayerWhat the model seesSource
L1 — Tool envelopeNarrow parameters (id + optional data)mcp_resources tool definition
L2 — Describe toolsWritable fields, enums, execute requirementsdescribe_* Nest handlers
L3 — Platform skillsWhen to describe, confirm, and sequence callsSKILLS/platform-actions bundle
L4 — Validation errorsField-level errors from domain servicesSame as REST API

Standard write pipeline

describe_*  →  assemble minimal payload  →  request_human_input (if destructive)  →  create_* | update_* | execute_*

Examples

Entity

  1. describe_entity — learn name, type, status, parent_entity_id.
  2. create_entity with { "name": "Acme Oy", "type": "organization" }.

Integration execute

  1. describe_tenant_integration with integration_id (+ optional operation).
  2. Build data from operations[].schema.
  3. execute_tenant_integration with integration_id, operation, data.

Process execute

  1. describe_process with process_id — check executable_by_ai_agents and triggers.
  2. request_human_input confirm (recommended).
  3. execute_process with { "process_id": "...", "async": true, "input_data": {} }.

Anti-patterns

  • Guessing full form payloads without calling describe_*.
  • Duplicating field lists in SKILL.md instead of linking describe tools.
  • One mega-tool with an action parameter and huge union schema.

Related

  • Platform actions
  • Plan: docs/PLANS/AGENT_PLATFORM_ACTIONS_SKILLS_TOOLS_PLAN.md §9.1