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 readOnlyHint and idempotentHint, and the description adds valuable behavioral detail beyond them: it discloses exactly what data is returned ('name, license where the state publishes one, job count...') and explains the ranking meaning ('by volume on the public record, not quality or reviews'). 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 three sentences with no filler. The first sentence states the core purpose, the second lists the output fields, and the third clarifies the ranking basis. Every sentence earns its place and the most important information is front-loaded.

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 read-only tool with 3 parameters and no output schema, the description is quite complete: it names the return fields and clarifies the ranking criterion. It does not mention response format or how the 'limit' parameter affects the output, but those are sufficiently covered in the schema and the description's field list gives an agent enough to use 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning to the parameters beyond what the schema already documents; it only implicitly references 'this kind' and 'their city permit record,' which are already explained in the parameter descriptions. No extra compensation needed.

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 and resource: 'Contractors ranked by how many jobs of this kind their city permit record shows.' It clearly distinguishes this tool from the sibling 'search_contractor_records' by focusing on ranking by permit volume rather than general search, and it lists distinct output fields (name, license, job count, etc.) that define its identity.

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 clear context on when to use this tool: when the agent needs a ranked list of contractors by public permit volume. It also gives a specific when-not: 'not quality or reviews.' However, it does not explicitly name sibling alternatives or state conditions for choosing them, so it falls 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 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: it names the data source ('dates on city permits'), mentions the number of permits and date coverage, and discloses that final-inspection times only count finished jobs. This is useful nuance that annotations do not 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 compact and front-loaded with the core measurement, followed by a single important caveat. Both sentences carry distinct value with no filler, making it easy for an agent to parse quickly.

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 two-parameter, read-only tool with high schema coverage and a descriptive title, the description covers the data source, the computed intervals, sample size, and a key methodological exclusion. Since there is no output schema, slightly more detail about the exact return shape would be useful, but the core calling context is complete.

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%, and both parameters already have enum values and descriptive text. The description does not add parameter-level detail, but with the schema handling the meaning of city and kind_of_work, a baseline score of 3 is appropriate.

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 specifies the tool's output: days from permit application to issue and from issue to final inspection, plus permit counts and date coverage. It identifies a concrete resource (city permits) and scope, though it lacks an explicit verb like 'calculate' or 'return' and does not explicitly compare itself to sibling tools.

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 guidance on when to use this tool versus alternatives like project_cost or solar_estimate. The description implies its purpose through the title, but it never states conditions, exclusions, or sibling routing, so an agent has to infer the appropriate context.

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 covered. The description adds useful context about ZIP-level availability ('where the site publishes one') and clarifies the data source (city permit value vs price paid). However, it doesn't disclose behavior like missing data handling, date ranges, or response format, which would be valuable for a data lookup tool.

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 compact and front-loaded: it states the core output (median and middle half of job value, permit count, dates) in the first sentence, then clarifies the ZIP behavior and the value definition. Every sentence earns its place, and there is no redundant repetition of schema details.

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 read-only lookup tool with 100% schema coverage and no output schema, the description covers the key aspects: what is returned, how ZIP filtering works, and the definition of the value. It could mention what happens when no data exists for a city/kind_of_work combination, but overall it is sufficiently complete for an agent 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 100%, so the schema already documents all three parameters. The description adds meaning by explaining that zip is optional and only used where the site publishes a ZIP-level figure, and that kind_of_work refers to the permit's stated work type. This is helpful but not extensive; the schema already carries the parameter definitions.

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 purpose: it returns the job value stated on city permits for a given kind of work, with median and middle half statistics, permit count, and dates. It distinguishes itself from siblings by focusing on permit value statistics rather than timelines, contractors, or estimates.

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 explains that a ZIP is needed to get a ZIP-specific figure where the site publishes one, and clarifies that the value is the city permit's stated value, not the price paid. It doesn't explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to select this tool for permit value queries.

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.