verify_invoice_balance

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. The description adds valuable context: it self-computes from Lines and allocated receipt/payment lines and deliberately ignores any 'balance' field on the form. This reinforces independence and reliability, though it doesn't cover error handling or permissions.

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?

Two sentences, front-loaded with the core computation. The parenthetical '(its own Lines)' is slightly dense but earns its place by clarifying scope. No filler or repetition.

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?

The description explains the computation method and trust model, and output schema covers return values. However, with 0% parameter descriptions and no usage guidance, the agent lacks key invocation details. Given the rich annotations and simple two-param schema, it's adequate but leaves significant gaps.

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 coverage is 0% and the description never explains the 'resource' or 'key' parameters. An agent must infer that resource is likely 'invoice' and key is an invoice identifier, but no format or allowed values are given. The description fails to compensate for the empty 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?

States a specific computation: invoice total vs. allocated receipt/payment lines, and names the comparison basis. The agent knows it's a balance verification tool, not a generic record fetch. No sibling differentiation is provided, but its unique focus on invoice balance makes it distinguishable.

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?

No indication of when to use this tool versus alternatives like find_broken_invoice_references or get_record. The description explains what it computes but not the scenarios or prerequisites for invoking it. Implied use for verifying invoice balances is the only guidance.

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