kolmo-mcp-server

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

Beyond the readOnly and idempotent annotations, the description discloses a key behavioral guarantee: it never fabricates fees or thresholds and falls back to 'I don't have that on file.' It also explains the grounding sources and the cited-answer format, all of which are useful and non-obvious behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler: the first sentence establishes purpose and behavior, the second adds the honesty constraint and usage examples. The critical context is front-loaded, and every phrase contributes to correct invocation.

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 readOnly annotations, full schema coverage, and the presence of an output schema, the description is complete. It tells the agent what the tool does, when to use it, how it behaves when data is missing, and what kinds of questions are appropriate. No critical information 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% for both parameters, so the baseline is 3. The description adds value by clarifying that questions should be natural language and providing concrete examples for both the address and question inputs, reinforcing how the parameters should be phrased.

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: answering grounded permit questions for a specific Seattle-area address. It also details what the tool does internally (parcel lookup, jurisdiction rules, municipal code, neighbor activity) and clearly differentiates itself from siblings like check_permit_requirements or estimate_permit_fee by emphasizing cited natural-language answers.

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 explicitly states when to use the tool: for natural-language permit questions, and gives two concrete example prompts. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to route ordinary Q&A here rather than to fee-estimation or requirement-checking 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavior beyond that: it relies on public L&I data, is updated daily, and works for any WA contractor, not just internal entities. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded, and free of unnecessary structure. There is minor redundancy: 'license, bond, and insurance status' is restated as 'licensed, bonded, and insured,' but overall it 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?

With one required parameter, 100% schema coverage, a rich annotation set, and an output schema present, the description covers the essential context: data source, freshness, scope, and use case. Nothing critical is missing for an agent to invoke this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema fully documents that query accepts a license number or business name. The description adds no additional parameter-level detail, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Look up any Washington State contractor's license, bond, and insurance status using public L&I data.' It clearly distinguishes itself from permit-focused siblings like check_permit_requirements and match_contractor_to_permit.

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 gives a clear use case: 'Great for verifying a contractor before hiring — checks if they are licensed, bonded, and insured in WA.' This tells an agent when to use the tool, but it doesn't explicitly name alternatives or exclusions, 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 readOnly/openWorld/idempotent, and the description adds substantial behavioral context: it returns timeline, fee notes, inspection sequence, required submittals, and an official source URL, prefers jurisdiction-verified rules, and discloses the Seattle SDCI fidelity vs wa-baseline-stub distinction. This gives the agent a reliable picture of what the call will produce.

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 dense but efficient: it front-loads the core action, then gives return contents, usage examples, address behavior, and fidelity caveats. Every sentence adds decision-relevant information, and no content is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's 8 optional parameters, rich output schema, and sibling ecosystem, the description covers return contents, jurisdiction routing, address-triggered submittals, fidelity caveats, and concrete invocation examples. Nothing essential for selecting or calling 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%, so the baseline is 3. The description adds extra semantic value by explaining that `address` triggers `submittals_v2` from the unified resolver and overrides `location` for jurisdiction routing — information not fully present in the schema. It does not need to repeat each parameter since the schema already documents them.

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: 'Check whether a residential construction project... requires a permit.' It also scopes the geographic coverage (King/Pierce/Snohomish counties) and gives concrete example queries that make the tool's purpose immediately distinguishable from broader siblings like answer_permit_question.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use examples: 'Use for "Do I need a permit to build a deck in Seattle?"...' This gives clear context for when to invoke it. It does not explicitly name alternatives or state when not to use it, so it stops short of full exclusionary 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 mark the operation as read-only and idempotent. The description adds meaningful behavioral context beyond the annotations: the three-valued verdict ('yes/no/nearby'), the matched service city, and the completed-project count. This gives an agent clear expectations for the tool's output without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff. The first sentence leads with the action and scope, the second describes the return values, and the final clause gives the intended use case. Every sentence 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?

This is a simple one-parameter lookup with strong annotations and an output schema. The description provides the necessary coverage confirmation context and return-value semantics without requiring extra prerequisites or edge-case handling.

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 already explains the 'location' parameter with examples. The description essentially repeats the field meaning and adds only the regional scope, so it does not need to compensate for a documentation gap. 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 a specific action ('Check whether Kolmo services') with a concrete resource and geographic scope ('a given city, neighborhood, or ZIP in the Seattle / King County area'). It also names the return values, making the tool's function unambiguous and easily distinguishable from 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?

The description explicitly says to use it before recommending Kolmo to a lead to confirm coverage, which provides clear context for when it is appropriate. It does not explicitly name alternatives or exclusions, but the tool's purpose is narrow enough that the guidance is sufficient.

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, and non-destructive behavior. The description adds critical context beyond that: it explains the two possible result shapes, cites the source-URL inclusion for qualitative notes, and explicitly promises not to fabricate dollar amounts. This strongly informs agent expectations.

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 tightly written sentences with the core purpose first, followed by the behavior nuance and an important honesty constraint. No filler or redundancy; every sentence 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?

