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

With no annotations, the description carries the burden and does so well: it discloses that each call replaces the entire fence catalog (a destructive full-overwrite trait the agent must know), and that credentials come from create_contractor_account. It doesn't mention validation failure behavior or whether a partial catalog is acceptable, which keeps it from 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?

Five short sentences, front-loaded with the data-shape explanation, then the guardrail, then the overwrite warning. Almost no waste; the opening 'Loads the contractor's price list' is the only line that could be tightened or made more precise.

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 7-parameter nested write tool with no output schema, the description covers what matters most: the nesting order, gate surcharge model, full-replacement semantics, and the auth prerequisite. Gaps are secondary (error behavior, handling of omitted optional fields) but not blocking for correct invocation.

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 71% and the description largely restates the schema's own 'material -> style -> height -> dollars per linear foot' description. 'Gates are flat surcharges' echoes the per-field schema descriptions rather than adding format or constraint detail, and the optional removal_per_ft_usd 'omit to leave unchanged' semantics and require_phone default are never addressed.

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 the resource (contractor's fence price list) and the shape of the data (rates by material/style/height, gates as flat surcharges). The verb 'Loads' understates that this is a write operation, but the later sentence 'Replaces the whole fence catalog each call' removes the ambiguity. Sibling set_* tools (set_branding, set_hosted_page) are clearly different domains, so no confusion there.

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 a clear operating rule ('Ask the contractor for real numbers; never invent them') and states the prerequisite chain back to create_contractor_account for org_id and setup_claim. It stops short of naming when not to use it or how it relates to get_pricing_terms, so an explicit alternative path is missing.

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