Update a receipt

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds the endpoint method 'PUT' which subtly suggests full replacement semantics, but it does not explain whether omitted fields are cleared, whether the receipt must already exist, or what happens on update. No contradiction with annotations exists; the description is neutral but does not significantly enrich behavioral context.

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 very short—three short phrases—but it includes redundant lines: 'Update a receipt.' and 'Update an existing receipt.' say essentially the same thing. The endpoint header adds slight structural value, but the redundancy wastes a sentence. Overall it is concise but not optimally structured; the key detail (PUT endpoint) is placed last.

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?

There is no output schema, and annotations cover basic operation traits, but the description does not specify return values, error cases, or side effects. Since it is a simple update tool with a well-described schema, an agent can probably proceed, but it lacks important context like what fields may be omitted, whether partial updates are allowed, and the response format. This is adequate but not complete.

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 schema covers 67% of parameters with descriptions, and the description itself adds little beyond the schema. However, the schema clearly documents the id and body, and the nested ReceiptInput properties include descriptions and examples. The description emphasizes 'existing receipt', reinforcing that the id refers to an existing resource. Although the description does not compensate fully for the 33% gap, the schema itself is fairly descriptive, so the parameter semantics are adequately conveyed.

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 clearly states 'Update an existing receipt' and references the REST endpoint 'PUT /receipts/{id}', which identifies the resource and operation. It distinguishes from siblings like create_receipt and get_receipt through the verb 'update', though it does not explicitly name alternatives. The title 'Update a receipt' reinforces clarity, but the description is somewhat terse and duplicates the title.

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 offers no explicit guidance on when to use this tool versus alternatives such as create_receipt or update_purchase_invoice. It only states the action, leaving the agent to infer usage from the endpoint pattern. There is no mention of prerequisites, typical scenarios, or exclusions, so an agent receives minimal guidance.

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