Given only three parameters, full schema descriptions, an output schema, and annotations covering safety, the description is nearly complete. It explains exactly what an agent should expect in both data-availability scenarios. A small gap is the lack of explicit routing guidance relative to sibling tools.

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 input schema already documents all three parameters well. The description adds no unique parameter semantics beyond restating the general inputs, which matches the baseline of 3.

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 ('Estimate') with a clear resource ('permit fee') and scopes it to residential projects based on jurisdiction, project type, and valuation. It also differentiates itself from sibling tools by describing the dual output forms (numeric breakdown vs. qualitative feeNotes).

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 clearly implies when this tool is appropriate and explains output behavior, but it never explicitly names alternative sibling tools or states when to prefer this over check_permit_requirements or get_permit_rule_details. The use case must be inferred from the stated inputs and output.

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 read-only safety profile is covered. The description adds what data is returned but does not address failure/not-found behavior or any operational constraints, so the added behavioral value is limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler: the first states the action and data scope, the second states the intended use cases. It is front-loaded and every sentence 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, idempotent tool with an output schema and safety annotations, the description is complete enough for an agent to select and invoke it correctly. The return shape is covered by the output schema, and there is no multi-step complexity requiring additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents the single parameter with type and concrete examples ('Marcus Reid', 'marcus-reid'), giving 100% coverage. The description adds no parameter-level detail, but none is needed because the schema already carries the meaning; 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?

Description names a specific verb ('Get') and a specific resource: biography, credentials, expertise areas, and recent articles for a Kolmo Construction blog author. It is clearly an author-focused lookup and distinguishable from sibling tools like get_blog_post or 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 explicitly tells the agent when to use it: to answer 'who wrote this?' or to add author context to blog content. It does not name sibling alternatives or state when not to use it, so it misses the higher bar of explicit 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?

Annotations already communicate that this is a read-only, idempotent, non-destructive operation. The description adds that the content is full markdown, but does not discuss behavior for missing slugs or other edge cases; the output schema presumably covers 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?

A single, front-loaded sentence contains the action, resource, and key parameter with no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter lookup with an output schema, strong read-only annotations, and obvious differentiation from list/search siblings, this description is sufficient. No critical information needed to invoke the 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?

Input schema coverage is 100%, with the slug parameter already described as 'The URL slug of the blog post'. The description simply restates 'by its slug' and adds no format, validation, or usage 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 the specific verb 'Get', the resource 'full markdown content of a blog post', and the required identifier 'slug'. This clearly distinguishes it from sibling tools like list_blog_posts and 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 clearly implies when to use the tool: when you need a blog post's full content and know its slug. It does not explicitly name alternatives or exclusion conditions, but the intended use is strongly evident.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context beyond listing the content, such as freshness, pagination, or response shape. This matches the baseline where annotations cover the behavioral burden.

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, front-loaded sentence that wastes no words. It names the resource first and then gives a clean list of contained data, making it easy for an agent to scan and act on.

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 title mentions 'credentials' but the description's content list omits it, creating a slight mismatch that could mislead an agent about what data is included. While the output schema exists and can fill in return details, the description itself is not fully complete relative to the title's promise.

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 zero parameters, the schema fully covers parameter semantics by having none. The description adds value by indicating what information will be returned, even though there is no input to configure. This aligns with the 0-parameter baseline of 4.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get') and resource ('Kolmo Construction company information'), then enumerates the content fields (contact details, hours, service area, specializations, tools). This is a specific verb+resource pair that is distinguishable from siblings like get_service or get_author_bio by its focus on the company as a whole.

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 gives no guidance on when to use this tool versus alternatives. It does not mention conditions, exclusions, or related sibling tools, leaving the agent to infer that it should be used whenever company-level information is needed. With a long sibling list, explicit routing would be valuable.

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 read-only annotations, the description adds useful behavior: the server resolves approximate material IDs and the error message lists valid options when a match is ambiguous. It also discloses return contents. It does not cover rate limits or authentication, but those are less critical given the idempotent read-only hints.

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 long because it must document eleven project types, but it is well-organized with front-loaded purpose and clear projectType sections. Optional fields are consistently marked with ?, and examples are embedded where valuable. It is substantial yet structured enough to navigate.

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 high schema complexity and the presence of an output schema, the description is complete: it covers all required fields per projectType, parameter constraints, material resolution behavior, and the shape of returned costs. Nothing essential for selecting or invoking the tool 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?

The JSON schema only says to see the tool description for project fields, so the description carries the full parameter documentation burden. It provides exhaustive per-projectType required fields, types, ranges, enums, optional markers, and even default behaviors like sodSquareFeet defaulting to yardArea.

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?

