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

Annotations already establish this is a safe, idempotent, non-destructive read, so the description only needs to add behavioural context and it does: it discloses that output is a priced quote with line items, that rates are 'indicative for one experienced decorator', and that prep level/set-up and clean-up time are baked in. It does not cover accuracy caveats or how multi-decorator scaling affects duration, which keeps it below 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?

The key purpose is front-loaded in the first clause, but the sentence then becomes a single run-on containing a long parenthetical list of nine extra-task enum values that merely duplicates the schema and hurts scannability. The example JSON earns its place; the enum recitation does not.

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 an 11-parameter tool with nested objects and no output schema, the description covers what the call produces (hours, days, priced quote lines), the inputs' intent, and a concrete example request. What's left vague is the pricing path — how day vs hourly rate, markup and VAT interact — though the schema carries most of that.

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 91%, so the schema already does most parameter documentation and baseline is 3; the description still adds meaning beyond it by mapping new_plaster to mist coats, framing prep levels as light/medium/heavy work categories, and enumerating the extra-task vocabulary that drives custom additions. The worked example JSON also clarifies how rooms, prep_level and day_rate_gbp combine, which the schema alone does not show.

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 pair: computes on-site hours/days and a priced quote for a decorating job, and names its inputs (rooms, extra tasks, prep level, rates). It also explicitly ties itself to the sibling paint_quantity by saying it takes 'the same sizes as paint_quantity', which lets an agent separate it from the paint-amount tool without opening either 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?

Usage is implied rather than stated: an agent can infer this is the labour-plus-pricing tool and paint_quantity is the paint-volume tool, and the description notes that supplying a day/hourly rate and materials turns the estimate into a priced quote. However, there is no explicit when-to-use/when-not guidance, no statement about whether to call paint_quantity first, and no mention of the trade_profile sibling even though trade details feed quotes.

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