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

Goes well beyond the annotations (which only declare openWorldHint=true and readOnlyHint=false) by disclosing what the price includes and excludes ('not the whole house - no foundation, finishes or labour on site'), how unspecified inputs are handled ('filled with stated defaults and listed as assumptions'), and that the fabricator is anonymised by region until it takes the job. These are material behavioral traits an agent cannot infer from structured fields.

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-loads the purpose, then usage, example, inputs, price scope, and next step in clearly ordered paragraphs. It is longer than typical, but almost every sentence carries non-redundant information; only the multi-clause opening sentence borders on dense.

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 9-parameter, no-output-schema tool, the description covers what is required vs defaulted, what the returned price represents, the assumption list, the anonymised fabricator, and the hand-off to start_my_project. An agent has everything needed to invoke it correctly and act on the result.

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?

With 100% schema coverage the baseline is 3, but the description adds genuine value: an end-to-end worked example mapping a plain-language request to total_sqft/stories/roof_type/zip, a statement of which fields are strictly needed, and an instruction to ask the user for the ZIP when missing. Defaults are also surfaced (e.g. ceiling height, windows, pitch), though most of these are already declared in 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?

States a specific verb+resource ('price a building in cold-formed steel framing') and scopes it precisely to the steel frame package via the Gage network. It distinguishes itself from both siblings by name, so an agent can route between quote_my_building, submit_design_for_quote and start_my_project without opening any 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?

Explicit trigger conditions are given ('when someone has designed a house, ADU, cabin, garage...and asks what it would cost'), along with a concrete example and an explicit alternative ('If you have exact walls and openings, submit_design_for_quote gives a tighter price'). It also names the follow-on tool and its required argument ('call start_my_project with the quote id').

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