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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful context beyond that: missing buyer context 'fails safely to HOLD,' and the tool never authorizes payment, resolves the supplier, or contacts the Tax Authority. These are concrete behavioral disclosures that help the agent avoid misusing the 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?

The description is compact and front-loaded: it states the value proposition, the concrete checks performed, the failure behavior, the non-behaviors, and the alternative tool in four dense sentences. There is no filler or repetition of schema constraints.

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 21-parameter tool with no output schema, the description is not exhaustive: it does not describe the exact return shape or discuss the meaning of several optional fields. However, required fields are clear from the schema, annotations cover the side-effect profile, and the fail-to-HOLD behavior plus the explicit handoff to authorize_israeli_invoice_payment_paid give the agent enough context to select and invoke the tool correctly.

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 only 19%, so the description carries extra responsibility. It adds high-level meaning by grouping parameters into 'VAT and total arithmetic' and 'date-, amount-, VAT-, and buyer-sensitive' allocation-number checks, and it notes buyer-context behavior. However, it does not explain most optional parameters such as official_verification, contact fields, currency, or language, so the compensation for low schema coverage is only partial.

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 states a specific action and scope: it is a free pre-payment gate that 'Checks VAT and total arithmetic plus date-, amount-, VAT-, and buyer-sensitive Israel Invoices allocation-number applicability.' It also separates itself clearly from the final authorization tool, authorize_israeli_invoice_payment_paid, by naming that tool explicitly.

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?

It clearly positions the tool as the 'FREE FIRST STEP before paying an Israeli tax invoice' and tells the agent when to stop using it: 'Use authorize_israeli_invoice_payment_paid for the registry-backed PAY, HOLD, or BLOCK decision.' It also states exclusions such as not authorizing payment, resolving the supplier, or contacting the Tax Authority.

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