Kolmo Construction

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the grounding workflow (parcel, rules, neighbor activity, municipal code) and, critically, the failure mode: it never fabricates fees or thresholds and falls back to "I don't have that on file" when data is missing. That is high-value behavioral context an agent cannot infer from annotations alone.

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 tight sentences: purpose and pipeline first, anti-fabrication guarantee second, concrete usage examples last. Every sentence adds information with no repetition.

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 annotations covering safety and an output schema covering the return shape, the description only needs to explain scope and behavior — and it does: what it looks up, what it returns (a cited answer), and how it handles missing data. Nothing an agent needs to invoke it correctly 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 coverage is 100%, so the schema already defines both parameters. The description still adds value by clarifying the question types the tool expects and tying them to a specific parcel address, slightly exceeding the baseline for a fully documented two-parameter 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 (answers grounded permit questions) and resource (Seattle-area parcel permit rules), then spells out the pipeline: parcel lookup, jurisdiction rules, neighbor activity, municipal code, cited answer. This clearly distinguishes it from narrower siblings like check_permit_requirements or estimate_permit_fee, which each cover only one step.

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?

Gives concrete natural-language usage examples ('do I need a permit for a 6 ft fence at 123 Main St?', 'what permits does an ADU at this address require?') and scopes it to a specific address. It does not explicitly name when to prefer a sibling tool instead, but the examples make the intended use clear.

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 annotations, the description adds important behavioral context: the data source is public L&I data updated daily, results are ranked closest match first, and an `identified` value of false means multiple businesses match and none should be reported as the contractor. These details materially affect how an agent should interpret and use the results.

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 the core action and scope, then moves through use case, search inputs, and result interpretation. The sentences are informative and appropriately sized, with no significant 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?

Given the simple one-parameter schema, rich annotations, and existing output schema, the description covers what an agent needs: data source and freshness, supported lookup keys, ranking behavior, and ambiguous-match handling. It does not need to explain return fields because the output schema already does that.

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 has 100% description coverage for the single `query` parameter, including examples for license number, business name, UBI, and phone number. The description repeats those identifier types but does not add syntax or formatting details beyond what the schema already provides.

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 verb and resource: look up a Washington State contractor's license, bond, and insurance status using public L&I data. It clearly distinguishes this from sibling permit, business-info, and quote tools by focusing narrowly on contractor license verification.

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 use context — verifying a contractor before hiring — and lists the supported search identifiers. However, it does not explicitly contrast this tool with alternatives such as match_contractor_to_permit or get_business_info, nor does it state when not to use it.

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?

Goes well beyond the readOnly/idempotent annotations: it explains that `verdict` is one of four enumerated values computed from jurisdiction thresholds and parcel overlays, that `depends` returns `verdict.questions` to feed back via `facts`, that `requiresPermit` is a default posture rather than the answer, and that `verdict.separatePermits` lists other required permits. It also discloses the full return surface (timeline, fees, inspections, submittals, source URL).

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 the purpose and verdict semantics before the edge-case discussion of non-project-type work. It is dense but nearly every clause carries operational meaning; the only waste is the `submittals_v2` mention appearing twice (once up front, once restated later).

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 9-parameter, nested-object tool with an output schema and full annotation coverage, the description covers the non-obvious semantics (verdict states, depends-question loop, separate permits, parcel-fact sourcing). What it omits is sibling routing — no guidance on when to use `answer_permit_question` or `get_permit_rule_details` instead.

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 baseline is 3; the description still adds cross-parameter meaning the schema does not spell out as clearly — parcel facts are read from the parcel when `address` is given and should only be passed without one, and `address` overrides `location` for routing. This is incremental value on top of an already thorough schema rather than new information.

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 scoped to three named counties: 'Check whether a residential construction project ... requires a permit.' This is clearly distinct from siblings like estimate_permit_fee, get_permit_timeline, and get_permit_rule_details, which handle fees, timelines, and raw rules respectively.

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?

Provides a concrete trigger example ('Do I need a permit to build a deck in Seattle?') and explains when to pass `address` (to get `submittals_v2`) and how `address` overrides `location`. It does not explicitly say when to prefer `answer_permit_question` or `get_permit_rule_details` instead, leaving that routing to the agent.

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 annotations, the description explains the meaning of each coverage result, how unconfirmed should be treated, and that only out_of_area is a negative result. It also discloses that the tool returns a count of completed projects in or near the location, adding useful behavioral 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?

The description is front-loaded and appropriately sized for a one-parameter read tool. It is slightly dense and includes an ambiguous instruction to 'Follow `guidance`,' but most sentences carry meaningful information.

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?

The tool is simple, has a fully described single parameter, annotations covering safety, and an output schema. The description still adds enough about result interpretation and the project count that an agent can call and use 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 coverage is 100% and the single location parameter already documents accepted examples such as city, neighborhood, ZIP, and address. The description restates those input types but adds no additional parameter-specific syntax or constraints.

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 verb and resource: checking whether Kolmo takes work in a given location. It also defines the exact coverage taxonomy, making the tool's purpose precise and distinguishable from all sibling lookup 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?

It clearly frames the tool as the coverage check for a city, neighborhood, ZIP, or address, and explicitly warns that out_of_area is the only value meaning Kolmo does not take the work. It does not name alternate tools or when not to use this one, but the context is otherwise clear.

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 bar is lower; the description still adds real behavioral value by disclosing the two possible return shapes (numeric breakdown vs. qualitative feeNotes with source URL) and the explicit 'never fabricates dollar amounts' guarantee. It stops short of saying when each mode triggers per jurisdiction, but the core behavior is disclosed.

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 purpose, then the fallback/guarantee. No filler, and the most decision-relevant caveat (no fabricated amounts) is prominent.

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 an output schema present and annotations covering safety, the description is nearly complete; it covers the PDF/spreadsheet fallback. The one gap is that it never warns that zone or areaSqft may be needed for accuracy in some jurisdictions, which an agent reading only the description could miss before calling.

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 the schema descriptions already explain the conditional role of zone and areaSqft per jurisdiction. The description only re-lists the three required inputs, adding no syntax or conditionality beyond the schema, 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?

States a specific verb ('Estimate') and resource ('permit fee') with explicit scope (residential, driven by jurisdiction/project type/valuation). This is readily separable from siblings such as check_permit_requirements, get_permit_timeline, or get_permit_rule_details.

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?