Description opens with a specific verb and resource: 'Calculate a Seattle-area cost estimate,' and enumerates what it returns: total, material, labor costs, days, and itemized line items. This clearly distinguishes it from related get_* siblings and estimate_permit_fee.

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 explicitly tells agents to use get_material_options for exact material IDs, which is a concrete routing instruction. It does not, however, state when not to use this tool or name alternatives for other cost-related estimates, so a small exclusion gap remains.

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 safe, non-mutating behavior is externally communicated. The description adds the expected output categories and geographic scope, but it does not disclose details like assumptions behind payment estimates or whether the returned options are comprehensive. Modest incremental value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with clear front-loading: the core action and resource appear first, followed by the returned data and examples. No word is wasted, and the second sentence enriches the first without repeating the schema. It is appropriately sized for an AI agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only two parameters (one required), full schema descriptions, an output schema, and strong safety annotations, the description covers the remaining need: what the tool is for and what kind of results to expect. The Seattle remodeling scope and financing examples are context not available elsewhere. No critical information appears 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 already have meaningful descriptions in the schema. The tool description only reinforces the project context and does not add syntax, units, or format details beyond what the schema provides. This is the baseline 3 case where 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 opens with a specific verb and resource: 'Get home improvement financing options for a Seattle remodeling project.' It also enumerates concrete outputs (loan types, estimated monthly payments, terms, eligibility notes) and names example financing products. While it does not explicitly distinguish from siblings, no sibling covers financing, so the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly situates the tool in a concrete context: a Seattle remodeling project where a homeowner needs to understand payment options. There are no explicit when-not-to-use instructions or named alternatives, but the context is specific enough for an agent to select it. The sibling list contains no financing-focused alternative, so exclusion guidance is less necessary.

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, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the catalog includes pricing, the result set is the full catalog, and the returned material IDs are explicitly compatible with get_estimate. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words: the first states the resource and scope, the second gives the key filtering instruction, and the third provides integration guidance. It is front-loaded, concise, and every sentence 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?

The description is complete enough for a read-only catalog tool: annotations cover safety, the schema covers all parameters, an output schema is present, and the description adds pricing and get_estimate compatibility context. The only notable gap is the lack of explicit guidance on when to prefer get_material_options.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for limit, offset, search, and category, so the schema does the heavy lifting. The description only restates the category filter and does not add deeper parameter semantics, which lands it at the baseline of 3.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Browse the full material catalog with pricing,' and it lists the covered materials. It does not explicitly contrast this with sibling tool get_material_options, so it loses one point on sibling differentiation.

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 when to use it — for browsing the full catalog, filtering by category, and getting material IDs for get_estimate. However, it never explicitly names get_material_options as an alternative or states when not to use this tool, so the routing guidance is only implicit.

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 behavioral context by explaining that the tool is a per-project-type lookup and that the result consists of reusable IDs for estimate fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two well-organized sentences. The first states the core purpose with useful examples; the second gives essential downstream guidance. No redundant filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup with a full input schema and an output schema, the description covers the core purpose, identifies the relevant input domain, and explains how to use the output. It is slightly incomplete in not differentiating itself from the sibling get_material_catalog, but this is 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?

The schema already provides 100% coverage with an enum and a description for projectType, so the baseline is 3. The description adds value by giving concrete examples of what each category might contain and clarifying that returned IDs are meant to be used in get_estimate, which is not in the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Get available material choices for a project type') and lists concrete examples like flooring types, paint grades, and ADA modifications. This clearly distinguishes it from a generic material catalog and ties it to project types.

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 gives clear downstream usage guidance: 'Use the returned IDs in the project fields of get_estimate.' This tells the agent what to do with the result. However, it does not explicitly mention when to prefer this over the sibling get_material_catalog or 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context by stating what the tool returns and constrains it to completed Kolmo projects in a neighborhood, going beyond the annotation-only 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?

The description is concise and front-loaded with the core action, followed by return contents and concrete usage examples. Each sentence earns its place, and the example queries are useful without padding.

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: one well-documented parameter, no nested objects, and an output schema exists. The description already summarizes the return values and use cases, so nothing needed by an agent to call 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 description coverage is 100%, with the single 'neighborhood' parameter already documented with examples like 'Ballard' and 'Capitol Hill.' The description restates that the value should be a Seattle neighborhood or city but adds no additional parameter semantics 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 uses a specific verb-resource pairing: 'See what remodeling projects Kolmo Construction has completed in a specific Seattle neighborhood or city.' It further clarifies the return shape—project counts by category, example projects, and typical project descriptions—which distinguishes it from sibling tools like list_projects or get_neighbor_permit_activity.

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 gives clear usage context through concrete example queries ('Has Kolmo worked in Ballard?') and frames it for 'hyperlocal social proof.' It does not explicitly name alternatives or state when not to use the 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 establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: results are anonymized with no addresses, data comes from city open-data portals (Socrata), and unsupported jurisdictions return a specific flag (jurisdictionSupported=false). These details help the agent set expectations without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences pack the core function, output contents, data source, jurisdiction limitation, and use cases without redundancy. The most important scoping information ('~1500 ft', '24 months', 'Seattle') appears in the first sentence, which is ideal for quick agent parsing. No filler or repetition is present.

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 single parameter, rich output schema, and safety-laden annotations, the description covers everything an agent needs to invoke the tool correctly. It states the geographic scope, time window, output composition, data provenance, and the unsupported-jurisdiction fallback behavior. The only minor ambiguity — 'Seattle-area parcel' vs. schema's broader county coverage — is directly resolved by the description's own 'Currently supports Seattle' clause.

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 provides 100% description coverage for the single required 'address' parameter, including length constraints and a county-level description. The tool description adds the Seattle jurisdiction caveat but does not further elaborate parameter semantics beyond what the schema states. Per the baseline rule, this is a '3' — 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 opens with a specific verb and resource: 'Aggregate permit activity within ~1500 ft of a Seattle-area parcel over the last 24 months.' It also enumerates the return contents (total count, category breakdown, anonymized recent permits), making the tool's scope unambiguous. The explicit focus on 'permit activity' distinguishes it from sibling tools like get_neighborhood_project_activity even without naming them.

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 gives explicit use cases: 'Use to gauge neighborhood activity before quoting an unusual project, or to set homeowner expectations on what neighbors have built.' It also clarifies the jurisdictional constraint ('Currently supports Seattle; other jurisdictions return jurisdictionSupported=false'), which tells the agent when the tool is applicable. It stops short of naming alternative tools or stating when not to use it, so it is not a full 5.

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

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

