BidBud Estimating

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses that output is a confidence-band comparison across three quality tiers and explains what each verdict means and implies ("low ... ask what is excluded"). It says nothing about pricing staleness, regional coverage limits or error behavior, which would push it higher.

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?

Purpose, mechanism, verdicts and usage trigger are front-loaded before the argument list, and the 14-argument block is unavoidable given the schema. The second sentence partially restates the first (quality tiers are mentioned twice), a minor redundancy.

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 14-parameter, read-only computation with an output schema, the description supplies everything needed to call it correctly: required inputs are obvious, optional ones are explained, and return semantics are summarized even though the output schema exists.

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% across 14 parameters, so the description carries the entire burden — and it does, annotating every argument with units, defaults and intent (quoted_price in USD, quality_tier default medium, stories default 1, state used when ZIP is unknown, year_built triggers lead-safe practices).

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 opens with a specific verb+resource (compare a contractor's quoted price against BidBud's likely range) and enumerates the four verdicts it can return, so the function is unmistakable. It doesn't explicitly differentiate itself from siblings like estimate_project or compare_tiers, which is the only thing keeping it from a 5.

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 a homeowner asks 'is this bid reasonable?'" gives a concrete triggering context, which is better than implied usage. It names no alternatives or exclusions (e.g., when to prefer estimate_project for a scope with no existing quote), so it stops short of full routing guidance.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds one genuine behavioral detail, that state is used as a fallback when the ZIP is unknown, but the rest is output-shape detail that duplicates the existing output schema.

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?

Purpose and usage trigger are front-loaded before the parameter list, and the Args block is dense but readable. It is slightly long and the Returns sentence partially duplicates the output schema, keeping it from a perfect score.

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 10-parameter pricing tool with zero schema description coverage, the description documents every parameter, its constraints and conditionals, and gives usage guidance. With annotations covering safety and an output schema covering returns, nothing an agent needs is missing.

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 0%, so the description carries the full burden and does so well: it adds value ranges (200-20000 sqft, 1-50 rooms), a concrete example for services, the accepted stories and flooring_type values, default 1 for stories, and conditional semantics (flooring_type only for flooring, num_windows only for windows, state only when ZIP is unknown).

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 opening sentence gives a specific verb (price) and a distinctive scope: the same project across three quality tiers side by side. This clearly separates it from estimate_project or check_quote, though no sibling is named explicitly, so it lands just short of a 5.

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 when to reach for the tool with a concrete trigger (a homeowner asking about basic vs high-end, or wanting to pick a budget level). There is no explicit when-not clause or named alternative, but the usage context is clear enough that an agent can route correctly.

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 readOnly/idempotent/non-destructive, so the safety profile is covered, and the description goes further by disclosing derivation behavior (stories drives roof/siding/gutter areas, pre-1978 adds RRP lead-safe practices, shared walls reduce siding, condo exteriors flagged as HOA responsibility) and the shape of the result (totals, confidence range, assumptions). It stops short of stating numerics like rate limits or precision/rounding 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?

Front-loaded with a one-sentence purpose, then a scannable per-argument list with no repeated or filler text. The remaining sentences — output shape and the note that each detail narrows the range — each add distinct information, which justifies the length given zero schema coverage.

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 18 parameters, no schema descriptions, and an output schema already present, the description fills precisely the gaps an agent needs: argument semantics, required-vs-optional weighting, and behavioral effects of inputs. Nothing needed to invoke it correctly is missing.

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 full burden — and it documents essentially all 18 parameters, including valid ranges (200-20000 sqft, 1-50 rooms), enum meanings ('medium' = mid-range, 'high' = premium), units, defaults, and the downstream effect of each ('Drives roof area, siding area and gutter length'). This is exactly the compensating case where prose must stand in for schema docs.

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 opening sentence gives a specific verb (estimate), resource (cost of home-improvement services) and scope (US home), which is materially clearer than a bare 'estimate' tool. It does not explicitly contrast itself with siblings such as check_quote or compare_tiers, so an agent gets no direct routing signal, but the purpose itself is unambiguous.

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?

The description supplies clear usage context: services are gated per tipic ('For flooring only', 'For windows only'), zip_code is flagged 'strongly recommended', and state is described as the fallback when ZIP is unknown. There are no explicit when-not-to-use rules or named alternatives, 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description usefully adds that output content is conditional on whether a state is provided and that results are advisory guidance rather than legal advice, but it says nothing about data freshness, coverage limits, or failure modes.

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 first sentence front-loads the full payload and the conditional behavior; the Args block is short, labeled, and gives an example per parameter. No filler sentences.

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?

An output schema exists, so return values need not be explained, and the description still previews what comes back. With a simple two-parameter read tool, the definition is essentially complete; only usage routing against sibling tools is absent.

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 must carry the load, and it does: it defines services as the planned services with concrete examples and state as a two-letter US state code with an example, plus the note that state is what unlocks the state-specific code and licensing sections.

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 a specific verb and resource: it tells you whether each planned service needs a permit, with typical fees and, when a state is supplied, the state's code/authority/licensing resources. That is unambiguous and clearly distinct from siblings like estimate_project or check_quote, though it never explicitly contrasts itself with them.

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?

There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives among check_quote, compare_tiers, estimate_project, or list_services. The scoping note 'general guidance, not legal advice' is a liability caveat, not usage guidance.

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, and an output schema exists to describe the return shape, so the description carries little behavioral burden. It adds some value by naming the substantive content (state-level labor pricing, accepted ranges) rather than just repeating 'list', but does not explain ordering, volume, or freshness of the catalog.

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?

A single front-loaded sentence with a tight parallel enumeration of returned content. No filler, no restatement of the title.

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 zero parameters, full annotation coverage, and an output schema to describe the actual return values, the description needs only to say what the listing contains — which it does. Nothing an agent needs to call this correctly is missing.

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?

The tool takes zero parameters, so there are no argument semantics to clarify; the description correctly avoids inventing any. Baseline 4 applies for a no-argument tool.

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 (List) and a clearly bounded resource (the home-improvement services BidBud can estimate), then enumerates the four content areas returned: services, quality tiers, input ranges, and state-level labor pricing. That enumeration distinguishes it from siblings like compare_tiers and estimate_project, which consume this data rather than enumerate it.

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?

The catalog-listing nature strongly implies this is a discovery step to run before estimate_project or compare_tiers, but the description never says so explicitly and names no alternatives or exclusions. Usage is inferable rather than stated.

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