Usage context is only implied: an agent can infer this is the tool for a dollar-figure estimate on a residential project, but there is no explicit when-to-use/when-not statement and no named alternative (e.g., check_permit_requirements for rule questions). The guidance is adequate but leaves routing 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 cover the safety profile (readOnly, idempotent, openWorld), and the description still adds real behavior: the response includes a provenance date ('the date Kolmo read it'), auto-derivation of utility/city/yearBuilt from an address, and a 'check' line that reports a still-missing fact. This is meaningful context an agent could not infer. It does not discuss caching, rate limits, or coverage limits of the rebate list.

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 compact sentences: the first front-loads scope and return content, the second explains address derivation, the third explains the 'check' line. Dense but every sentence carries information, though the phrasing ('what each pays, who must install it') is slightly compressed at the cost of easy scanning.

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 an 11-parameter tool, the description covers the required input path (work), the address-vs-city fallback, and the ask-back loop via the 'check' line, and an output schema exists so return structure need not be restated. The main gap is that several financial inputs (income, household size, project cost) are never explained even contextually.

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 36%, so about half the parameters (annualIncome, householdSize, projectCostUsd, yearBuilt, heating, work) carry no description in either place. The description compensates for the address/city relationship and hints at the `confirmed` loop via the 'check' line, but leaves the income, cost, and heating inputs unexplained. Partial compensation only.

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 exact verb (find rebates) and resource, scopes it geographically and by program (PSE, Seattle City Light, Seattle Clean Heat, HomeWise, WA HEAR), and enumerates the return payload (payout, installer requirements, post-rebate price, source page). This clearly separates it from siblings like get_financing_options or get_project_roi.

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?

Usage context is clear: it operates on a specific job with a required `work` list, and the address/city branch is explained ('An address fills in utility, city and year built', city 'when there is no address'). There is no explicit when-not-to-use or named alternative, 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that the response bundles bio, credentials, expertise, and recent articles, but says nothing about freshness, missing authors, or lookup failure behavior.

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: the return scope is front-loaded and the usage clause follows. No filler, though the second sentence could be trimmed slightly.

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 spelled out, and the description covers purpose plus usage for a single-parameter read tool. Only minor gaps remain around ambiguity resolution when an author name matches nothing.

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 the single 'author' parameter already documents accepted name-or-slug formats with examples. The description adds nothing about the parameter beyond what the schema provides, so 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 (get the biography/credentials/expertise/recent articles for a blog author) and scopes it to Kolmo Construction authors. It doesn't explicitly name a sibling such as get_blog_post or list_blog_posts, so differentiation is left implicit.

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?

Gives concrete usage contexts: answering "who wrote this?" and adding author context to blog content. It offers no exclusions or explicit pointer to the alternative (get_blog_post), 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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds that the returned content is full markdown, which is useful, but it does not discuss missing-slug behavior, publication state, or access constraints.

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 single efficient sentence with the lookup key and output format front-loaded. There is no redundant or wasted wording.

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 simple one-parameter schema, full annotation coverage, and presence of an output schema, the description is nearly complete. A minor gap is that it does not state what happens when the slug is unknown or the post is unpublished.

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 single 'slug' parameter is already documented in the schema. The description's phrase 'by its slug' adds no meaningful syntax or format detail 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?

The description states a specific verb ('Get'), resource ('blog post'), scope ('full markdown content'), and lookup key ('by its slug'). This distinguishes it from list-style siblings such as list_blog_posts and from broader search_content.

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 tool is used when the caller already knows a blog post slug and needs the full post content. It does not explicitly say when to choose this over list_blog_posts, search_content, or get_author_bio.

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, openWorld and non-destructive, so the safety profile is covered. The description adds nothing behavioral beyond that — it restates what the tool returns rather than disclosing anything like data freshness or scope limits, which matters given the openWorld hint.

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 compact sentence with the resource front-loaded and zero filler. The enumerate list is efficient, though it flattens distinct concerns (contact info vs. tools) into a single clause.

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 inputs, a rich annotation set, and an existing output schema that documents the return shape, the description does not need to explain results. The only real gap is the lack of routing guidance among the large sibling set that overlaps with pieces of this payload.

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 is nothing for the description to disambiguate; baseline 4 applies. The listed content areas are effectively the (parameter-less) response surface.

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?

Names a specific verb and resource ('Get Kolmo Construction company information') and enumerates the payload (contact details, hours, service area, specializations, tools), which lets an agent recognize it as the general company-profile tool. It stops short of explicitly contrasting itself with content-adjacent siblings such as check_service_area_coverage or get_service.

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 statement of when to use this tool, when not to, or which sibling to prefer — notably nothing distinguishing the 'service area' string returned here from check_service_area_coverage, or 'specializations' from list_services. Usage must be entirely inferred from the content list.

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, closed-world, non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing data provenance (City public correction letters) and, crucially, the denominator — 'shares are of permits that went to correction' — which prevents misreading the metric.

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 compact sentences: the first states scope and source, the second pins down the metric definition. No filler, and the most misreadable detail is front-loaded before the agent invokes it.

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 covers subject, source, and metric semantics. The remaining gap is how the three optional filters shape the result, which is not addressed anywhere.

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%: zone has an example, subtype has an enum/default but no explanation, and limit has only bounds. The description mentions no parameters at all, so it does not compensate for the gap — e.g. nothing says what zone does when omitted or how limit affects the returned categories.

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 resource (common plan-review corrections on Seattle ADU permits) and what is returned (share of permits per category plus cited code). It is distinctive enough to separate it from sibling lookups like get_permit_rule_details, though it never names an alternative explicitly.

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?

Usage is only implied — an agent can infer this is for diagnosing frequent ADU correction categories. There is no statement of when to prefer it over get_permit_rule_details, check_permit_requirements, or resolve_permit_submittals, and no exclusions.

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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds useful context by stating that the result includes a cost range, material/labor split, duration in days, and line items. It does not explain pricing assumptions, estimate accuracy, or failure behavior, but those are less critical for a read-only calculation 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 first sentence front-loads the core purpose and output, and the remaining dense field lists are structurally grouped by project type. The text is necessarily long for a multi-project estimator, though the wall of field names is harder to scan than it could be.

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 estimator whose schema leaves the project payload open-ended, the description provides the missing per-project-type field guidance, optionality, and references to the tools that define allowed values and material IDs. An output schema exists, so the brief output summary is sufficient.

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?