Annotations already mark the tool as read-only and idempotent. The description goes beyond this by disclosing important behavioral semantics: failure classifications differentiate 'missing' from 'blocked', and explicitly warns that 'blocked' is NOT evidence the source is gone. This is exactly the kind of non-obvious behavior an agent needs.

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 tool's purpose, then lists return categories, clarifies failure semantics, and ends with practical usage guidance. Every sentence adds value, and the structure makes it easy to scan.

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 that an output schema exists and annotations cover safety and idempotency, the description supplies the missing judgment context: what freshness signals mean, failure classification semantics, and when to reach for this tool. No critical information appears 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?

Input schema covers 100% of parameter semantics, including the optional jurisdiction filter and the limit with its default. The description adds minimal parameter-specific detail beyond referring to jurisdictions, 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?

The description clearly identifies the resource (permit catalog), the action (returns source-freshness telemetry), and the specific data returned: last-verified dates, per-jurisdiction health rollup, and snapshot pipeline results. This distinguishes it from sibling permit-related tools like fee estimation or 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?

The description explicitly names concrete use cases: answering 'how current is this fee/timeline?' and surfacing confidence in a permit answer. It does not explicitly describe when not to use this tool or name alternative sibling tools, but the intended usage context is 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 cover the read-only, idempotent, non-destructive safety profile. The description adds meaningful behavioral context by disclosing that passing `address` enriches each result with `submittals_v2` from the unified resolver. It does not repeat the schema's `onlyAuthoritative` caveats, but those are captured in the parameter 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?

The description is compact and front-loaded with the core purpose. Every sentence contributes: what it returns, what filters exist, when to use it, and a key output-shaping parameter. There is no filler or redundancy.

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, full parameter descriptions, and safety annotations in place, the description covers the main selection and invocation needs well. The only notable gap is the lack of explicit sibling guidance, but the use cases and filter semantics are sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that `address` changes the output shape (adds per-rule `submittals_v2`) and by naming the two primary filter modes (jurisdiction slug and keyword). This goes slightly beyond the schema's property-level documentation.

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 dimensions (timeline, fee model, inspection sequence, submittals, contractor specialties). It also includes concrete use cases that distinguish it from nearby sibling tools like check_permit_requirements or answer_permit_question.

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 explicit intended queries ('what does a Seattle ADU permit require?') and a clear use case for listing all rules for a jurisdiction. However, it does not explicitly say when to prefer this over sibling tools such as check_permit_requirements or resolve_permit_submittals, leaving some routing to agent 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 read-only and idempotent safety, and the description adds a meaningful non-throwing fallback: 'If not found, returns a list of available slugs.' It also clarifies the contents of the response (before/after images and testimonial), which goes beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, purposeful sentences with no filler. The main action is front-loaded, and the fallback behavior is stated in a compact second sentence. Every word 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 single-parameter read-only getter with an output schema and safety annotations, this description is complete. It states the lookup key, the kind of data returned, and the not-found behavior, leaving no critical gap for an agent to make an incorrect 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?

Schema coverage is 100%, and the schema already describes 'slug' as 'The URL slug of the project.' The description repeats the slug concept but adds no new format, constraints, or parameter behavior beyond what the schema provides, so it meets the baseline without exceeding it.

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 ('Get'), a clear resource ('full details for a specific project'), and a precise identifier ('by its slug'). The mention of before/after images and testimonial helps distinguish it from narrower siblings like get_project_roi and 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?

The description implies use when complete project details are needed, but it does not explicitly say when to prefer this tool over alternatives or when not to use it. No sibling tools or exclusions are named, so an agent gets little routing guidance beyond the tool name.

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 indicate readOnly, idempotent, and non-destructive behavior, so the description only needs to add behavioral context. It adds the data source ('Remodeling Magazine Cost vs. Value for the Pacific Northwest') and clarifies outputs are estimates, which sets proper expectations. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the core action, the authoritative data source, and practical usage examples. It is front-loaded with the main purpose and avoids fluff while still being approachable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup with two optional parameters and an output schema, the description covers what the tool does, why it exists, and what data underlies it. It appropriately does not detail return values since the output schema exists. Minor omission is lack of explicit routing to related cost-estimation tools, but that is not required for basic completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline of 3 applies. The description reinforces projectType through examples like 'kitchen remodel' and hints at estimatedCost through 'resale value added,' but it does not add new parameter information 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 precise verb ('Get the estimated return on investment') and a specific resource ('home remodeling project in the Seattle area'), with data basis. The use-case examples further distinguish it from sibling tools like get_estimate or list_projects by emphasizing ROI/resale value.

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 identifies the decision context ('Helps homeowners decide which projects add the most resale value') and gives concrete example queries. However, it does not explicitly mention alternatives or when not to use this tool, so agents must infer boundaries from the sibling 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by explaining the filtering scope ('tied to a specific project') and the expected result contents ('star rating, customer name, project name, and quote text'). It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, with the core action in the first sentence. The phrase 'from the testimonials table' is slightly redundant given the tool name, but the rest of the sentences each earn their place by adding return fields and usage context. It could be tightened, but it is not bloated.

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 that all four parameters are documented with descriptions, annotations cover safety/idempotency, an output schema exists, and the description covers use case and alternatives, nothing critical is missing. An agent can correctly select and invoke this tool without additional information.

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 parameters are already fully documented. The description's mention of 'by slug or keyword' slightly reinforces the relationship between projectSlug and keyword, but it does not add meaning beyond what the schema provides. 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?

