Upload Document

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description productively explains *why* a tool called 'upload_document' is read-only: nothing is transmitted to Wint until attach_missing_document runs. That deferred-commitment semantics plus the 10 MB / file-type limits are real behavioral context the annotations cannot express. Return shape is covered by the output schema, so no penalty there.

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?

Three short sentences, front-loaded with the action and its constraints, then the output artifact, then the most surprising fact (nothing is sent yet). No sentence is redundant or padded.

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 zero parameters, an output schema and full annotations, the description supplies everything needed to invoke it correctly and to interpret the upload_id. The only real gap is sibling differentiation inside a set of five upload-named tools, which the description does not resolve.

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?

The tool takes zero parameters, so the baseline is 4; the schema fully closes the object with additionalProperties=false. The description correctly implies the file and its constraints come from an interactive panel rather than from arguments, which prevents the agent from inventing inputs.

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 specific action (open a file-picker panel), the accepted resource types (receipt or invoice, PDF or image), and a hard constraint (max 10 MB), which is far more informative than the bare name 'upload_document'. It partly disambiguates from the family of upload siblings by scoping inputs to receipts/invoices and by naming attach_missing_document, but it never says how it differs from upload_supplier_invoice, upload_other_document or upload_stage.

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?

The description makes the usage context explicit: this is the first step of a two-step flow whose second step is attach_missing_document, with the upload_id as the handoff key. What it omits is any exclusion rule against the three sibling upload tools, so an agent facing a generic upload request still has to guess.

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