Although the top-level schema only exposes projectType and a generic project object, the description compensates by listing the required and optional fields for each of the 20 project types, including nested structures, optional markers, and material ID references. It also points to list_project_types for allowed values and get_material_options for material identifiers.

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 verb and resource: a Seattle cost estimate covering range, material/labor split, days, and line items. It also enumerates the project types it supports, making it clearly distinguishable from sibling tools such as estimate_permit_fee, get_project_roi, and get_my_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 intended use is implied by the name and the detailed project-type field lists, but the description does not explicitly say when to use this estimate versus alternatives like get_my_quote or estimate_permit_fee. It also gives no exclusions or prerequisites for invoking it.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered before the description is read. The description adds that figures are 'estimated' monthly payments and includes 'eligibility notes', which is modestly useful behavioral context, but the rest of the return summary duplicates the output schema and says nothing about rate freshness or whether results are static.

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, purpose front-loaded in the first. There is mild redundancy: 'Returns loan types...' is immediately restated by the HELOC/loan/refinance/payment-plan list, which costs a few words without adding information.

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 only two parameters, full schema coverage, an output schema, and rich annotations, the description covers everything the agent still needs: what the tool produces, the geographic scope, and the financing domain. Nothing essential for correct invocation 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 100% and both parameters (projectBudget, creditProfile with its enum) are fully documented in the schema, so the baseline is 3. The description never references either parameter — it does not say that creditProfile defaults to 'good' or how budget drives the options — so it adds no meaning 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 (get home improvement financing options) with an explicit scope (a Seattle remodeling project) and enumerates the concrete instruments returned: HELOC, home improvement loans, cash-out refinance, contractor payment plans. That enumeration cleanly separates it from siblings like find_rebates, get_estimate, and get_project_roi.

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 "Helps homeowners understand how to pay for a remodel" implies the usage context, but there is no explicit when-to-use guidance, no exclusion, and no pointer to the adjacent tools (find_rebates for incentives, get_estimate for pricing) that an agent might confuse this with. 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 declare this as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context: the catalog includes pricing and returns material IDs compatible with get_estimate. It could mention pagination or default result behavior, but the annotations carry the safety profile.

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 compact sentences with no filler. The catalog contents are front-loaded, followed by the filtering hint and downstream compatibility note.

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?

The tool has an output schema, so return values need not be explained in detail, and annotations cover safety behavior. The main remaining gap is the lack of differentiation from the sibling get_material_options, which could affect tool selection.

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 four parameters are already well documented in the schema. The description reinforces category filtering but does not add syntax, default behavior, or other meaning beyond what the schema provides.

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 and resource: browsing the full material catalog with pricing, and it names the categories covered. It does not distinguish this tool from the similar sibling get_material_options, so an agent cannot tell from the description alone which one to prefer.

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 basic invocation hint ('Use category to filter') and notes that returned IDs are compatible with get_estimate. However, it does not say when to use this catalog versus get_material_options or other material-related 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description's added value is the output-consumption contract (IDs feed get_estimate) and the breadth of category coverage, but it says nothing about output shape or ordering — acceptable since an output schema exists, yet not much beyond the minimum.

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 waste. The category list is front-loaded to establish scope, and the get_estimate handoff follows immediately as the actionable instruction.

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?

One fully-documented enum param, an output schema, and annotations covering the safety profile mean the description needs only to establish purpose and downstream wiring, which it does. The remaining gap is disambiguation from get_material_catalog, which an agent may reasonably confuse with this tool.

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 the single parameter has a 20-value enum, so the schema already carries the meaning. The description's category examples ('kitchen/bath/basement/ADU scope tiers, ADA modifications') loosely hint at the enum surface but add no format or selection guidance beyond it — baseline 3 applies when the schema does the heavy lifting.

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 ('Get available material choices') scoped by project type, and enumerates concrete categories (flooring, paint grades, decking, scope tiers, ADA) that make the payload concrete. It does not, however, distinguish itself from the similarly-named sibling get_material_catalog, leaving an agent to guess which one to call.

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?

Gives explicit downstream usage ('Use the returned IDs in the project fields of get_estimate'), which is exactly the kind of routing guidance an agent needs. It stops short of naming an exclusion or alternative — notably nothing says when to prefer get_material_catalog over this tool.

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, so the safety profile is fully covered by structured data. The description's field enumeration largely restates what the output schema already conveys. The only genuine behavioral addition is the 'call before respond_to_quote' sequencing, which is modest given no auth, rate-limit, or failure-mode 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?