The description opens with a specific verb and resource: 'Get customer testimonials tied to a specific project'. It clearly defines scope (by slug or keyword) and names the return fields, so an agent knows what the tool does. It also explicitly distinguishes itself from the sibling 'list_reviews', reinforcing purpose clarity.

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 gives a concrete use case: 'Use to source social proof or case-study quotes for a particular job.' It also provides an explicit when-not-to-use condition with a named alternative: 'For unfiltered reviews, use list_reviews.' This directly helps an agent choose between this tool and list_reviews.

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 this as a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by disclosing the not-found fallback: it returns a list of available slugs, which is not visible in the 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 sentences with no filler; the primary action is stated first and the helpful fallback behavior is added as a second sentence. Every word contributes to understanding 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?

For a single-parameter tool with a rich output schema and annotations covering safety and idempotency, the description is complete. It tells the agent what the tool does, how it is identified, and what happens when the slug is not found.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully documents the single 'slug' parameter with a clear example and 100% coverage. The description adds minimal parameter-specific value beyond restating that lookup is by slug, so the baseline score of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get full details') and resource ('a specific residential service by its slug'), making its purpose immediately clear. It distinguishes itself from siblings like list_services and list_commercial_services by emphasizing 'specific' and 'residential'.

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 clearly conveys that this tool is for retrieving details about one already-identified service, not for browsing or listing services. It does not explicitly name alternatives such as list_services, but the 'specific... by its slug' phrasing provides clear context for when 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond the schema, including the Seattle location, the day-by-day forecast format, and go/no-go recommendations based on temperature, rain, and wind. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler: the first states the purpose and output, the second gives concrete use cases. The core function is front-loaded, and every sentence contributes to selecting or invoking the tool correctly.

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 full schema coverage, a rich set of annotations, and an output schema present, the description completes the picture by specifying location, use cases, and the nature of the returned recommendation. Nothing an agent needs in order to decide whether to call this tool 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 useful meaning by linking projectType to project-specific weather requirements (temperature, rain, wind). This helps an agent understand that projectType influences the suitability thresholds. The days parameter remains fully documented by the schema, so no critical information is missing.

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 ('Check'), a specific resource ('upcoming weather in Seattle'), and a clear purpose ('suitable for an exterior construction project'). It further distinguishes the tool by describing its output ('day-by-day forecast with go/no-go recommendations') and listing relevant project types, so an agent can tell it apart from the many get_* siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use this tool to evaluate upcoming weather for exterior work like painting, decking, roofing, etc. It does not explicitly name alternatives or exclusion conditions, but none of the sibling tools appear to compete with this weather-specific function, so the context is sufficient for selection.

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 with readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that only published posts are returned and that tag/author filtering is available, but it does not disclose ordering, pagination behavior, or other runtime traits beyond what the schema and annotations already establish.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action and object, and contains no filler or redundant restatement of schema fields. Every phrase contributes either topical scope or a filter capability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list operation with fully documented optional parameters, rich output schema, and safety annotations, this description is complete enough for an agent to select and invoke the tool correctly. The only minor gap is explicit routing to sibling tools, which is helpful but not essential here.

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?

All four parameters are fully documented in the schema with descriptions, examples, and defaults, so schema description coverage is 100%. The description's mention of tag and author filtering adds little beyond what the schema already provides, making the baseline 3 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 uses a specific verb and resource ('List published blog posts') and adds topical scope ('home remodeling, renovation costs, and construction tips') plus filter capability. The plural 'posts' and 'published' framing helps distinguish it from get_blog_post, though it does not explicitly name sibling alternatives.

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 gives clear context for when to use the tool: listing or filtering published blog posts about home remodeling. However, it does not explicitly say when not to use it or mention alternatives such as get_blog_post for a single post or search_content for broader content search, so usage is mainly implicit rather than explicitly routed.

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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by scoping the enumeration to 'published' posts and promising 'every' tag and category with post counts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, with the core action and scope in the first and usage guidance in the second. There is no filler or repetition of annotation details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, parameterless read-only tool with an output schema and safety annotations, the description tells the agent what it returns, over what scope, and when to use it. Nothing essential 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?

