CrewButton

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the trailing 'Read-only' adds nothing. The genuinely useful addition is the disclaimer that CrewButton does not judge prices and that the tool only counts candidate businesses plus a comparison checklist, which sets expectations about what the output is not. Beyond that, no permission, coverage, or rate-limit behavior is disclosed.

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?

It is a single dense sentence that front-loads the audience ('For a homeowner who...') rather than the action, and the colon-clause construction buries the actual operation mid-sentence. Nothing is redundant, but the structure could surface the verb and scope in the first few words.

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 rich annotations, 100% schema coverage, and an output schema that carries return values, the description only needs to explain intent and expectation-setting, which it does: it clarifies that this is a count-and-checklist rather than a price verdict. Adequate for a 2-parameter read tool.

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 100%, with both zip and trade documented including the 5-digit pattern, the trade enum, and the Handyman fallback guidance. The description only restates 'US ZIP code' and 'same job', adding no format or selection detail beyond the schema, so baseline 3 applies.

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 resource: it counts other local businesses near a US ZIP code that can take the same job, and lists what to check when comparing quotes. It is distinguishable from find_local_pros (a listing) by the 'count' framing, though the roundabout phrasing ('CrewButton does not judge prices: this tool counts...') makes the agent work harder than necessary to extract the verb.

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 names the triggering scenario precisely: a homeowner who already has a price and wants to know if it is fair. That is a clear when-to-use condition. It never names find_local_pros or what_to_tell_a_pro as alternatives or states when-not to use it, so routing between siblings still requires inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context beyond that: local businesses reply with prices in writing, the tool returns a link to send the job, and it explicitly does not book anyone or share contact details.

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 core operation and the returned link are front-loaded, and the sentences are efficient. "Local businesses reply with prices in writing" is slightly tangential but still useful context, and nothing is seriously bloated.

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 a rich output schema and full annotations, the description covers what the tool does, when to use it, and the key safety guarantee. It could still be more complete by noting the US-only scope or explicitly differentiating from siblings, but nothing essential is missing 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 100%, and the schema already documents the ZIP pattern and the full trade enum with a Handyman fallback note. The description gives trade examples (plumbing, electrical, HVAC, cleaning, roofing) but does not add syntax or selection guidance beyond what the schema provides.

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 verb and resource: it counts local businesses near a US ZIP code for a given trade and returns a job-send link. That is far more specific than the title alone, but it never names or distinguishes itself from the sibling tools compare_a_quote and what_to_tell_a_pro.

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?

"Use it when someone needs a local pro for a home repair or service" gives a clear usage context. There are no explicit exclusions or named alternatives, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the trailing 'Read-only' merely restates structured data. The added value is modest — the word 'short' signals the response is a compact checklist rather than a long article — but nothing about the checklist's shape or trade coverage is elaborated beyond that.

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?

Two sentences, front-loaded with what is returned and followed by the trigger conditions. The closing 'Read-only' is the one element that spends words on information the annotations already carry, so it falls just short of waste-free.

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 single-parameter, fully enumerated read tool with complete schema descriptions, full annotations, and an output schema, the description covers everything an agent needs: what comes back and when to reach for it. No material gap remains for a tool of this complexity.

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 the trade enum's own description already supplies examples and the 'use Handyman for a general repair' fallback. The description only restates that the trade is an input ('in a given trade'), adding no syntax or selection guidance of its own, so the baseline 3 applies.

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 gives a concrete verb and artifact — it returns a short checklist of details and photos a homeowner should supply so a pro can quote a job, scoped to a given trade. The purpose is unmistakable and clearly distinct in substance from find_local_pros or compare_a_quote, though those siblings are never named.

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 states the triggering intents precisely: when someone asks what to tell a contractor, what a quote needs, or how to describe a repair. That is clear usage context, but it offers no explicit exclusions or pointer to the sibling tools for the adjacent jobs of finding a pro or comparing a quote.

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