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

Annotations mark this as a non-read-only, open-world, non-idempotent operation; the description earns credit by explaining why – it fires a notification to an external lead router – and by explicitly stating 'Nothing changes on any policy,' which reassures the agent this is not a policy mutation. It discloses what comes back (canopy_connect_url and/or upload_url) and what each link is for. It does not mention whether repeated calls create duplicate leads, which matters given idempotentHint=false.

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 eligibility constraint and trigger condition are front-loaded in the first two sentences, and the return shape follows. The parenthetical explaining Canopy Connect is a bit long and the sentence about carrier/line is tacked on the end, but no sentence is wasted.

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?

With no output schema, the description correctly takes on the job of describing return values (canopy_connect_url, upload_url) and their meaning. It covers eligibility, trigger condition, side effect, and output, which is sufficient for an agent to call this correctly despite the thin schema.

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 0%, so the description carries the burden and only partly does: it defines line values (auto, home, flood, life, other) and carrier ('the other company's name, if known'), and the return-value paragraph implicitly maps to the method enum (canopy / upload / both). The method parameter's default and effect, and the required client_session, are never explained.

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 names the action (bring in an outside policy), the actor (a signed-in client with a policy at another agency not yet linked), and the effect (notifies the Hutsenpiller team via the agency's lead router and returns sharing URLs). It is clearly separable from siblings like request_agent, request_service_change, or get_policy_details.

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?

States an explicit precondition ('signed-in client', 'policy with another agency that is not linked to their account yet') and an eligibility gate ('Current clients only'), plus a procedural rule ('Ask the client before calling'). It does not name a sibling alternative for the adjacent case (e.g., what to use if the policy is already linked or the client is a prospect), which keeps it short of a 5.

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