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

Beyond the annotations it discloses real behavior: the result is a structured requirement where each value records which words it came from, unresolved or conflicting facts are returned as a single question, unread words are preserved verbatim, and the returned (id, token) must be passed back to continue the same requirement. It also clarifies that despite being a write (readOnlyHint=false) nothing is transmitted or ordered. It does not explain persistence lifetime or what happens when the utterance is partially parsed across retries.

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 core action is front-loaded and every clause carries information — outputs, continuity, non-transmission, and the structured-form alternative. It is dense and heavily parenthetical, so the reading is slightly harder than it needs to be, but there is no filler to cut.

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?

With no output schema and a nested continuation object, the description carries the full burden and does: it explains what is returned (a structured requirement plus at most one clarifying question), what is preserved (unread words), and how to continue the conversation (echo id and token). Nothing essential for a correct first call or a correct follow-up is missing.

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 100%, so baseline is 3, and the description adds real meaning by explaining the purpose of the nested 'requirement' object — pass the id and token from the first answer to continue that same requirement rather than opening a new one. It adds nothing about slug, turn_id, or timezone, which the schema already documents.

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 names a specific verb and resource — 'Give Chamfer the buyer's requirement... in their own words' read into 'a structured requirement' — and makes the transformation (free text → structured fields with provenance) explicit. An agent can distinguish this from send_requirement (which dispatches) and submit_request (which takes already-structured fields) without opening any 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?

It states the trigger (input in the buyer's own words, including corrections or additions), two explicit exclusions ('Nothing is sent or ordered: send_requirement sends it when the buyer says so' and 'When you already have the fields in structured form, use submit_request instead'), each paired with the sibling that should be used instead.

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