emet_transcript_append

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

Goes far beyond the annotations: part rolling after 8 exchanges, the single closing-exchange exception after close, the grace window, the lock state, refusal semantics, and the first-append machine-line gate. The only blemish is the claim "Idempotent on exchange_index" sitting against idempotentHint=false; it is defensible as scoped idempotency (a repeated index writes nothing) rather than a safety-relevant contradiction, but the two signals are not obviously reconciled for the agent.

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?

Front-loads the core purpose and routing rule in the first two sentences, then layers edge cases in descending priority. It is long and occasionally dense (the closing-exchange paragraph is a single run-on chain), and "whatever session_id it names" is a minor detour, but almost every sentence carries operational weight.

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?

For a complex, stateful, multi-constraint write tool with no output schema, the description covers the full lifecycle: normal append, part rollover, close grace append, retry resolution, and refusal. It even describes the observable result field (`closing_exchange`) that confirms acceptance, so an agent can act and verify without further documentation.

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 coverage is only 29% across 7 parameters, so the description must compensate. It does add real meaning for exchange_index (whole number of 1 or more, number or its textual form) and for assistant_message on the first append (must carry the measured machine line or "no local shell MCP"), but source, channel, session_start, user_message and the closing-exchange assistant_message content are left to the schema or undocumented.

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?

States a precise verb and resource ("Append ONE exchange to the session transcript") and even emphasizes the unit of work with capitalised "ONE", which separates it from bulk siblings like save_transcript and revise_transcript. An agent knows exactly what this writes and at what granularity without opening the schema.

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?

Explicitly says "Call after every reply", then spells out the when-not cases: appends to a closed session are refused and "that exchange belongs in the next session you open the usual way", with a named exception window (EMET_CLOSE_GRACE_MINUTES). This is textbook when/when-not guidance with the alternative route named.

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