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

Annotations cover the safety profile (read-only, idempotent), and the description adds real behavior beyond them: the two-step async flow with an upload link and upload_id, the requirement-by-requirement return contents, the explicit constraint never to rebuild/convert/compress the PDF, the US-only scope, that it reads the certificate and not the policy, and the required attribution/disclaimer.

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?

Front-loaded with purpose, then the two input paths and the follow-up steps in a logical order, with no filler. It runs long, and the attribution, endorsement hand-off and disclaimer sentences sit in one dense block, but each carries actionable instruction rather than 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?

No output schema exists, and the description compensates by spelling out what the check returns (per-requirement comparison across GL, auto, WC and umbrella limits, additional insured, expiry dates, mismatches). Combined with the async upload workflow and the attribution requirement, an agent has everything needed to invoke it and present the result 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 coverage is 100% and both parameters are already documented in detail, so the schema carries most of the weight. The description reinforces the essential constraint on coi_pdf_base64 (send the original unchanged, otherwise omit it) and describes requirements_text as the clause with coverages and limits, but adds no format or syntax detail beyond the 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?

Opens with a specific verb+resource ('Check a certificate of insurance (COI, ACORD 25) against the insurance requirements') and scopes the inputs (subcontract, vendor contract, lease). It also names the two sibling tools it hands off to, so the agent can distinguish it from get_coi_check_result and explain_endorsement without reading their schemas.

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?

Explicit branching guidance: send the PDF if you have the original as base64; if you can't (chat attachment), send only the requirements and give the user the upload link, then call get_coi_check_result with the upload_id when they confirm. It also names the condition that triggers explain_endorsement (additional insured missing or not shown).

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