tmcra_ingest

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it only reveals basic write intent via 'persist.' It omits important traits hinted at by the schema and siblings: idempotency behavior (idempotency_key), consistency semantics (eventual vs. read_your_writes), the slow_policy escalation options, and whether the operation is asynchronous (siblings tmcra_get_job/tmcra_wait_job suggest job-based execution).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but this is under-specification rather than efficient conciseness: a single clause cannot serve a tool with seven parameters, a nested message type, and six siblings. It front-loads the core intent but omits nearly everything else.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description is far from complete for this tool's complexity: 7 parameters at 0% schema coverage, no annotations, and a sibling set suggesting a lifecycle/job framework. The agent lacks information about when to ingest, how messages must be structured, job behavior, and consistency options.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description compensates for almost none of the seven parameters. It only implies that 'messages' are conversation messages; it says nothing about session_id, scope, agent_id, consistency, slow_policy, or idempotency_key, leaving the agent to guess their roles and formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('persist') with a resource ('conversation messages that have already occurred'), clearly signaling a write/append operation for historical messages. It is distinguishable from tmcra_recall (reading) and the job/session management siblings, though it does not explicitly differentiate itself from tmcra_turn_commit, which may also write messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus its six siblings. Nothing explains the relationship to tmcra_turn_prepare/tmcra_turn_commit (turn lifecycle) or when ingest is preferred over committing a turn, so the agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.