BidBud Estimating

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the description focuses on value-add: it explains the four verdicts and what each implies ('low' means ask what is excluded), and it states what the tool does NOT assess (contractor, workmanship, materials) plus the US-residential limitation. For a read-only comparison tool, that is comprehensive behavioural disclosure.

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 description is front-loaded with purpose, then verdict definitions, when-to-use, limits, and a structured Args block. The length is justified by the 14-parameter schema with zero description coverage, and no sentence is decorative.

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?

Although an output schema exists, the description still explains verdict semantics so an agent can interpret the result directly. Combined with the limits section and full parameter documentation, an agent has everything needed to decide when to call it and how to populate all required and optional fields.

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 all 14 parameters—and it does. Each arg gets a short gloss, including units (USD, square feet), enums and defaults (quality_tier medium, stories 1), conditional relationships (state used when ZIP unknown; year_built before 1978 triggers lead-safe practices) and service-specific fields (flooring_type, num_windows). This adds genuine meaning beyond the bare 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?

The description opens with a specific verb+resource: comparing a contractor's quoted price against BidBud's likely range for the same scope. It clearly distinguishes this from siblings like estimate_project (no quote given) and compare_tiers (comparing quality tiers rather than validating a price). The verdict vocabulary further pins down what the tool produces.

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 gives an explicit when-to-use trigger ('a homeowner has a contractor's price and asks whether it is reasonable') and a scope-limiting section ('judges the price only... US residential homes only; a planning comparison, not an appraisal or a bid'). It does not, however, name the sibling alternative to use when no contractor quote exists, 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 and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it clarifies that tiers reflect typical materials and labor rather than specific products, and that results are planning estimates, not bids — setting expectations about precision that annotations cannot convey.

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?

Structure is front-loaded and purposeful: one-line purpose, then when-to-use, limits, args, returns. Every section earns its place for a ten-parameter tool, and no sentence is redundant filler.

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, yet the description still briefly orients the agent to the return shape (per-tier totals, per-service breakdown, cross-tier totals) without over-explaining. Combined with the limits section and full parameter documentation, an agent has everything needed to call this correctly.

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 documentation burden, and it does: it lists all ten parameters with meaningful constraints (sqft 200-20000, rooms 1-50, 5-digit ZIP, 1/1.5/2/3 stories), notes conditional applicability (flooring_type only for flooring, num_windows only for windows), and explains fallback semantics (state used when ZIP is unknown) plus the 10% contingency value.

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 line names a specific verb and resource ('Price the same project at economy, mid-range and premium quality side by side'), which is immediately distinguishable from a single-project sibling like estimate_project. An agent can tell this is the multi-tier comparison tool without opening the 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?

The 'When to use' block gives a concrete trigger ('what's the difference between a basic and a high-end job?') and the 'Limits' block scopes applicability to US residential homes and planning estimates rather than bids. It does not name a sibling alternative such as estimate_project for single-scenario pricing, so routing against siblings is left partly to 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 establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new context: national cost data with metro/state labor-rate adjustments, the confidence-range nature of the output, and caveats that actual prices depend on site, scope and local market. It also notes condo exteriors may fall to the HOA, a useful behavioral nuance.

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 purpose, then When to use, Limits, Args and Returns — a structure that scales to 18 parameters. It is long, but nearly every line carries decision-relevant information; a few entries (e.g. the closing 'each property detail narrows the likely range') are restatements.

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 complex 18-parameter estimation tool, the description covers scope, estimation methodology, limitations, per-parameter semantics and optional add-ons. An output schema exists, so the brief mention of returns (totals, confidence range, assumptions, follow-up questions) is sufficient rather than redundant.

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 whole burden — and it does: each of the 18 parameters gets meaning, units, valid ranges, defaults, or derived effects (e.g. num_rooms drives wall area, stories drives roof/siding/gutter length, year_built pre-1978 adds RRP practices, roof_pitch steep adds a labor surcharge). This is meaning the bare schema cannot convey.

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?

Opens with a specific verb and resource ('Estimate the cost of one or more home-improvement services for a US home'), and the scope statement (planning estimate, not a bid) distinguishes it from check_quote and compare_tiers without needing their schemas.

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 'When to use' trigger (homeowner wants to know what a job should cost before soliciting bids) plus clear limits (US residential only, one property per call, planning estimate not a bid). It doesn't explicitly name or route against the sibling tools, so it stops short of full alternative 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 cover read-only/idempotent/no-destruction, and the description adds real context beyond them: it discloses that state-level code/authority/licensing content is conditional on the state argument and that results are typical, non-authoritative, and not legal advice. That reliability caveat is the kind of trait annotations cannot express.

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 is front-loaded, then usage, then limits, then a compact Args block for the two parameters. Every sentence does work and nothing is padded, though the prose sentence and the Args block overlap slightly in scope.

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-shape explanation is unnecessary, and the state-conditional behavior plus the 'verify with local building department' caveat covers what an agent needs before calling. The only residual gap is the unmentioned enum constraint on services.

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 has to carry the load, and it does: it explains services is the set of planned jobs with an example list and that state is a two-letter code with an example, plus the conditional effect of supplying state. It omits that services is drawn from a fixed enum (13 allowed values), which the agent must infer from 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?

The first sentence states a specific verb (say whether... needs a permit) plus the resources returned (fees, state code, code authority, licensing resources), so the agent knows exactly what comes back. It does not name any sibling tool (check_quote, estimate_project, list_services) to draw a contrast, which keeps it at a 4 rather than 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?

An explicit 'When to use' clause names the two triggering questions (does a job need a permit, how to check a contractor's license) and the 'Limits' clause tells the agent the output is typical-only and must be confirmed locally. It stops short of naming an alternative sibling for adjacent questions like cost estimation.

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 meaningful scope boundaries: US residential homes only, and only the services listed here. No annotation contradiction.

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 what is returned, then labels usage and limits. Every sentence earns its place with no repetition of schema or annotations.

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?

Given zero parameters, rich annotations, and an output schema, the description provides everything an agent needs to decide when to call it and what scope constraints apply. Return-value detail is appropriately delegated to the output schema.

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 has zero parameters, so there is no parameter semantics to explain; baseline is 4. The description correctly avoids irrelevant parameter detail.

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 and resource: listing the home-improvement services BidBud can estimate, plus the extra catalog dimensions (quality tiers, input ranges, pricing geography). This distinguishes it from estimation or comparison siblings by framing it as discovery/scope checking.

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?

Explicitly says when to use it: first, when unsure whether a job is supported or what details to ask the homeowner for. It does not name alternatives such as estimate_project or compare_tiers, but the usage condition is clear.

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