contractors.fyi

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

Annotations declare a safe read-only, idempotent operation, and the description adds meaningful context beyond that: the exact data source (Berkeley Lab records), scope (homeowner-owned, no battery, before incentives), and the shape of the result. No contradiction with the annotations is present.

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 entire behavior is conveyed in one dense sentence with no filler, and the most important comparison logic is front-loaded. The parenthetical list of filters is efficient, though the phrasing is slightly awkward.

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 only moderate complexity, the description carries the full burden of explaining return content, and it does: percentile, local typical price/range, and price per watt. Combined with the schema's bounds and enum, an agent has enough to select and invoke the tool 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?

Two parameters already have schema descriptions (kw, price), and the description adds the key relational meaning: city defines the comparison group, kw defines the size match, and price is the quote being evaluated. This is useful context beyond the schema, though it does not spell out per-parameter syntax.

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 precisely defines what the tool computes: where a given quote price falls relative to same-city, same-size homeowner purchases, and enumerates the outputs (percentile, typical price/range, price per watt). This makes it clearly distinct from sibling tools like solar_estimate or project_cost, which estimate costs rather than benchmark a specific quote.

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 use case (benchmarking a quote against local Berkeley Lab market data) is implied by the description, and the filters are clear. However, it does not explicitly state when to use this tool instead of alternatives such as solar_estimate or project_cost, nor does it mention exclusions beyond the embedded data filters.

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 the safe read-only, idempotent, closed-world profile, so the bar is lower; the description adds real value by disclosing the ranking methodology and the data-coverage caveat that licenses appear only 'where the state publishes one.' It does not describe empty-result or pagination behavior, keeping it short of a 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?

Two sentences, zero filler, ranking semantics front-loaded and the return-field inventory placed second where it is most useful. Every clause carries information an agent needs.

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, enumerating the returned fields (name, license, job count, typical value, ZIPs, profile URL) is exactly the right compensation, and the license-availability caveat prevents over-reading the data. It stops short of noting result limits or behavior when no contractors match.

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% and both enums plus the limit bounds are fully documented in the schema, so the baseline is 3. The description only loosely gestures at 'this kind' and 'city permit record' without adding format or selection guidance beyond 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 and resource ('Contractors ranked by how many jobs of this kind their city permit record shows') and pins down the ranking basis. This clearly distinguishes it from the raw-record sibling search_contractor_records, which the agent can infer 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?

The description implies the use case (find contractors for a given city and kind of work) and warns that ranking is by volume 'not quality or reviews,' but never says when to prefer this over search_contractor_records or check_solar_quote/permitting siblings. 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.

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

Annotations already mark the tool read-only and idempotent, and the description adds behavioral nuance beyond that: it uses typical appliance figures rather than exact loads, applies a 10% spare factor, and counts running watts plus the largest motor's starting wattage. The explicit limitation about electrician load calculations is useful. No contradiction with annotations.

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 only two sentences and front-loads the primary sizing purpose. However, the second sentence is structurally tangled: 'what generator permits stated as job value, by size, where a city has enough of them' is hard to parse and does not earn its place as cleanly as the first sentence.

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?

There is no output schema, so the description carries the burden of explaining results; it names generator size and permits but omits units, output format, and how the permit value relates to the loads input. The phrase 'where a city has enough of them' is incomplete given that the only parameter is a loads array, leaving an agent to guess part of the expected response.

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 schema already documents the loads array and its enum, so the baseline is 3. The description adds meaning by explaining that these loads represent outage must-runs and that the sizing method combines running watts with the biggest motor's starting watts, which helps an agent reason about appropriate enum selections.

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 identifies the core output: the smallest common home standby generator size with a 10% safety margin for outage-critical loads, and it mentions generator permit values by size. This differentiates it from siblings like permit_timeline and project_cost, though the second clause 'where a city has enough of them' is grammatically vague and weakens precision.

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 establishes a clear context: use this tool to size a standby generator for the appliances that must run during an outage. The closing caveat 'an electrician's load calculation beats them' tells the agent the result is a rough estimate and should not replace a professional calculation, though it does not explicitly name sibling alternatives.

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 the safe, read-only, idempotent nature of the call. The description adds value by disclosing that the output includes coverage dates and that it serves as the source of valid enumerations for other tools, which is useful behavioral context beyond the annotations.

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 with no filler. The first sentence states the core output and scope; the second sentence provides actionable usage guidance. Everything earns its place.

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 simple, parameterless discovery tool with annotations covering safety, the description fully explains what the agent will get and when to use it. No output schema is present, but the described return content is sufficient for the agent's decision-making.

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 input schema has zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because no parameter information is needed here.

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 uses a specific verb ('covers'/'list') and identifies the exact resource: cities, kinds of work, and the dates each list covers. It also marks itself as the preliminary discovery tool distinct from the sibling tools that consume these values.

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 instructs the agent to call this tool before the others to obtain valid city and kind_of_work values. This is clear when-to-use guidance that routes the agent correctly relative to all sibling tools.

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 safety is covered. The description adds genuine methodological context beyond that: results are derived from permit dates, include permit counts and the date range covered, and final-inspection timings only count completed jobs — a real sampling caveat an agent would not otherwise know.

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 sentences with no filler, and the primary output (the two durations) is front-loaded. The phrasing is slightly convoluted, but every clause earns its place by describing either the metric or its 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 no output schema, the description must describe the return payload, and it does: two duration figures plus permit counts and the dates covered. Combined with 100% schema coverage for the two required params and annotations carrying the safety profile, an agent has what it needs.

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% with both parameters enumerated and documented, so the schema carries parameter meaning fully. The description adds nothing about parameter format or constraints, which is the expected baseline when the schema does the work.

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 the two computed durations (application→issue, issue→final inspection) and the source (dates on city permits), which is specific enough to distinguish it from siblings like project_cost or solar_estimate. It is framed as a metric description rather than a verb+resource action, but the resource 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The only routing hint ('City id from list_coverage') lives in the schema parameter description, not the tool description, so an agent gets no help choosing between this and the cost/estimate siblings.

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 readOnly, idempotent, non-destructive behavior, so the bar is lower; the description still adds source-of-truth context ('the value stated on the city permit, not the price paid') and a conditional-coverage caveat for ZIP-level results. It does not discuss refresh cadence or how many permits are needed before a figure is published.

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?