Two sentences, zero filler. The resource and its contents come first, and the sequencing instruction closes the sentence as the actionable takeaway. Every clause 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 one-parameter read-only tool with a full output schema, the definition covers purpose, contents, and call timing completely. Return values are already handled by the output schema, and the safety profile by annotations, so nothing an agent needs 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 coverage is 100% and the single parameter already documents itself thoroughly ('The person's kolmo.io/quotes/<id> link, as Kolmo sent it. Never guess one.'). The description's 'the quote Kolmo sent the person' reinforces the parameter's origin but adds no syntax, format, or validation detail beyond the schema. Baseline 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?

States a specific verb (Read) and a precisely scoped resource (the quote Kolmo sent the person), then enumerates the concrete contents (scope, line items, options, total, payment schedule, expiry, acceptability). It contrasts naturally with list-style siblings and names the related action respond_to_quote, so an agent can route to it 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 final sentence 'Call before respond_to_quote' is an explicit sequencing condition that names the alternative/downstream tool and the moment that selects this one. Nothing is left to inference about when this tool belongs in the flow.

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 safety is covered. The description adds useful behavioral context about output: project counts by category, example projects, and typical descriptions, which helps the agent know what it will get back. It does not mention pagination limits or handling of unknown neighborhoods.

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, front-loaded with the core action and followed by return content and use cases. The 'Great for hyperlocal social proof' clause is mildly promotional but does convey intent efficiently.

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 one-parameter read tool with full annotations and an output schema, the description covers purpose, scope, and output shape adequately. Minor gap: it does not clarify whether 'city' means non-Seattle cities (Bellevue is given as an example) or how unmatched neighborhoods are handled.

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 the single parameter already lists example values ('Ballard', 'Capitol Hill', 'Bellevue', 'Queen Anne'). The description restates the same framing ('a specific Seattle neighborhood or city') without adding format, casing, or fuzzy-match rules, so 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: 'See what remodeling projects Kolmo Construction has completed' scoped to a Seattle neighborhood or city. This is clearly distinct from siblings like list_projects (all projects) and get_neighbor_permit_activity (permit activity, not Kolmo's own work).

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?

Provides concrete use-case framing with example questions ('Has Kolmo worked in Ballard?', 'What has Kolmo done in Capitol Hill?'), which tells the agent when this tool fits. It stops short of naming alternatives or exclusions — e.g. when to prefer list_projects or get_project for a specific project's details.

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, open-world, so the safety profile is covered. The description adds real value beyond them: the data source (Socrata city open data), the Seattle-only coverage with the jurisdictionSupported=false failure mode, and that results are anonymized with no addresses.

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 it aggregates and returns, then coverage caveat, then use cases. Four sentences, each carrying distinct information, with no filler beyond a slightly parenthetical sourcing note.

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 needn't be spelled out, yet the description still summarizes them helpfully. Combined with the coverage limitation and anonymization note, an agent has enough to call this correctly; the only gap is the unresolved schema-vs-description jurisdiction discrepancy.

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?

With 100% schema coverage the baseline is 3, but the description adds meaningful constraint context: the address resolves to a parcel and only Seattle-area parcels yield data. There is a mild tension worth noting — the schema says King/Pierce/Snohomish County addresses are accepted, while the description says non-Seattle jurisdictions return an unsupported flag, which the agent must reconcile.

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?

Specific verb+resource with scope (aggregate permit activity within ~1500 ft of a parcel, last 24 months) and it names what is returned (counts, category breakdown, anonymized examples). It does not explicitly differentiate itself from the sibling get_neighborhood_project_activity, which is the one closely-named alternative an agent might confuse it with.

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 to gauge neighborhood activity before quoting an unusual project, or to set homeowner expectations" gives concrete triggering scenarios. It also states the jurisdiction limit (Seattle only, others return jurisdictionSupported=false), but gives no explicit when-not-to-use or named alternative among the many permit 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety basics are covered. The description adds a critical security rule ('Never collect card or bank details') and clarifies that it operates on accepted quotes, which is valuable context beyond the annotations. It does not disclose return format, but an output schema 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?

Two sentences, front-loaded with the key purpose and followed by a clear safety rule. There is minimal waste, though the first sentence is a fragment ('Invoices for...') rather than a complete clause, which slightly reduces clarity.

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 simplicity (one parameter), rich annotations, and presence of an output schema, the description provides sufficient context to call the tool correctly. It could explicitly state that it returns a payment link URL and when to use it over get_my_quote, but otherwise it 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 description coverage is 100%, and the single parameter quoteLink is fully documented in the schema with a warning not to guess. The description adds no parameter-specific information beyond what the schema already provides, so the baseline 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 states that the tool returns invoices for an accepted Kolmo quote, including amount, status, and the payment page. The verb is implicit (returns/retrieves), but the resource and scope are clear. It distinguishes from get_my_quote by focusing on accepted quotes and payment details, though it doesn't name the sibling explicitly.

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 'for an accepted Kolmo quote' implies a usage condition, but there is no explicit guidance on when to use this tool versus alternatives like get_my_quote or respond_to_quote. The rule 'Never collect card or bank details' is a behavioral constraint, 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds genuinely non-obvious semantics by defining `missing` vs `blocked` and warning that `blocked` is NOT evidence the source is gone. It also discloses that data comes from a weekly snapshot pipeline, which sets expectations about staleness. It stops short of stating latency or whether checks run live on request.

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 purpose, then payload contents, then failure semantics, then use cases — a sensible information order with no filler. The enumerated payload list is dense but each clause carries distinct information; only the trailing data-quality page pointer is arguably optional.

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 summarizes the shape of the three returned sections, which is enough for an agent to know what it will get and how to interpret failure classifications. With zero required parameters and full schema coverage, nothing needed for correct invocation 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% and both parameters document themselves, including the default of 5 and the all-jurisdictions behavior when omitted. The description only echoes 'per-jurisdiction' scoping and adds no new syntax or edge-case guidance, so 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+resource ('source-freshness telemetry for the permit catalog') and enumerates the three payloads: per-jurisdiction last-verified dates, source-health rollup, and snapshot-pipeline results. That makes it unmistakable against content siblings like get_permit_timeline or list_permit_jurisdictions, which return permit substance rather than provenance metadata.

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?

Gives concrete triggers: 'Use to answer "how current is this fee/timeline?" or to surface confidence in a permit answer,' and points to the equivalent /permits/data-quality page. It does not state when NOT to call it (e.g., that it is not a substitute for the actual fee/timeline lookup), 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are enriched conditionally when `address` is supplied, pulling `submittals_v2` from the unified resolver. It does not mention auth, rate limits or whether the resolver is expensive to call.

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, front-loaded with the operation and the detail payload, then filtering, then the conditional `address` enrichment. The closest thing to waste is the `submittals_v2` sentence, which repeats what the schema already says about the `address` 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?

An output schema exists, so return values need not be explained, and the description still flags the one conditional shape change (per-rule submittals_v2). What is missing is routing guidance against the crowded set of permit-related siblings, which matters for a tool with five optional filters and no required 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 description coverage is 100%, so the schema already explains limit defaults, keyword scope, jurisdiction slug format, the address-driven submittals_v2 enrichment and the onlyAuthoritative compatibility note. The description largely restates the address/submittals_v2 behavior and the slug-or-keyword filtering rather than adding semantics beyond the schema, so the baseline of 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 opens with a specific verb and resource ("Enumerate permit rules") and enumerates the detail payload: timeline, fee model, inspection sequence, submittals, contractor specialties. That is much clearer than a bare name restatement, but it never distinguishes itself from near-duplicate siblings such as check_permit_requirements, answer_permit_question or resolve_permit_submittals.

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 supplies two concrete example intents ("what does a Seattle ADU permit require?" and "list all rules for a jurisdiction"), which implies when to reach for it. However, the first example is exactly the kind of natural-language question answer_permit_question appears built for, and the description never says when NOT to use this tool or which sibling to prefer.

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 a safe read-only, idempotent, closed-world operation, so the bar is lower. The description still adds valuable edge-case behavior: uncovered cities return the covered list, and groups under 30 permits are suppressed, which an agent could not learn from annotations or 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?

Two tight sentences with the returned metrics front-loaded and the coverage/suppression caveats following. No filler, though the parenthetical metric list is dense and could be split for readability.

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?

The presence of an output schema means return values need no explanation, and the coverage caveat is a plus. However, with four parameters at 25% schema coverage, the description leaves meaningful ambiguity about how subtype and valuationUsd shape the timeline result, so it is only adequately 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 description coverage is only 25% (only projectType has any enum documentation), so the description needs to compensate and does not. It never explains subtype's role, what valuationUsd affects, or that jurisdictionSlug drives the city coverage/suppression behavior, leaving three of four parameters semantically thin.

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 the exact metrics returned: measured days from application to issue, median and 80th percentile, city vs applicant days, and review cycles. That clearly delimits the tool from siblings such as check_permit_requirements (requirements) and get_permit_data_freshness (data recency), though the differentiation is implicit 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?

There is no when-to-use guidance, no exclusions, and no named alternatives among the many sibling tools (e.g., check_permit_requirements, estimate_permit_fee). The reader can infer the tool answers time-to-permit questions, but nothing routes them here versus another tool.

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 read-only, idempotent, non-destructive profile, so the bar is lower. The description adds genuinely useful behavior beyond annotations: what the payload contains (before/after images, testimonial) and the not-found fallback returning available slugs, which the agent cannot infer from annotations or 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?

Two tight sentences: the core action and payload first, the failure mode second. Every clause earns its place and nothing is padded.

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?

A simple single-parameter read tool with a full output schema and complete safety annotations needs little more. The description covers the main payload and the not-found path, leaving only minor gaps such as whether the returned slug list replaces an error or accompanies one.

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?

There is a single 'slug' parameter with 100% schema description coverage. The description only repeats 'by its slug' and adds no format, resolution, or case-sensitivity guidance beyond what the schema already provides, so 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 gives a specific verb and resource ('Get full details for a specific project by its slug') and names the return contents. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like list_projects or get_project_testimonials.

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?

Usage is implied by 'by its slug' and the retrieval framing, but the description never states when to pick this over list_projects or get_project_testimonials, nor any prerequisites. The agent must infer the use case.

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 covered. The description adds genuinely useful non-schema context — the Remodeling Magazine Cost vs. Value source and Pacific Northwest scope — which tells the agent the figures are regional estimates, not live quotes.

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?

Core purpose is front-loaded in the first sentence, with scoping and data provenance following. The trailing marketing phrasing and example questions are slightly redundant but earn their place by showing valid parameter shapes.

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-value explanation is unnecessary. Geographic scope, data source, and intended decision use are all covered; only the ranking/ordering semantics of the no-parameter call are left implicit.

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 the schema itself explains both the projectType examples and the 'omit to see all projects ranked' behavior plus the estimatedCost effect. The description's example queries reinforce usage but add no semantics beyond the schema, so 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: estimated ROI for a home remodeling project, scoped to the Seattle area, plus the underlying data source. It is clearly distinct from cost-estimate siblings like get_estimate or list_project_types, but never names an alternative to route against.

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?

Gives concrete use context ('helps homeowners decide which projects add the most resale value') and two example questions that map directly onto the two parameters. No explicit when-not-to-use or named alternative tool, so it stops 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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only a summary of returned fields, which the output schema already provides, and says nothing extra about auth, limits, or matching fallback behavior. With annotations carrying the load, a 3 is appropriate.

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, front-loaded with purpose and access modes, with the sibling redirect last. The return-fields sentence is largely redundant with the existing output schema, which is the only wasteful element.

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 a true output schema and full annotation coverage, the description needs only purpose and routing, which it delivers. The only gap is that the 'falls back to title match' behavior lives solely in the schema rather than being surfaced in prose.

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 four parameters (limit, keyword, minRating, projectSlug) are already documented in the schema. The description only echoes the 'by slug or keyword' access modes without adding format or edge-case detail. Baseline 3 applies when the schema does the heavy lifting.

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 and resource ('Get customer testimonials tied to a specific project') plus its data source ('from the testimonials table'), and explicitly contrasts with list_reviews for the unfiltered case. An agent can distinguish this from list_reviews and get_project 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?

It names the concrete use case ('source social proof or case-study quotes for a particular job') and routes the agent to the alternative ('For unfiltered reviews, use list_reviews'). The selection condition between the two tools is explicit rather than 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavior: an on-miss fallback that returns available slugs instead of failing, which changes how the agent should handle the response. Return payload shape is left to the 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?

Two short sentences, zero waste, and the core purpose is front-loaded ahead of the edge-case behavior. Nothing could be removed without losing information.

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 an output schema and full annotation coverage, the description need only carry purpose and the not-found contract, both of which it does. It stops just short of richer context such as what a 'residential service' record contains or whether slugs are stable.

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 the schema itself supplies both the format ('URL slug') and an example ('kitchen-remodeling'), so the schema does the heavy lifting. The description only restates that lookup is by slug; it adds no extra semantics such as case sensitivity or partial-match behavior. 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 ('Get full details for a specific residential service') plus the lookup key ('by its slug'). The word 'residential' implicitly separates it from list_commercial_services, but no sibling is named explicitly, so the agent must infer the boundary with list_services.

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 usage context (fetch one service's detail) but never states when to prefer this over list_services, get_material_options, or get_estimate. The only guidance given is a recovery path after a miss, not a selection rule before calling.

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, open world), so the description's extra contribution is the go/no-go evaluation logic based on temperature, rain, and wind thresholds. The hard-coded Seattle locality is disclosed here and appears nowhere in the schema, which is genuinely useful behavioral 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?

Three sentences, purpose front-loaded, then return shape, then use cases — well ordered and short. Minor waste: the enumerated project types largely restate the projectType enum, and the list omits 'windows' and 'interior' values present in the schema.

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 and full annotation set exist, so the description only needs to frame purpose and inputs; it does that and adds the non-obvious Seattle-only restriction. Nothing an agent needs to decide whether to call it 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 100%, so the baseline is 3, but the description adds meaning beyond the enum labels by explaining that suitability is judged against project-specific temperature, rain, and wind criteria — telling the agent why projectType matters rather than just that it exists. The days parameter is left entirely to 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 — check upcoming Seattle weather for exterior construction suitability — and names the concrete output (day-by-day forecast with go/no-go recommendations). No sibling tool overlaps this function, and the fixed Seattle scope is a meaningful disambiguation an agent wouldn't otherwise know.

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?

Gives clear usage context by enumerating the trades it fits (painting, decking, roofing, landscaping, siding, fencing), which maps directly onto the projectType enum. It stops short of stating when NOT to use it or naming any alternative tool or precondition.

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 openWorldHint=false, so the safety profile is covered. The description does add one genuine behavioral fact beyond the structured data: only *published* posts are returned. It says nothing about default page size, ordering, or empty-result behavior, which the schema only partly covers.

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 short sentences, scope front-loaded before the filter sentence. Minimal waste, though the second sentence largely repeats what the schema already says about tag and author.

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 an output schema present, annotations covering the safety profile, and full schema coverage on all four optional parameters, the description is nearly complete. The only remaining gap is ordering/pagination behavior, which the offset parameter partially addresses in the 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?

Schema description coverage is 100%, so every parameter (tag, author, limit, offset) is already documented with examples and defaults. The description merely restates that tag and author are filters, adding no syntax, matching, or combination semantics (e.g. whether filters AND together). 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 ('List') plus the resource ('published blog posts') and even the topical scope (home remodeling, renovation costs, construction tips). That distinguishes it from get_blog_post (single post) and list_blog_tags_and_categories, though neither sibling is named explicitly.

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 tag or author name' implies how to use the filters but gives no guidance on when to reach for this tool versus get_blog_post or search_content. Usage is inferable from the verb 'List' 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 declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope context that it covers only published posts and includes post counts, though it does not discuss pagination or auth requirements.

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, each earning its place: the first states exactly what is enumerated, the second routes the agent to the correct use case and sibling. The purpose and scope are front-loaded before the usage guidance.

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, rich annotations, and an existing output schema, the description provides everything an agent needs to select and invoke the tool correctly. Return values need not be explained because the output schema covers them.

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?

This tool takes zero parameters, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and the description appropriately does not invent unnecessary parameter guidance.

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 ("Enumerate") and names the exact resources (tags and categories) scoped to published blog posts, plus the added detail of post counts. It also distinguishes itself from the sibling list_blog_posts, so an agent can easily tell which tool to choose.

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 explicitly states when to use this tool: to discover topics before calling list_blog_posts or to surface coverage gaps. The alternative sibling is named and the selecting condition is clear, leaving nothing 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results include citable URLs and that slug mode returns a fuller write-up, which is useful return-shape context since an output schema exists anyway. Pagination and truncation behavior are not discussed.

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 listing and filtering guidance is front-loaded and efficient, but the middle sentence is a long certification credential dump (SEDBE #D700031098, SCS #7259, MRSC roster, $350K threshold) that reads as marketing rather than operational instruction an agent needs to call the tool.

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 an output schema present and all four parameters documented in the schema, the description only needs to convey scope and mode selection, which it does. The one gap is that the relationship to sibling `list_services` is never made explicit, leaving the agent to infer which listing to choose.

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 `slug`, `limit`, `offset` and `category`. The description restates the category values verbatim and clarifies that slug narrows to a single full write-up, adding only marginal meaning beyond the schema's own 'One service, with its full description'.

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 ('List commercial construction services') plus what each result carries (slugs, citable page URLs). It implies scope via 'commercial' but never names the sibling `list_services` to draw a line between the two listing 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?

Explains the two usage modes clearly: bulk listing with optional category filter, or 'Pass a `slug` for one service's full write-up.' No explicit when-not conditions or reference to the alternative `get_service`/`list_services` path, but the calling patterns are unambiguous.

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 this a safe, idempotent read; the description goes well beyond them by disclosing payload size (~4K tokens), the response shape ('results keyed by county... each a list of {slug, name, verified}'), and the amplification factor for `detail`. That is exactly the cost/scale information an agent needs before choosing a fan-out option.

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 purpose and default behavior, then the expansion options in the order an agent would consider them. The parentheticals (county list, returned record fields) carry real information rather than filler; no sentence is redundant with the schema.

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?

Despite having an output schema (so return values could be omitted), the description still summarizes the compact shape and gives the cost of broadening it. With zero required parameters and four optional ones, an agent has everything needed to call this correctly on the first try.

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 baseline is 3, and the description earns one above it by explaining what `slug` actually returns ('one jurisdiction's full record (department, fee-schedule URL, phone, code cycles, notes)') and quantifying the token tradeoff for `detail`. `county` and `verifiedOnly` are left entirely to the schema, which is acceptable at full coverage but keeps it off a 5.

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 ('List the jurisdictions in Kolmo's permit catalog') and immediately scopes it with the three concrete counties. It also distinguishes itself from siblings by naming the exact tools whose jurisdictionSlug input this list feeds (estimate_permit_fee, check_permit_requirements, get_permit_rule_details).

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 frames the default (whole catalogue in one call) as the right choice for picking a slug, then gives two named alternatives -- `slug` for one city, `detail: true` for everything -- with a stated cost penalty ('~9x larger') and a recommendation ('prefer `slug` when you need one city'). When-to-use and when-not-to-use are both present.

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, closed-world, non-destructive, so the safety profile is covered. The description adds domain substance beyond that: which code systems exist and that the primary NAICS is 236118 with secondary codes for commercial and specialty trades, which tells the agent what the payload actually 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?

Front-loaded with purpose, then use case, then content detail — sensible ordering with no filler sentences. The long portal roster (OpenGov, MRSC, King County, City of Seattle) is slightly verbose but serves retrieval matching on jurisdiction names.

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?

Output schema exists so return structure needn't be explained, annotations cover safety, and the schema covers the one parameter. The description supplies the business context an agent needs to decide to call it; only minor gaps remain (e.g., whether the code list is static).

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 the single enum parameter is fully documented with its default, so the baseline is 3. The description names the three code systems, implicitly mapping to the enum values, but adds nothing about filtering behavior or what "all" returns.

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) plus a concrete resource (Kolmo's vendor procurement codes) and enumerates the exact code systems returned (NAICS, NIGP, UNSPSC). No sibling tool deals with procurement codes, so an agent can immediately distinguish this from the permit, service, and project 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?

"Use this when vetting Kolmo for gov bids or setting up Kolmo as a vendor" gives a clear triggering scenario tied to portals like SAM.gov and WA WEBS. There is no explicit when-not or named alternative, but the use case is narrow enough that misselection is unlikely.

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, closed-world behavior, so the bar is lower. The description still adds value by disclosing result payload contents (photos and locations) and the breadth of the portfolio. It says nothing about pagination defaults, but the schema covers limit/offset.

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 front-loaded sentences: purpose first, then filtering and the sibling alternative, then category guidance. The long parenthetical of commercial sub-types is dense but functional; nothing is redundant with the schema.

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 two-property mutation surface is trivial. Combined with full annotations and full schema coverage, the description supplies everything needed to call it correctly; only pagination expectations are left implicit.

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 baseline is 3, but the description goes beyond it by unpacking what 'commercial' and 'public-works' actually encompass (tenant improvements, retail/pharmacy fit-outs, municipal work, warehouse renovation) — meaning an agent cannot get from the schema's bare enum-style list.

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 ('List Kolmo's completed projects'), names the two scopes it spans (residential remodels and commercial/public-works), and notes what comes back (photos, locations). It also explicitly separates itself from get_project, 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?

Tells the agent to filter by category or keyword, and explicitly points to get_project for the full case study — a named alternative with a clear condition. It also instructs which category values select the commercial portfolio, though it gives no when-not-to-use guidance beyond that.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The description's one incremental signal is 'all 20', which implies the result is complete and unpaginated. Beyond that it adds little behavioral context, and the output schema already documents the return shape.

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: the what/scope comes first, the when-to-use follows. No filler, no restatement of the title, and nothing an agent must skip past to act.

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 parameterless, read-only discovery listing with an output schema and rich annotations, everything an agent needs is present: what is returned, how many items, and the follow-up tool to call.

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 the baseline is 4. The reference to 'required input fields' describes returned data rather than call-site arguments and does not mislead, but it also cannot add parameter meaning where none exists.

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 ('List all 20 supported calculator project types') and enumerates what the response contains (required input fields and descriptions). The phrase 'calculator project types' cleanly separates it from sibling catalog tools like list_services or get_material_catalog, and the mention of get_estimate anchors its role in the workflow.

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?

'Useful for discovery before calling get_estimate' gives an explicit trigger condition and names the downstream tool, so an agent knows exactly when to reach for it. It stops short of stating when-not to use it (e.g., versus parsing a free-form description via parse_project_description), which is the only gap.

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 this a safe, idempotent read, so the bar is lower, and the description still adds real value by warning that `total` and `averageRating` describe the returned sample rather than the business and by naming `googleProfile` as the authoritative source to cite. That is exactly the kind of trap-disclosure an agent needs; only pagination/ordering behavior is left unstated.

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?

Four short sentences, front-loaded with what the tool returns, then the citation caveat placed where it matters most. The 'Filter by minimum star rating' sentence largely duplicates the `minRating` schema entry and is the one line that doesn't fully earn 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?

With an output schema present and 100% parameter coverage, the description supplies the one thing structured data cannot: the semantic distinction between sample aggregates and the authoritative `googleProfile` figures. Nothing an agent needs in order to call or cite this tool 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 coverage is 100%, including defaults and the ~350 tokens-per-review cost note for `limit`, so the schema already carries parameter meaning. The description restates the rating filter and source combination without adding format or interaction detail, so 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 ('List customer reviews and testimonials') and adds scope: it merges two sources (Google reviews and on-site testimonials) and supports rating filtering. It never explicitly distinguishes itself from the sibling get_project_testimonials, so an agent must infer the split between business-wide reviews and project-level testimonials.

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?

Usage is implied by the mention of filtering by minimum star rating and mixing sources, but there is no explicit 'use this when…' guidance, no exclusion of the project-testimonials sibling, and no note on when to paginate versus take the default sample.

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 annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds the returned fields and keyword search use, but does not add notable behavioral context beyond the annotations and 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?

Two short sentences, front-loaded with the core list operation and followed by the one notable filtering hint. There is no wasted wording.

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 complete parameter schema, annotations, and output schema, the description is largely sufficient for correct invocation. It could still be stronger if it explicitly distinguished this tool from closely related siblings such as list_commercial_services and get_service.

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 mentions using `search` for keyword lookup, but this largely restates the schema and adds no limit/offset guidance.

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: listing residential remodeling services, and it lists the returned fields. The word 'residential' implicitly separates it from list_commercial_services, but it does not explicitly name that sibling or explain the boundary.

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 implies use when you need the full residential catalog and says to use `search` for keyword filtering. However, it does not explicitly state when to use this tool versus get_service, search_content, or list_commercial_services.

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/openWorld, so the safety profile is covered. The description adds real context beyond that: a 30-day cache, geographic scope limited to three WA counties, and provenance rules (which facts carry a source citation and which do not). The offLotFt/screen:true caveats are genuinely useful disambiguation, though they edge into explaining return values that the output schema already covers.

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 the verb, resource, and scope, and the closing routing sentence is well placed. The mid-section caveat about offLotFt/screen:true is compressed into a run-on that takes a careful read to parse, which costs 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?

An output schema exists and annotations are rich, so the description needn't cover return shape, and its coverage of scope, provenance, and sequencing is strong. It is silent on failure modes — what happens for an address outside King/Pierce/Snohomish or an unlocatable parcel — which is the one thing an agent would still have to discover by calling.

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 are fully documented in the schema itself, including the 3–250 char bound, county constraint, and the cache-bypass behavior. The description adds no parameter-level detail (no address format guidance, no discussion of when forceRefresh is worth the cost), so it matches the baseline for schema-does-the-work tools.

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 chain (geocode → resolve parcel) and an explicit return set: zoning, setbacks, overlays, lot area, jurisdiction routing, prior-permit history. It also names the downstream siblings it feeds (check_permit_requirements / estimate_permit_fee), so an agent can place it in the workflow 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?

Gives a concrete triggering utterance ("what can be built at 123 Main St Seattle?") and a sequencing rule relative to two named siblings. No explicit when-not-to-use case or handling for out-of-area addresses, 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 declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds useful behavioral context: it returns qualification status with explicit gap callouts and combines real-time L&I data with Kolmo's permit 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?

Two tightly written sentences with the core action front-loaded. Every clause adds useful information about input scope, output, and data sources, with no repetition or 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?

Given an output schema, rich annotations, and fully described required parameters, the description supplies the remaining context an agent needs: what is cross-referenced, what the result means, and that gap callouts are included.

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 the three required parameters are clearly documented in the input schema. The description adds no parameter-level meaning beyond the schema, so the baseline 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?

States a specific verb and resource: cross-reference a WA contractor's L&I license specialty against a permit's required specialties. It also distinguishes itself from license-status siblings by focusing on qualification for a specific permit and gap callouts.

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 purpose implies when to use it—when checking whether a contractor is qualified for a permit—but it does not explicitly name alternatives such as check_contractor_license_status or check_permit_requirements. No when-not guidance or prerequisite is provided.

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 the description adds real context: it is LLM-backed against a constrained JSON schema, returns a confidence value, and emits a single clarifyingQuestion on ambiguity. That tells the agent to expect non-deterministic parses and a possible follow-up turn, which annotations cannot convey. It stops short of saying what happens on low confidence or provider failure.

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 that lead with the parse target and end with the LLM constraint. The parenthetical field list (kitchen|bathroom|deck|adu|fence|...) is slightly long for the value it adds, but nothing is redundant.

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 needn't be re-explained, and the description still summarizes confidence and clarifyingQuestion, which is the part an agent must act on. The remaining gap is silent on error/degraded-LLM behavior and on how to chain the clarifyingQuestion back into a retry.

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 each parameter already carries an example and rationale (e.g., zoningCode 'from lookup_parcel_by_address'), so the schema does the heavy lifting. The description names none of the four parameters and adds no syntax or format guidance beyond the input being free text. 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+resource ('Parse a homeowner's natural-language project description into structured permit-relevant fields') and enumerates the exact output fields (projectType, areaSqft, heightClass, attached/detached, position, materials). This is unmistakably distinct from sibling tools like check_permit_requirements or get_project.

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 names the trigger ('Use this before calling check_permit_requirements / estimate_permit_fee when you only have free text from the homeowner') and gives the condition that selects this tool over those siblings. The 'only have free text' qualifier is a genuine when-to-use discriminator.

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?

Adds substantial behavior beyond the annotations: confirmation SLA of 1 business day, the crucial state distinction that the booking is 'requested' not 'booked' until confirmed, permitted scheduling windows and lead times, and that dryRun previews. This is exactly the operational context an agent needs before firing a non-idempotent, open-world mutation.

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?

Dense but front-loaded: the action, the proposal constraints, the confirmation state, and the identity fallback all land in one compact block with no filler sentences. The telegraphic phrasing ('pass the person's own name, email, phone, address and scope') reads a little clipped but wastes no words.

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 annotations covering the safety profile and an output schema covering returns, the description carries the timing rules, state semantics, and identity fallback. It does not mention prerequisites such as service-area or license checks that sibling tools exist for, which is a minor gap for an open-world mutation.

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 44% for 9 parameters, but the description compensates well: it explains the quoteLink-vs-identity branch (including that quoteLink substitutes for name/email/phone/address/scope) and adds real constraint detail for proposedTimes (1-5 entries, 24h-60d out, Mon-Fri 8-4 or Sat 9-12 Pacific) that the schema only labels as 'ISO 8601 with offset'.

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?

Specific verb (request) plus specific resource (on-site walkthrough), with the interaction model spelled out (proposals → Kolmo confirms within 1 business day). No sibling tool performs this action, so the agent can route to it unambiguously.

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?

Gives clear conditional guidance: with quoteLink use the link, without it pass the person's own name/email/phone/address/scope, and use dryRun to preview. It doesn't name explicit exclusions or a competing sibling (e.g. submit_contact_request) to use instead, so it stops 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 read-only, idempotent, non-destructive, open-world. The description adds genuinely new behavioral context: each result carries a `fidelity` tier varying by city/scope, with defined values ('full', 'min-viable', 'wa-baseline-stub'), and unverified jurisdictions return 'no-spec'. What's missing is any note on cost/latency of the pipeline or how partial coverage is signaled in the response.

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 the action and resource in the first clause, then the use-case contrast, then the fidelity caveat. Dense but every sentence carries information; the heavy em-dash parentheticals cost a little readability, but nothing is redundant.

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?

Output schema exists, so return structure needn't be described. The description nonetheless covers the one thing an agent must interpret post-call — what `fidelity` means and what 'no-spec' indicates — which is the right allocation of words. Remaining gap is the absence of any scoping note on partial or stale data.

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 six parameters including triggers for envelopeChange, structuralChange, and the SEPA threshold. The description adds only the framing that 'scope' drives provider cataloging and fidelity variance, which is a marginal increment over the schema — 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: 'Resolve the structured submittal-item set for a specific parcel + permit scope,' and names the pipeline it runs through. It explicitly contrasts with the sibling check_permit_requirements, so an agent can distinguish the two 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?

Explicitly says when to use it ('when you need the per-item checklist with triggers, source citations, filler actor, gap-resolution path') and when not to ('not just the rule-level summary that check_permit_requirements returns'). The alternative tool is named and the selecting condition is 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 declare destructiveHint=true and non-idempotent, but the description goes further by disclosing the concrete consequence of each action: acceptance binds the person to work at that total, decline is irreversible, and changes_requested requires notes. This is exactly the behavioral context 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?

Three dense sentences, front-loaded with the core action and consequences, with the acceptance procedure last. No filler; every clause carries distinct meaning.

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 destructive, open-world action tool with an output schema present, the description covers consequences and the accept workflow well, so return values need no explanation. The decline path prerequisites (personConfirmed) are only stated in the schema, leaving a minor gap.

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?

With only 50% schema coverage, the description usefully compensates: it explains the 'response' enum semantics, ties confirmedTotal to the total shown from get_my_quote, and notes that notes is needed for changes_requested. It leaves personConfirmed and selectedOptions unaddressed, but the schema partially covers personConfirmed.

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 (answer/respond) and resource (a Kolmo quote), plus the effect of each response value. It cleanly distinguishes itself from the sibling get_my_quote, which only reads the quote, by naming it as the upstream step.

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?

Gives explicit when-to-use guidance per response value ('accepted' binds, 'declined' is final, 'changes_requested' keeps open and needs notes) and lays out the alternative workflow ('show the person scope, options and total from get_my_quote'). Nothing material is left 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds useful behavioral detail—ranked results grouped by type and a per-type limit—though it does not explain ranking behavior or result caps beyond the 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?

Two tight sentences: the first front-loads what is searched and what comes back, the second handles sibling routing. No wasted words.

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 need not be spelled out, and the description still summarizes grouped ranked results. For a 3-param read-only search tool, this is complete enough, with only minor gaps around ranking/limit behavior.

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%, with all three parameters documented including examples and defaults, so the baseline is 3. The description only restates the single-keyword query and grouped results, adding little parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.