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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the key behavioral fact that no email is sent, the precondition that the invoice must already be finalized, and the return payload (invoice id and marked-sent date). It does not say what happens if the invoice is not finalized (error vs silent accept) or whether repeated calls are idempotent, which keeps it short of a 5.

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?

Four sentences, front-loaded with the primary use case before the exclusion, the parameter note, and the return values. No filler and no repetition of the title or annotations.

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 two-parameter mutation with no output schema, it covers the trigger, the no-op side effect, the prerequisite state, and the return shape. Only the failure mode for a non-finalized invoice is unstated.

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 only 50%, so the description has to carry weight; it explains the optional date's purpose (when it was actually sent on an earlier day) and its YYYY-MM-DD format, duplicating and extending the schema hint. invoice_id is undocumented in both places, though the name is self-explanatory.

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 verb (record) and resource (a finalized invoice as sent) plus the scope qualifier 'by another channel', and explicitly distances itself from send_invoice. An agent can distinguish it from send_invoice or finalize_invoice without opening either schema.

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?

Gives the exact triggering condition (customer was reached via your own email thread, WhatsApp, paper), an explicit exclusion (finalizing does NOT count as sent), and names the alternative that handles the other case (send_invoice records it automatically). Nothing is left to inference.

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