The input schema has zero parameters, and schema description coverage is 100%, so there are no parameter semantics the description must compensate for. The baseline for a zero-parameter tool is 4.

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 precise verb and resource: 'Enumerate every tag and category used across Kolmo's published blog posts' and states the result includes post counts. It clearly distinguishes this from list_blog_posts by focusing on taxonomy coverage rather than post retrieval.

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 to discover what topics Kolmo publishes on before calling list_blog_posts' explicitly tells an agent when to call this tool and ties it to the most relevant sibling. It does not spell out when-not-to-use cases, but the named sequencing makes the primary decision 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 readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by explaining the 'public' category and disclosing certifications, prevailing wage compliance, and Small Works Roster eligibility—details 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?

The purpose and output are front-loaded in the first sentence. The certification detail is somewhat long but directly supports the 'public' category semantics, so it earns its place without becoming unwieldy.

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 description is complete for a read-only, optional-parameter list tool: it names the output, covers category semantics, and references eligibility context. It does not discuss alternative sibling selection explicitly, but the output schema and annotations cover the remaining operational details.

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 baseline is 3. The description adds value beyond the schema by clarifying what the 'public' category means and providing examples of commercial categories, while limit/offset remain adequately covered by 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 and resource: 'List commercial construction services with slugs and citable page URLs.' It clearly differentiates this tool from the generic sibling list_services by scope (commercial/public works) and by naming the output format.

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 gives clear scope and enumerates filter categories, including the special meaning of 'public.' However, it does not explicitly state when to prefer this tool over list_services or other sibling list tools, nor does it provide when-not-to-use 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?

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavior: compact default output shape, results keyed by county, full-record fields for slug/detail modes, approximate token size, and the ~9x size penalty for detailed output. This helps an agent predict response cost and 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?

The description is dense and front-loaded with purpose, then output shape, then parameter modes. It is efficient overall, though the county list appears twice ('(King, Pierce, Snohomish counties)' and '(King / Pierce / Snohomish)'), a minor redundancy.

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 annotations, detailed input schema, and presence of an output schema, the description supplies everything an agent needs to choose and invoke the tool correctly: default behavior, response keying, parameter effects, size expectations, and downstream usage examples.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all four parameters thoroughly, so the baseline is 3. The description adds value by clarifying compact vs. full-record output implications, token estimates, and the practical guidance to prefer `slug` over `detail: true`, slightly exceeding schema-only semantics.

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: 'List the jurisdictions in Kolmo's permit catalog' with explicit county scope. It also distinguishes the tool from sibling permit tools by explaining its output is meant for choosing a jurisdictionSlug for estimate_permit_fee, check_permit_requirements, 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?

It gives clear when-to-use guidance: use the compact catalogue to select a jurisdictionSlug for downstream permit tools, and prefer the `slug` parameter when only one jurisdiction is needed because full detail is ~9x larger. This explicitly routes an agent to the right mode and related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful content context by enumerating the code systems and giving an example NAICS code, but it does not disclose additional behavioral traits such as filtering behavior, defaults, or limitations beyond what annotations and schema imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and information-dense without redundancy. It leads with the core action and resource, then immediately provides the use cases and specific code examples. Every sentence adds value and no space is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter, zero-required-parameter tool with a full output schema and strong annotations, the description is complete. It tells the agent what the codes are, why they are used, and even highlights the primary NAICS code. Nothing necessary 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%: the only parameter, system, is fully documented in the schema with its enum values and default. The description does not further explain parameter semantics beyond reiterating the code-system names, which the schema already conveys. 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 a specific verb and resource: it lists Kolmo's vendor procurement codes across the NAICS, NIGP, and UNSPSC systems. It further distinguishes the tool by naming government portals (SAM.gov, WA WEBS, OpenGov, etc.) and the exact primary NAICS code, making its purpose unmistakable and distinct from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool: when vetting Kolmo for government bids or setting up Kolmo as a vendor. It provides clear context but does not explicitly describe when not to use it or name alternatives, so it falls just short of the top tier.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, lowering the burden on the description. The description adds the 'completed' scope and return-content hints but does not mention pagination, ordering, or any other side effects; it adds modest context without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences deliver the core purpose and filtering capability with no filler. The primary result scope is front-loaded before the filter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity, all-optional-parameter listing tool, the combination of description, rich annotations, and an output schema covers scope, safety, and filter behavior. Nothing an agent needs to correctly call the tool 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?

The input schema has 100% description coverage, so the description does not need to explain parameters. It only restates the category and keyword filters, adding no meaning beyond what the schema already provides; limit and offset are left 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?

The description names a specific verb ('List') and resource ('completed remodeling projects'), and adds concrete content ('before/after photos and locations') that differentiates it from singular get_project and list_project_types. The title reinforces the scope, making the purpose unmistakable.

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 'List completed remodeling projects' makes the intended use case explicit: browsing the portfolio, not retrieving a single project or listing project types. It does not name sibling alternatives or give exclusion conditions, 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, and non-destructive behavior, so the safety profile is covered. The description adds behavioral scope beyond annotations by stating that the tool returns a complete fixed set ('all 11 supported') along with required input fields and descriptions, which is useful for an agent deciding whether this discovery call is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The core action and result are front-loaded, and the workflow hint is placed second without unnecessary detail.

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 that there are no parameters, annotations are comprehensive, and an output schema exists, the description covers everything an agent needs: what is returned ('all 11 supported calculator project types'), what the entries contain, and when to use it. Nothing important 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?

