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

Annotations already declare a non-read-only, destructive, non-idempotent, closed-world mutation, and the description adds real context on top: it will not email or submit anything, and edits are guarded by an expected_updated_at value from list_applications (optimistic concurrency). It stops short of saying what an edit overwrites in the existing draft or status field, which is the main residual gap for a destructiveHint=true tool.

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?

Four short sentences, each doing work, with the create-or-edit scope front-loaded and the negative scope statement last. The phrasing around 'manual unlinked letter text' and the stray letter_document_id reference cost some immediate clarity.

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 10-parameter destructive write tool with no output schema and zero schema description coverage, the description covers the create/edit decision well but leaves most field-level semantics and the mutation's overwrite behavior unexplained. An agent could call it correctly for the common cases but would be guessing on status, due_date, and next_action.

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%, so the description carries the burden and only partially meets it. It explains id, expected_updated_at, company, title, and the job-linking intent of job_id, but says nothing about status (an 8-value enum), due_date, next_action, job_url, or what 'draft' text versus the letter document means. The concurrency note for expected_updated_at is genuinely valuable added meaning.

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 opens with a concrete verb pair plus resource: 'Create or edit the connected user's application tracker and manual unlinked letter text.' That distinguishes it from siblings like list_applications and save_document. It is slightly muddied by the reference to 'manual unlinked letter text', which is really a delegation note rather than part of this tool's own resource.

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?

Explicit routing rules are given: when letter_document_id is present, use get_document/save_document instead; for tracker edits supply id and expected_updated_at from list_applications; for new records supply company and title. The scoping exclusion 'Does not email or submit an application' also helps. The only flaw is that letter_document_id is not among this tool's parameters, which could momentarily confuse an agent.

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