SA Build & Renovation Costs

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context by disclosing the rate basis (rand-per-m² in South Africa) and that fees are applied as optional percentages, but it says nothing about accuracy, assumptions, or what the result contains.

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 tight, front-loaded sentences with no filler, and the core inputs are stated before the optional add-ons. Slight deduction because the second sentence describes a 'municipal plan fees' option that does not correspond to any actual parameter.

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 no output schema and 7 parameters at 14% description coverage, the definition leaves real gaps: three parameters (contingency_pct, include_vat, double_storey) are unexplained and the return shape is never hinted at. The geographic and rate-basis context is helpful but not enough to fully cover the tool's 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 only 14%, so the description must compensate and it does so partially: it explains floor area, quality level, region, and percentage-based fees. It omits contingency_pct, include_vat, and double_storey entirely, and oddly references 'municipal plan fees' which is not a parameter 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?

The description names a specific verb (estimates), resource (construction cost of a new house or extension), and even the method (rand-per-m² rates) and geography (South Africa). The 'new house or extension' scoping implicitly separates it from roof_replacement_estimate and renovation_flip_check, though it never names those siblings.

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 statement of when to use this tool versus the sibling estimators, nor any prerequisites or exclusions. An agent must infer from the resource scope alone that this is for greenfield builds rather than renovations or roof work.

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=true and openWorldHint=false, so safety is covered; the description adds the valuable part — the exact composition of the result (material and labour per line, preliminaries, contingency, VAT, total, likely range in rand) and the currency. It doesn't say how contingency/preliminaries actually feed the total, but this is well above the annotation baseline.

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 dense sentences, input contract first and return contract second, with zero filler. Every clause carries information an agent needs to invoke or interpret the call.

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 no output schema, the description's return breakdown does real work and covers the tool's complexity well; the input side is mostly covered by schema defaults. The remaining gap is the sibling-estimator distinction and the meaning of the percentage parameters.

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 only 33%, so description should compensate more than it does. It clarifies region (South African) and quality level and ties VAT into the output, but says nothing about contingency_pct or how preliminaries_pct interacts with the returned preliminaries line; region ids and item code format remain unelaborated.

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 (prices) and resource (list of building/renovation items) plus the geography (South African region) and quality level. It names list_cost_items as the code source, but doesn't distinguish itself from sibling estimate_new_build or roof_replacement_estimate, so an agent can't tell from the description alone which estimator applies.

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?

Implies usage via the 'by code from list_cost_items' prerequisite, which usefully signals the lookup-then-estimate flow. But there's no explicit when-to-use/when-not versus estimate_new_build or roof_replacement_estimate, leaving the most consequential routing decision 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description earns credit for disclosing the pricing basis (Cape Town, standard quality, excl. VAT), which materially affects interpretation of the returned rates. It omits result-size/pagination behavior, which is the main remaining gap for a listing endpoint.

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, zero filler, with the core payload description front-loaded before the filtering hint. Every clause carries information an agent would otherwise have to guess.

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 no output schema, the description correctly takes on the burden of describing returned fields (codes, units, base rates) and the assumptions behind the rates. For a 2-optional-param read tool this is nearly complete; only result volume and whether rates are per-unit are left unstated.

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% — both parameters already carry descriptions with examples ('geyser', 'tile'; roofing, walls, painting, etc.). The description's 'Filter by category or keyword' merely restates that and adds no matching semantics (substring vs exact, multi-word behavior, AND/OR combination of the two filters). 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?

States a specific verb and resource ('Lists the building and renovation items that can be priced') and enumerates what each record carries: codes, units and base rates. That is well beyond a tautology. It stops short of naming how it differs from the sibling estimators (estimate_new_build, estimate_works, roof_replacement_estimate), so the catalog-vs-calculation distinction is only implied.

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?