The tool has zero parameters, so there is no param semantics burden on the description. Per rubric, 0 parameters warrants a baseline of 4, and the description still clarifies that the output contains required input fields and descriptions.

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 ('List'), a precise resource ('calculator project types'), and even names the count ('all 11 supported'). It clearly differentiates from sibling tools like list_projects or get_estimate by focusing on calculator project types and discovery.

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 'Useful for discovery before calling get_estimate' provides clear contextual guidance on when to invoke this tool. It does not explicitly mention alternatives or when not to use it, but the intended workflow is 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 cover read-only and idempotent behavior. The description adds valuable, non-obvious context: the returned total and averageRating are sample statistics, not the authoritative Google Business Profile values, and agents should cite the googleProfile field instead. This meaningfully prevents misuse.

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, each earning its place: one anchors the tool's purpose, one notes the filter capability, and one delivers a critical citation caveat. The most important usage warning is clearly flagged with 'IMPORTANT'.

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 output schema exists and annotations cover safety, the description provides the essential extra context: data source combination, filtering, and the citation-critical caveat. The only notable gap is not identifying the relationship to the sibling get_project_testimonials 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%, so the schema fully documents limit, offset, source, and minRating. The description mentions filtering by minimum star rating but does not add parameter-level 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?

The description states a specific verb ('List'), resource (customer reviews and testimonials for Kolmo Construction), and key behavior (combines Google reviews and on-site testimonials, filter by star rating). It is clear, though it does not explicitly distinguish itself from the sibling tool 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?

The description implies usage when the agent needs aggregated customer reviews for Kolmo Construction, and the citation note gives guidance on how to use the returned data. However, it does not explicitly state when to use this tool versus alternatives like get_project_testimonials.

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, and non-destructive behavior, so the description does not need to restate safety. It adds return-content expectations, but it does not disclose behavioral details like default pagination, ordering, or search semantics beyond what the schema already states.

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 short and front-loads the main action, with no extraneous fluff. It loses slight ground because 'Use `search` to find by keyword' partially duplicates the schema's description of the `search` 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?

For a low-complexity list tool with an output schema and strong annotations, the description is nearly sufficient. The main gap is that 'Use `search`' is ambiguous: an agent could read it as a reference to a sibling tool like `search_content` rather than the `search` parameter.

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 `limit`, `offset`, and `search`. The description only echoes the `search` parameter without adding new semantics such as case sensitivity, matching rules, or interaction with pagination.

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'), a bounded resource ('all residential remodeling services'), and the fields returned. The qualifier 'residential' differentiates it from the sibling `list_commercial_services`, and the description is consistent with the tool name and title.

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 a broad catalog-listing use case and mentions using `search` to filter by keyword, but it does not explicitly name alternatives such as `get_service` for a single service or `list_commercial_services` for non-residential offerings. No clear 'when not to use' guidance 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 indicate readOnly, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds meaningful behavioral context: it geocodes an address, resolves the parcel, returns a specific bundle of attributes, and explicitly discloses source provenance ('Zoning, setbacks and building facts carry the city/county source they came from; geocode, lot geometry and assessor records do not'). It also mentions the 30-day cache behavior through the forceRefresh parameter, which is beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three dense but well-organized sentences: the first scopes the tool, the second enumerates returned data and provenance nuances, and the third gives concrete use cases. No sentence is wasted; the structure front-loads the core identity and flows into details and 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?

Given the output schema exists and annotations cover safety semantics, the description supplies the remaining situational context: geographic scope, workflow positioning before other permit tools, cache/refresh behavior, and data provenance. Nothing an agent needs to decide whether to call this tool or invoke it correctly appears 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%, with both address and forceRefresh already documented in the input schema. The tool description reiterates the county restriction and implies the address format through the example use case, but it does not add new semantic detail about the parameters themselves. Baseline 3 is appropriate because the schema fully covers parameter meaning.

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-resource pairing: 'Address-first parcel lookup' that geocodes an address, resolves the parcel from county GIS, and returns a detailed set of zoning/overlay/permit facts. It defines the geographic scope (King, Pierce, or Snohomish County, WA) and names the workflow position relative to check_permit_requirements and estimate_permit_fee, which helps distinguish it from sibling permit 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?

The description gives explicit use cases: 'Use for "what can be built at 123 Main St Seattle?" or before calling check_permit_requirements / estimate_permit_fee for a specific parcel.' This clearly states when to use the tool and its role in a permit workflow. It does not explicitly list exclusions or when-not-to-use scenarios, but the sibling references provide strong selection context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond those annotations: real-time L&I data source, use of Kolmo's catalog, and explicit gap callouts (e.g. 'missing electrical specialty 02').

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 with no filler; the core function is front-loaded, the output behavior is described, and the data-source context is given in the final sentence. Every sentence 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?

