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

Annotations are all false and carry almost no signal, so the description carries the full burden — and it delivers richly: supersede semantics ('filing a second one replaces the first, which is rejected as superseded'), shrink behavior ('5000×5000 export is accepted and stored at 2000px'), format refusal ('anything else is refused by name'), sandbox-induced PUT 403s, truncated-paste rejection via attachmentBytes, and human-override protection ('a human's own choice is never overwritten by a proposal that never saw it'). No contradiction with the annotations — destructiveHint=false aligns with 'This does NOT change anything'.

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 long, but the density of decision-relevant information justifies it: every major block (pending semantics, two lanes, formats, shrinking, one-value replacement, human-override, scope boundary, honesty rule) maps to a distinct risk the agent must handle. Critical info is front-loaded ('FILES A PENDING DRAFT ONLY') and warnings are scannable via caps and the ⛔ marker. Minor deductions for redundancy ('This does NOT change anything' restates the opening sentence) and an editorial aside ('that is YOUR sandbox, not Taokeh').

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 tool — 8 parameters, two mutually exclusive input lanes, no output schema, no idempotency — the description covers purpose, exact invocation mechanics, side effects, concurrency behavior, failure modes, and ethical constraints. The only notable gap is the success response: nothing states what the agent should expect back after filing (e.g., a draft identifier or confirmation), which matters more because there is no output schema. That single omission keeps this from a 5.

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 the baseline is 3. The description adds genuine workflow-level meaning beyond the schema: it groups parameters into two mutually exclusive lanes (attachmentToken alone vs attachmentBase64 + attachmentMediaType + attachmentBytes), explains why attachmentBytes is mandatory alongside base64 ('a truncated paste is rejected rather than filed'), and states the format constraint ('PNG or JPEG only'). It adds little on notes, needsReview, attachmentSha256, or attachmentFilename, but those are already well documented in the schema.

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 first sentence states a specific verb and resource with a decisive qualifier: 'FILES A PENDING DRAFT ONLY — NOTHING CHANGES UNTIL A HUMAN REVIEWS AND APPROVES IT IN TAOKEH. Propose a new COMPANY LOGO.' The title independently confirms it ('File a pending logo-change draft'). It also differentiates from siblings by fencing off the Pioneer testimonial artwork ('THIS IS THE COMPANY LOGO ONLY'), so an agent cannot confuse it with the large create_*_draft / update_*_draft family.

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 when-to-use and how-to-use guidance with named alternatives: Lane 1 directs the agent to call request_attachment_upload (a sibling) and pass its attachmentToken; Lane 2 specifies the exact fallback condition ('if your shell cannot reach taokeh.my... PUT fails 403/blocked') and the parameters to use instead. Scope exclusions are explicit ('It is not the Pioneer program's testimonial artwork'), and the honesty rule states when NOT to file ('Never generate a logo and file it as though they had chosen it').

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