Three sentences, all load-bearing, with the core output description front-loaded before the optional-ZIP note and the source caveat. The opening clause ('What city permits for this kind of work stated as the job value') is slightly awkward to parse, costing a point.

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 carries the return-value burden and does so: median, interquartile ('middle half'), permit count, and dates. Combined with the required-parameter list and enum schema, 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 coverage is already 100%, so the baseline is 3, but the description adds real semantic value: the ZIP argument is only meaningful 'where the site publishes one', and the returned figure is explicitly the permit-stated value rather than a market price. That meaning is not 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 states a specific resource and measurement ('city permits... stated as the job value: median and middle half, with the number of permits and their dates') plus the source semantics ('the value stated on the city permit, not the price paid'), which implicitly separates it from the quote/estimate siblings. It never names a sibling or an alternative tool, so it stops 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?

'Give a ZIP to get that ZIP's figure where the site publishes one' is a real usage instruction for the optional parameter, including a coverage caveat. However there is no guidance on when to prefer this over check_solar_quote, solar_estimate, or permit_timeline, so the when-to-use decision is only implied.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable context: it searches the permit record (not a license verification) and covers 'every city covered', which clarifies scope and limitations beyond what annotations provide.

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 two sentences with zero filler. The main action and scope are front-loaded, and the limitation is stated clearly in the second sentence. Efficient and well-structured.

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 simple single-parameter read-only tool with annotations, the description is nearly complete. It states the returned fields (city, jobs count, profile URL) and the key limitation (no license verification). It does not describe pagination or result count, but these are not critical for such a straightforward search.

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%, so the single parameter 'name' is fully documented in the schema with description 'Business name or part of it'. The description merely restates this ('by business name') without adding format, syntax, or edge-case details. Baseline of 3 is appropriate given high schema coverage.

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 clearly states the verb 'look up' and the resource 'contractor by business name', and specifies the returned fields (city, permitted jobs count, profile URL). It is specific and unambiguous, though it does not explicitly differentiate from sibling tools like find_contractors, which might perform a similar search.

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 provides no guidance on when to use this tool versus alternatives. It only clarifies a limitation ('does not verify a license today'), which is a behavioral note rather than usage routing. No exclusions or alternative tool names are mentioned.

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, covering safety. The description adds valuable behavioral context: it discloses that output figures are 'rough city figures,' specifies the data source (Berkeley Lab records), and clarifies exclusions ('before any tax credit, no battery'). It also explains the fallback logic for inputs (bill, kWh, or home details). These details go beyond the annotations and help the agent understand approximation and scope.

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 a few sentences but packs substantial information without redundancy. It front-loads the core purpose ('Size a home solar system') and then details inputs, outputs, and caveats. Each clause contributes unique information (inputs, add-ons, price source, exclusions, rough figures). It is appropriately concise for a tool with 8 parameters, though it could be slightly more structured with bullet points, but the current flow is logical.

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 the tool's complexity (8 parameters, no output schema), the description is quite complete. It explains what outputs to expect (price range, savings, payback, per kW, heating/cooling use, default price) and clarifies limitations (rough city figures, no battery, pre-tax credit). It also covers the input fallback logic. The only missing element is a detailed description of the return format, but since there is no output schema, the description adequately covers what the agent needs to know to invoke it 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 75%, so the schema already documents most parameters. The description adds semantic meaning by explaining how parameters interact: the fallback from monthly_bill to monthly_kwh to home_size/uses, and the inclusion of electric_cars as an add-on. This clarifies the relationship between parameters beyond their individual descriptions, adding value over the schema. It does not repeat schema details but explains the decision logic.

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 clearly states the tool's function: size a home solar system from various inputs (bill, kWh, home details) and output price range, savings, payback, and per-kW figures. It specifies the resource (home solar) and the action (sizing and estimating costs), making it distinct from sibling tools like check_solar_quote or project_cost. The verb 'size' and resource 'home solar system' are explicit, and the description covers the full scope of what the tool does.

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 implies the use case—when you need to estimate solar system size and costs—but it does not explicitly state when to use this tool versus alternatives. It neither names sibling tools nor provides exclusionary conditions (e.g., 'use this when you have a bill, otherwise use X'). The context is clear from the content, but guidance on choosing among alternatives is absent, so it falls short of explicit usage guidance.

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