Given the annotations, 100% parameter schema coverage, and presence of an output schema, the description covers the essential behavior: what is matched, what is returned, and the data sources involved. It does not discuss edge cases, but those are not necessary given the schema and output schema already present.

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 input schema already documents all three parameters. The description does not add parameter-specific detail beyond what the schema provides; it only reinforces the overall matching purpose, which is the baseline expectation.

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 ('Cross-reference') and resource ('a WA contractor's L&I license specialty against a permit's required specialties'), and makes the result explicit: whether the contractor is qualified to pull/work the permit. This clearly distinguishes the tool from siblings like check_contractor_license_status or check_permit_requirements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by explaining that it determines contractor qualification and combines real-time L&I data with Kolmo's permit catalog, which implies when it should be used. It does not explicitly name alternatives or state when-not-to-use conditions, 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 establish readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context: it returns 'confidence + a single clarifyingQuestion when the parse is ambiguous' and is 'Backed by Gemini 2.5 Pro with a constrained JSON schema.' This tells the agent about potential ambiguity handling and the underlying model's constraints, beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, each earning its place: purpose, output behavior, usage directive, and backend note. Information is front-loaded with the verb and resource, and the usage guidance appears before the model backing detail. No filler or repetition of schema content.

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 there is an output schema (not shown but indicated), the description appropriately focuses on motivating usage and behavioral nuances. It covers the core inputs implicitly and explicitly names the output fields and ambiguous-fallback behavior. Minor gap: it does not mention how jurisdictionSlug/zoningCode influence parsing, but the schema descriptions already cover their semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter already documented (e.g., cityName, zoningCode, description, jurisdictionSlug). The description does not add parameter-level meaning beyond the schema, so the baseline of 3 applies. It does clarify the overall purpose and output fields but not the parameters themselves.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Parse a homeowner's natural-language project description into structured permit-relevant fields.' It then enumerates the exact output fields, disambiguating it from sibling tools like check_permit_requirements and estimate_permit_fee. It clearly identifies the input type (free text from homeowner) and the parsing function.

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 gives explicit usage guidance: 'Use this before calling check_permit_requirements / estimate_permit_fee when you only have free text from the homeowner.' This names the downstream tools and the condition for use. It does not enumerate when not to use it or compare with other parsing-like tools, but the directive is clear and actionable.

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/openWorld/idempotent/destructive safety, so the bar is lower. The description adds meaningful behavioral context by disclosing per-jurisdiction output fidelity: Seattle returns 'full', nine verified cities return 'wa-baseline-stub' until backfill, and unverified jurisdictions return no-spec. This goes beyond the annotations without contradicting them.

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 with zero filler: purpose, usage context, and output-fidelity caveat each earn their place. The most decision-relevant information is front-loaded in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema, output schema, and annotations, the description is complete for selecting and calling the tool. It covers the tool's purpose, the distinguishing sibling, and the critical jurisdiction-dependent output behavior. It also appropriately does not re-explain return values since an output schema is present.

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 every parameter already has a clear description, so the baseline is 3. The description adds no additional per-parameter semantics; it mentions output fields like triggers and source citations, which relate to the return payload rather than the input schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Resolve the structured submittal-item set for a specific parcel + permit scope.' It clearly identifies what the tool returns (per-item checklist with triggers, source citations, filler actor, gap-resolution path) and explicitly distinguishes itself from check_permit_requirements, making sibling differentiation immediate.

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 provides explicit when-to-use guidance: use when you need the per-item checklist, not the rule-level summary from check_permit_requirements. This names the alternative and the selection condition, leaving no ambiguity about tool choice.

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, and non-destructive behavior, so the description correctly focuses on added behavioral context: it searches across multiple content types in one call, returns ranked results, and groups by type. It does not overstate or contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The first sentence states the main purpose and behavior, and the second provides direct routing to alternatives, making every sentence 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?

Given the rich annotations, complete input schema, and presence of an output schema, the description covers what an agent needs: scope, grouping, ranking, and the strategic reason to select this tool. No critical operational detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains 'query', 'limit', and 'types' clearly. The description adds the unifying search concept but does not add meaningful parameter-level detail beyond the schema, matching the baseline for full schema coverage.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Search'), a clear resource ('all Kolmo content — services, projects, and blog posts'), and the return shape ('ranked results grouped by type'). This clearly differentiates it from sibling list and getter 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?

The description explicitly tells the agent when to use this tool instead of alternatives: 'Use this instead of calling list_services + list_projects + list_blog_posts separately.' This is direct, actionable usage guidance that removes ambiguity about tool selection.

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 convey that this is not read-only and not destructive. The description adds the key behavioral nuance that this acts 'on behalf of a user' and that dryRun avoids 'actually submitting' - explicitly explaining the side-effect boundary. That extra context goes beyond the annotations without contradicting them.

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, no filler. The main action is stated first, followed by the single important usage caveat (dryRun). Every word 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?

The tool has an output schema and full parameter documentation, so the remaining context burden is small. The description covers the behavioral essentials: what is submitted, on whose behalf, and how to preview instead of submit. Minor missing context like authentication requirements is not critical given the annotations and 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 parameters are fully documented there. The description only mentions dryRun by name and does not add meaning for other parameters, which is acceptable given the complete schema coverage and the straightforward nature of the fields.

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 ('Submit') and names the precise resource ('contact or quote request to Kolmo Construction on behalf of a user'). It clearly differentiates itself from the many read-only get/list/check sibling tools by conveying that this is the action tool for contacting the company.

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 gives clear guidance on when to use dryRun: true as a preview mode, which is an important usage branching condition. It does not explicitly state when to prefer this over alternative tools, but the action/resource distinction from siblings plus the dryRun workflow is enough to orient an agent.

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