'Filter by category or keyword' tells the agent how to narrow results but never says when to reach for this tool instead of the estimator siblings, nor whether it is a prerequisite lookup step for them. Usage is inferable (look up rates before estimating) but not stated.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further by enumerating what the calculation actually consumes — transfer duty and costs, holding costs, agent commission — and, with no output schema present, names the three returned figures, which is genuinely additive context.

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 dense sentences: the first front-loads the deal type and the cost stack, the second delivers the returns. No filler, no restatement of the title, and the most decision-relevant output (max offer) lands last for emphasis.

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 7 parameters, no output schema and only minimal annotations, the description does enough work to make the tool callable: it names the cost components and the returned metrics. What's missing is the holding period semantics, the default assumptions (1% holding cost) and any caveat that transfer duty is a SA-specific calculation — relevant for an agent judging whether results are trustworthy.

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?

At 57% schema coverage the description meaningfully complements the schema: it ties target_margin_pct to the 'maximum sensible offer' output and clarifies that selling cost means agent commission and that holding costs are modelled over time. It doesn't explain the holding cost default of 1% of purchase price or what months_held governs, leaving one parameter effectively unaddressed.

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 specific verb+resource ('Checks a buy-renovate-sell deal') plus the exact analytical output (profit, margin, max offer), which clearly separates it from the estimation siblings. It stops short of naming estimate_works or estimate_new_build as the tools that feed it, so sibling differentiation is implied by domain rather than stated.

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 phrase 'buy-renovate-sell deal in South Africa' implies the scenario, and the required trio of inputs sketches a use case. But there is no explicit 'use this when...', no exclusion ('not for new builds — use estimate_new_build'), and no mention of scope limits such as single-property vs portfolio.

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=true and openWorldHint=false, so the description doesn't need to restate safety. It adds genuinely new behavioral context: prices come from current supplier data that a human has checked and approved, and each line carries the supplier and price date — provenance an agent needs for trust and attribution. It doesn't say how stale prices can get or what happens if no approved price exists.

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?

One dense sentence delivers scope, line items, and pricing provenance; a second short sentence handles routing. Front-loaded with what the tool returns, and nothing is repeated from the 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?

No output schema exists, and the description compensates by describing the return shape (per-line supplier and price date, enumerated material components). Safety is covered by annotations, and the alternative is named, so nothing an agent needs to select or 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?

Schema description coverage is 100%, so all five parameters (including the profile enum and the sloped-area clarification) are already documented; a 3 is the baseline. The description adds only indirect meaning — that ridge_m yields ridge capping and include_labour yields a per-m² labour rate — without new format or constraint details.

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 (material list and cost for a roof replacement in IBR/corrugated steel sheeting), enumerates the line items produced (sheets, screws, ridge capping) and the pricing basis. It also explicitly names the sibling it is not ('Use estimate_works for an all-in installed rate instead'), so an agent can route without opening a 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?

Explicitly gives the alternative tool and the condition selecting it: use estimate_works when an all-in installed rate is wanted, this tool for a priced material list. That is a real routing rule. It stops short of stating negative conditions (e.g. that this is materials-only, not a quote, or when ridge_m/gauge_mm should be supplied).

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?

The description adds real context beyond the annotations: 'Free to call' signals no call-budget cost, and 'We review these every week and build the most-requested data first' discloses that this is an asynchronous request with no immediate data returned. Nothing contradicts readOnlyHint=false (a submission does create a record) or openWorldHint=false; auth and rate-limit details are absent but low-risk here.

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 the cost signal and then the qualifying condition, then the outcome. No restatement of the tool name and no wasted clauses.

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 fully documented, no-output-schema submission tool, the description covers purpose, trigger and what happens after submission. It could be slightly more complete by stating that no data is returned synchronously, but the weekly-review sentence conveys that implicitly.

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%, so the schema already explains need, region and context fully. The description reinforces the one-sentence constraint on the required field but adds no meaning beyond the schema for the optional region and context parameters, 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 states a specific action (describe a missing data need) and resource (South African cost, rate, rule, price or place not covered), and explicitly frames itself as the fallback when the sibling calculators don't cover a need. It is immediately distinguishable from bond_repayment, municipal_rates and the other siblings, which are lookups rather than submissions.

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 a clear trigger: use this when needed South African data is not provided by 'none of these tools,' and enumerates the kinds of gaps that qualify. It does not name the specific sibling domains, so an agent still has to reason about what the siblings already cover before deciding to fall back here.

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