kolmo-mcp-server

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

Annotations already mark the tool read-only and non-destructive; the description adds important behavioral context: it cites sources, never fabricates fees/thresholds, and falls back to 'I don't have that on file'. This explains grounding and failure behavior beyond the structured 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?

Three sentences are front-loaded with purpose, then behavior, then usage examples. Every sentence contributes; there is no filler or repetition.

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

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

The description covers scope, data sources, return style, fallback behavior, and example uses. With an output schema present and annotations covering safety, nothing essential is missing 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 coverage is 100% and the description adds only example phrasing for the question and address parameters, not new format or constraints. Baseline 3 is appropriate because the schema carries the parameter 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 names a specific resource and action: grounded permit Q&A for a Seattle-area address, with a return value ('cited answer'). It is distinct from sibling tools like check_permit_requirements or get_neighbor_permit_activity because it combines parcel lookup, jurisdiction rules, neighbor activity, and municipal code into an answer.

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

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

It explicitly says 'Use for natural-language permit questions' and gives two concrete examples, so an agent knows when to invoke it. It does not mention exclusions or route to alternatives, so it stops short of 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses that data is updated daily, results are ranked closest match first, and when `identified` is false, no match should be reported. This is critical behavioral guidance about how to handle ambiguous results, which adds significant value.

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 core purpose is front-loaded in the first sentence. The additional sentences provide useful context about use case, search inputs, and result ambiguity. There is minor redundancy ('checks if they are licensed, bonded, and insured' repeats the first sentence), but overall it is sufficiently concise.

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 covers the essential operational aspects: scope (WA), data source and freshness, accepted query types, and the critical ambiguity handling rule. With an output schema present, an agent has all necessary context to invoke the tool and interpret results 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?

The input schema already fully describes the query parameter with examples and accepted formats (license number, business name, UBI, phone). The description essentially repeats this information without adding new meaning, so the baseline of 3 applies given 100% 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 uses a specific verb ('Look up') and a specific resource ('Washington State contractor's license, bond, and insurance status'). It also clarifies that it works for any competitor and explicitly names the checks (licensed, bonded, insured in WA), which differentiates it from siblings like get_business_info or 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') and lists the accepted search terms and result ranking. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full when/when-not guideline.

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?

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context. It explains how the verdict is computed (jurisdiction thresholds, parcel overlays, and facts), what happens when verdict is 'depends' (verdict.questions names facts to ask the homeowner), that requiresPermit is the rule's default posture rather than the answer, and that submittals_v2 fidelity differs by city (Seattle full SDCI, others wa-baseline-stub). This goes well beyond the annotations, giving the agent a realistic model of the tool's behavior and edge cases. No contradiction exists.

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

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

The description is long, but every sentence earns its place. It front-loads the core purpose, then systematically explains the verdict semantics, return fields, usage examples, and the special address behavior. There is no filler or tautology. The structure flows logically from what the tool does, to how to interpret its output, to how to call it effectively. Given the complexity of 9 parameters and a rich output schema, this length is justified and remains concise in intent.

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 tool with 9 parameters, a nested `facts` object, an output schema, and multiple annotations, the description covers the essential workflow: what it does, how to invoke it (including the two natural-language examples), the meaning of key output fields (verdict, requiresPermit), and the special behavior of `address` (submittals_v2 with per-city fidelity). It doesn't repeat parameter-by-parameter details because the schema already provides those, and it doesn't need to describe return structure because the output schema exists. Nothing an agent needs to decide when to call this tool or how to form a correct request is missing.

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

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

Schema coverage is 100% and each parameter already has a detailed description, so baseline is 3. The description adds meaningful usage semantics: it clarifies that passing `address` also returns `submittals_v2` from the unified permit engine, and explains that parcel-related facts in `facts` should only be passed when no address is given ('Parcel facts ... are read from the parcel when `address` is given; pass them only without an address.'). It also orients the `facts` parameter by stating that verdict.questions name the facts to pass back. These enrichments justify a step above baseline.

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 statement: 'Check whether a residential construction project in King/Pierce/Snohomish counties requires a permit.' It names the specific verb, resource, and geographic scope, and immediately distinguishes itself from siblings like answer_permit_question (a Q&A tool) and resolve_permit_submittals (which likely focuses solely on submittals) by framing the core as a permit-requirement check while also returning submittals. This gives an agent a clear, unambiguous purpose.

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 provides usage examples: "Use for 'Do I need a permit to build a deck in Seattle?' or 'What permits are required for a kitchen remodel in Bellevue?'" This is clear when-to-use guidance. However, it does not explicitly mention when not to use the tool or name alternatives (e.g., get_permit_rule_details for deep-diving a specific rule, or estimate_permit_fee for cost). The context is strong but lacks explicit exclusionary guidance, so it falls short of a 5.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds valuable operational semantics: unconfirmed places should be treated as in-area, out_of_area is the only refusal signal, and a count of completed projects is also returned. This goes well 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?

The description is compact and front-loaded with the core purpose, then follows with the decision-relevant coverage values and the extra count return. Every sentence carries necessary information with no filler.

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

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

Given the output schema exists and annotations cover safety, the description sufficiently explains the valid response categories, the handling of unrecognized places, and the additional project count. It gives an agent everything needed to invoke the tool and act on the result.

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 for the single `location` parameter, including examples. The description reinforces that the location can be a city, neighborhood, ZIP, or address, but does not add significant new meaning beyond the schema's own description.

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

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

The description opens with a specific action and resource: 'Check whether Kolmo takes work in a given city, neighborhood, ZIP or address.' It names the exact geographic scope (Washington, Puget Sound core) and the distinct return categories, making it clear how this tool differs from siblings like get_business_info or lookup_parcel_by_address.

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 strong context on how to interpret results: primary, nearby, case_by_case, unconfirmed, and out_of_area, including the critical note that out_of_area is the only negative value. It does not explicitly name alternative tools or give when-not-to-use conditions, so it falls just short of a 5.

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

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

Annotations already mark the tool read-only/idempotent/non-destructive, and the description adds valuable behavioral context: numeric breakdown when an authoritative rule exists, qualitative feeNotes with a source URL for PDF-only sources, and a strict no-fabrication policy. This goes well 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?

Three short sentences with no filler: purpose and inputs, return-mode behavior, and anti-fabrication guarantee. The most important information is front-loaded.

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

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

With full schema documentation and an output schema present, the description covers the key additional context: when numeric vs qualitative output occurs and the policy not to invent amounts. Nothing an agent needs to invoke it correctly is missing.

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

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

The input schema already documents all three parameters at 100% coverage, so the description does not need to repeat them. It merely names jurisdiction, project type, and valuation without adding meaning beyond the schema.

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

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

The first sentence names a specific verb ('estimate'), a clear resource ('permit fee'), and the exact input basis ('jurisdiction, project type, and project valuation'). This distinguishes it from siblings like check_permit_requirements and 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 clearly states this is for residential projects and requires jurisdiction, project type, and valuation. It also explains the fallback condition when cities publish fees as PDFs/spreadsheets, though it does not explicitly name alternatives or exclusions such as commercial projects.

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 no side-effect disclosure is needed. The description adds the data categories returned but does not address behavior for unknown authors or limits on recent articles; the output schema likely 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?

Two focused sentences; the first front-loads exactly what the tool returns and the second states common use cases. No filler or redundant repetition of schema or 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?

With one fully documented required parameter, safety annotations, an output schema, and a precise use-case statement, nothing needed to invoke 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%; the author parameter already includes type, required status, and examples like 'Marcus Reid' and 'marcus-reid'. The description adds no extra parameter meaning, but none is needed given the schema's completeness.

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 action ('Get') on an explicit resource ('biography, credentials, expertise areas, and recent articles') for a Kolmo Construction blog author. This clearly differentiates it from sibling tools like get_blog_post and list_blog_posts, which concern post content rather than the author profile.

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

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

Explicitly frames when to invoke: to answer 'who wrote this?' or add author context to blog content. It does not name exclusions or alternatives, but the use-case guidance is clear enough to route an agent appropriately.

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 that the return is full markdown content, which is useful, but it does not disclose behavior for missing slugs or other edge cases. An output schema exists, reducing the burden on the description.

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 one short, front-loaded sentence with no redundant words. It states the action, the resource, the content type, and the required input efficiently.

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

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

For a single-parameter, read-only tool with a rich annotation set and an output schema, the description is complete. An agent can correctly invoke it with a slug and know what to expect without additional documentation.

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 slug parameter is already described as 'The URL slug of the blog post'. The description only restates 'by its slug' and adds no new semantic value beyond the schema, 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 uses a specific verb ('Get'), names the exact resource ('full markdown content of a blog post'), and states the lookup key ('by its 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 implies the tool should be used when the caller has a blog post slug and needs the full markdown content, but it never explicitly names alternatives or states when not to use it. Siblings like list_blog_posts and get_author_bio exist, but no routing 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds the scope of the returned data but does not disclose additional behavioral details such as whether the data is cached, likely to change, or limited in coverage.

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 with a clear subject and an efficient list of content categories. Every phrase earns its place, and there is no repetition of schema or annotation information.

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

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

For a parameterless information retrieval tool with an output schema, the description is largely complete: it names the company and the kinds of details returned. The only minor gap is that the title mentions 'credentials' but the description does not list them; however, the output schema is available to supply the full field list.

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

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

The input schema has zero parameters, so there are no parameter semantics to explain. Per the baseline for parameterless tools, the description does not need to add parameter guidance, and it correctly focuses on what the tool returns.

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

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

The description uses a specific verb ('Get') and resource ('Kolmo Construction company information') and enumerates distinct content categories: contact details, hours, service area, specializations, and tools. This clearly differentiates it from sibling get_* tools like get_author_bio or get_service.

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

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

The intended use is implied by the description: agents should call this when they need general company information about Kolmo Construction. However, there is no explicit guidance about when not to use it or which alternative to choose, but the zero-parameter, company-specific scope makes this a minor gap.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond that: it returns a range rather than a fixed quote, includes material/labor split, days, and line items, and explains that material inputs can be resolved by get_material_options ID or close name, with ambiguous names triggering candidate lists.

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, but the length is justified by the need to document 20 project types. It front-loads the output summary and then organizes each project type's parameter grammar compactly; the dense notation is somewhat hard to scan, but every segment 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 tool's complexity, the description is remarkably complete: it covers all project types, required vs. optional inputs, constraints, defaults, and material references. An output schema exists, so the description does not need to explain return values; nothing essential for invoking the tool correctly appears to be 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?

Although the schema's coverage metric is 100%, the schema merely points to 'see tool description for required fields per projectType.' The description compensates massively by specifying per-project required fields, optional markers, units, ranges, defaults, enum-like values, and material-resolution behavior for all 20 project types.

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 'Seattle cost estimate: range, material/labor split, days, line items,' which clearly identifies the tool as a cost estimator and previews its outputs. It is specific enough to distinguish from siblings like estimate_permit_fee or get_project_roi, though it lacks an explicit verb phrase like 'get a cost estimate for.'

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 explicit guidance on when to use this tool versus alternatives such as estimate_permit_fee or get_material_options. It implies the tool is for estimating Seattle project costs by listing 20 project types, but it never states conditions, exclusions, or when a sibling would be more appropriate.

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

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

The annotations already establish read-only, idempotent, and non-destructive behavior. The description adds the informational nature of the response and the specific content returned (estimated payments, terms, eligibility notes), which is useful context beyond the structured annotations. There is no 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?

The description is compact: the first sentence states scope, the second lists return contents, and the third adds audience and financing categories. Every sentence earns its place, with no redundancy or filler.

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

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

With only two parameters, full schema descriptions, strong annotations, and an output schema present, the description gives enough context to invoke the tool correctly. It does not cover edge cases or explicit non-use scenarios, but those are minor given the simple input surface.

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 projectBudget and creditProfile are already documented. The description does not add specific parameter-level detail or explain how budget or credit profile affect the returned options, so it stays at the baseline for a fully covered 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 clearly names the verb 'Get' and the resource 'financing options,' and it enumerates the outputs: loan types, estimated monthly payments, typical terms, and eligibility notes. It does not explicitly contrast with sibling tools, but the financing-specific scope is distinct from nearby tools like get_estimate or get_project_roi.

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

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

The description provides clear context for when to use this tool: a Seattle remodeling project where a homeowner needs to understand how to pay for the remodel. It lists relevant financing vehicles (HELOC, home improvement loans, cash-out refinance, contractor payment plans), though it does not state exclusions or directly name alternative 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=true, idempotentHint=true, and destructiveHint=false, so the safe read-only behavior is covered. The description adds useful behavioral context beyond annotations: the catalog is 'full' and includes pricing, and the returned material IDs are explicitly compatible with get_estimate. It does not add every operational detail, but the annotations lower the burden and the description complements them well.

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 no filler. The core purpose is front-loaded, followed by one filtering tip and one output-compatibility note, all of which earn their place. This is a model of concise, structured documentation.

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 low complexity (four optional, well-described parameters), rich annotations, and an output schema, the description is complete enough for an agent to select and invoke the tool correctly. It states the purpose, the filtering option, and the downstream use of the returned IDs. No critical invocation 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?

The schema provides descriptions for all four parameters (limit, offset, search, category), so schema coverage is 100% and the baseline is 3. The description only repeats the category-filter concept and adds no new parameter syntax, defaults, or formatting details beyond what the schema already provides. It meets the baseline but does not elevate 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 states a specific verb and resource: 'Browse the full material catalog with pricing' and lists concrete material types. It also adds a distinctive output detail ('Returns material IDs compatible with get_estimate'), which helps differentiate it from many siblings. However, it doesn't explicitly distinguish itself from the similarly named get_material_options, so it stops short of a 5.

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

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

The description provides clear context: an agent can use this tool to browse materials and obtain IDs for get_estimate. The instruction 'Use category to filter' gives practical invocation guidance. It never explicitly names when not to use it or compares it to alternatives like get_material_options, so it lacks the explicit exclusion language needed for 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds no additional behavioral detail beyond the fact that it returns IDs, but 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 two sentences with no filler. The first sentence states the core function with concrete examples, and the second sentence gives the practical downstream use, earning its place by connecting this tool to get_estimate.

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 lookup tool with a rich enum and an output schema, the description is complete. It explains what is returned, gives representative coverage across project types, and tells the agent how the result should be used.

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 a clear description and enum for projectType, so the schema carries the parameter documentation burden. The description adds contextual examples of material categories but no additional parameter semantics beyond what the schema already provides.

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

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

The description uses a specific verb and resource combination ('Get available material choices for a project type') and elaborates with concrete examples like flooring types, paint grades, and decking materials. It also distinguishes this tool by tying it to get_estimate, which differentiates it from sibling tools such as get_material_catalog.

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 stating that returned IDs should be used in the project fields of get_estimate, giving agents a concrete downstream purpose. It does not explicitly state when not to use this tool or name alternative tools, so it stops just 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by stating what the tool returns and its scoping to a neighborhood/city. It does not disclose caveats like data freshness or empty-result behavior, but the output schema covers the return shape and the annotations cover the safety profile.

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

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

Three sentences with no filler: the first states the action, the second describes the returned data, and the third gives practical usage examples. Each sentence earns its place and the most important information is front-loaded.

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

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

For a read-only, single-parameter lookup with a full input schema and an output schema, the description is complete. It covers what the tool does, the nature of the results, and sample user questions it answers. Nothing essential is missing for an agent to decide when and how to invoke it.

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 single parameter is fully documented in the schema with examples ('Ballard', 'Capitol Hill', 'Bellevue', 'Queen Anne'), and schema description coverage is 100%. The description reinforces the same semantics but does not add meaning beyond what the schema already provides, so the high-coverage 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: 'See what remodeling projects Kolmo Construction has completed in a specific Seattle neighborhood or city.' It further clarifies the output ('project counts by category, example projects, and typical project descriptions'), making the purpose unmistakable and distinguishing it from siblings like get_neighbor_permit_activity or list_projects.

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 concrete use-case examples: 'Has Kolmo worked in Ballard?' and 'What has Kolmo done in Capitol Hill?' This effectively communicates when to use the tool, but it does not explicitly contrast it with alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: results are anonymized (no addresses), sourced from city open-data portals, and only Seattle is supported while other jurisdictions return jurisdictionSupported=false. This clarifies edge cases and data handling, which is especially useful given the openWorldHint. No contradiction with annotations.

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

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

The description is three sentences with zero redundant phrases. It front-loads the core function in the first sentence, then details the output and source, and ends with practical use cases. Every sentence earns its place, making it efficient and 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?

For a tool with a single parameter, comprehensive annotations, and an output schema (as indicated by context signals), the description covers all necessary aspects: what it does, what it returns, data provenance, jurisdiction limitations, and use cases. No critical information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the 'address' parameter clearly (full street address in King, Pierce, or Snohomish County, WA). The description enhances this by specifying that the tool targets 'Seattle-area parcels' and noting that other jurisdictions return jurisdictionSupported=false, which tells the agent that addresses outside Seattle may not produce useful results. This nuance goes beyond the schema's generic county list, adding meaningful semantic guidance.

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

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

The description clearly states the verb 'aggregate' and resource 'permit activity' with precise scope (within ~1500 ft, last 24 months, Seattle-area parcel). It also lists the return payload (count, category breakdown, anonymized example permits) and data source (Socrata). This differentiates it from siblings like get_neighborhood_project_activity, which focuses on projects rather than permits.

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 cases: 'gauge neighborhood activity before quoting an unusual project' and 'set homeowner expectations on what neighbors have built.' However, it does not explicitly name alternatives or state when not to use this tool, such as differentiating from get_neighborhood_project_activity. The context is clear but lacks explicit exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context by explaining failure classifications (missing vs blocked) and clarifying that 'blocked' does not imply the source is gone. 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?

The description is moderately long but each sentence contributes value—explaining the response contents, failure semantics, and usage. It front-loads the key purpose and structures the information logically. Slightly verbose in the listing of pipeline details, but not wasteful.

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 the description thoroughly describes what data is returned (per-jurisdiction dates, health rollup, snapshot results, failure classifications), an agent has enough context to know when to call this tool and what to expect. The description also ties it to permit confidence, completing the reasoning chain.

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

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

Schema description coverage is 100% with both parameters clearly described in the schema. The description does not add extra parameter semantics beyond the schema, but since the schema already fully covers them, the baseline of 3 is appropriate. No additional insight is provided in the description text.

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

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

The description clearly states the tool returns source-freshness telemetry for the permit catalog, including last-verified dates, health rollup, and snapshot pipeline results. It specifies the resource (permit catalog) and the action (retrieve freshness), and the mention of failure classification distinguishes it from generic data queries.

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?

Explicit usage guidance is given: 'Use to answer

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, non-destructive behavior. The description adds meaningful context on output scope, filtering, and the conditional submittals_v2 enhancement when address is provided. With the safety profile already covered by annotations, the added conditional behavior earns a 4.

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 strong front-loading: purpose and detail come first, use cases second, and the optional address enhancement last. Every sentence earns its place with no 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?

For a read-only enumeration tool with a rich output schema and fully described parameters, the description covers selection, use cases, filters, and the optional enhancement path. Nothing essential appears to be missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description restates filtering and the address-triggered submittals_v2 behavior but adds no new parameter meaning beyond what the schema already documents.

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 clear verb and resource ('Enumerate permit rules') and lists concrete detail dimensions, plus example queries like 'what does a Seattle ADU permit require?'. It does not explicitly differentiate from siblings such as resolve_permit_submittals or check_permit_requirements, so it falls just short of a 5.

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

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

It gives explicit when-to-use scenarios ('Use for ... or to list all rules for a jurisdiction') and clarifies the optional address-triggered submittals_v2 behavior. It does not name alternative sibling tools or state when not to use it, so exclusions are missing.

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 valuable behavioral context beyond annotations by specifying the not-found behavior: 'If not found, returns a list of available slugs.' This helps an agent handle an edge case without guessing.

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 core purpose and return content are front-loaded, and the fallback behavior is appended in a separate clause. Every word contributes to understanding.

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

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

For a one-parameter read-only tool with an output schema and full parameter coverage, the description is complete: it states the lookup key, the nature of the returned data, and the not-found fallback. No critical behavior is left unexplained.

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

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

Schema description coverage is 100% and the single 'slug' parameter is already described as 'The URL slug of the project.' The description only repeats the concept of selecting by slug without adding new semantic detail, so it meets the baseline but does not elevate 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 names a specific verb ('Get'), a precise target ('full details for a specific project'), and the required identifier ('by its slug'). It also distinguishes itself from sibling tools like get_project_roi and get_project_testimonials by explicitly including before/after images and testimonial as part of the returned 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 clearly implies when to use it: when you need full project details for a known slug. However, it does not explicitly contrast this with sibling tools like list_projects for discovering slugs or get_project_testimonials for only testimonial data, leaving the when-not-to-use guidance to inference.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds the important geographic limitation (Seattle area / Pacific Northwest) and the fact that the value is an estimate based on Remodeling Magazine data. It does not contradict annotations, and the output schema covers the return shape.

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

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

Two sentences plus two examples, front-loaded with the core action and scoped immediately. The examples earn their place by illustrating natural-language use, so the description is appropriately sized 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?

With an output schema present, read-only annotations, 100% parameter documentation, and a clear statement of scope and data source, an agent has what it needs to select and invoke the tool. The only minor gap is an explicit caveat about data/update limitations, but that is not required for correct invocation.

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 projectType and estimatedCost are already documented with examples and semantics. The description adds no new parameter-level detail, so 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?

Opens with a specific verb, resource, and geographic scope: 'Get the estimated return on investment (ROI) for a home remodeling project in the Seattle area.' It also names the data source and distinguishes itself from generic estimation tools by focusing on resale value for homeowners.

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?

Clearly frames when to use it: to help homeowners decide which projects add the most resale value, with two natural-language examples. It does not explicitly state alternatives or when-not-to-use, 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 readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful context beyond annotations by naming the source table, specifying returned fields, and implying fuzzy/keyword matching behavior, which aligns with the annotation 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 compact and front-loaded with the core operation, followed by return fields, use case, and sibling alternative. Every sentence adds distinct value and none of the content is redundant with the schema.

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

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

For a read-only, idempotent lookup tool with no required parameters and a full output schema, the description covers the essential decision context: what it does, what it returns, when to use it, and when not to. The sibling alternative and use case complete the picture.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including their meanings and defaults. The description adds only light semantic context ('by slug or keyword', 'for a particular job') without exceeding what the schema offers, matching the baseline for full 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 begins with a specific verb-resource pair, 'Get customer testimonials tied to a specific project', and clarifies the lookup method ('by slug or keyword') and the data source ('from the testimonials table'). It also lists the returned fields, which distinguishes it from broader review tools.

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

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

It states an explicit use case: 'Use to source social proof or case-study quotes for a particular job.' It also gives a direct alternative and condition: 'For unfiltered reviews, use list_reviews,' providing clear routing guidance.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds a valuable behavioral detail beyond annotations: on not-found it returns a list of available slugs to help the caller choose the correct one. This enriches the agent's understanding of the tool's failure mode.

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, and the main action is stated first. The fallback behavior is a natural second sentence, making the description efficient and well structured.

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

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

For a single-parameter read-only lookup with an output schema, annotations, and a clear fallback behavior, the description is complete. Nothing an agent needs to call 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?

The schema has 100% description coverage for the single 'slug' parameter, including a concrete example. The description only reinforces 'by its slug' without adding new parameter-level semantics, 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 uses a specific verb ('Get full details') and a specific resource ('residential service') keyed by slug, clearly distinguishing this from list_services and list_commercial_services. The phrase 'full details' also separates it from lighter summary 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 clearly conveys when to use the tool: when you need details for a specific residential service identified by slug. The not-found fallback also provides practical guidance for a wrong/invalid slug. However, it does not explicitly name alternatives like list_services for browsing, though that is strongly implied.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail by specifying the day-by-day forecast format and the go/no-go criteria (temperature, rain, wind), going beyond the annotations.

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

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

Two focused sentences with no filler. The first sentence states the main purpose and output; the second supplies relevant use cases.

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

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

A simple two-parameter tool with a fully documented schema and output schema. The description covers location, purpose, output shape, and the decision criteria, leaving no material gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions project-specific requirements and lists project types, but does not add syntax or format details beyond what the schema already provides.

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

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

States a specific verb and resource ('Check if upcoming weather in Seattle is suitable for an exterior construction project') and a clear output ('go/no-go recommendations'). It is unambiguously the weather tool among the sibling set.

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

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

Provides clear use context with concrete project types ('Perfect for scheduling exterior painting, decking, roofing, landscaping, siding, or fencing'). It does not explicitly list exclusions or alternative tools, but the intended usage is 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 cover safety: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the 'published' status constraint and the topic focus, which is useful context, but it does not disclose ordering, pagination behavior, or filter-combination semantics beyond what the schema already implies.

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

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

Two compact sentences with no filler. The action and scope are front-loaded, and the filter capability is stated in the second sentence 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 the rich annotations, complete parameter schema, and presence of an output schema, the description is sufficient. It identifies the content domain, the published-only scope, and the available filters; nothing critical is missing for a caller to invoke this 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 schema fully documents the four parameters. The description mirrors the tag and author filters but adds no extra meaning about parameter formats, defaults, or behavior beyond what the schema provides.

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

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

The description states a specific verb ('List'), a clear resource ('published blog posts'), and a topical scope ('home remodeling, renovation costs, and construction tips'). It also names the two filtering dimensions, which distinguishes it from siblings 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 action is clear, but there is no explicit guidance on when to choose this tool over alternatives such as get_blog_post for a single post or search_content for full-text search. The intended use is implied rather than stated with exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description adds a scope guarantee ('every tag and category') and post counts, but does not disclose any further behavioral details such as pagination, ordering, or data freshness.

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, followed by the practical use case. Every sentence contributes meaningful information.

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

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

Given that there are no parameters, an output schema exists, and the annotations already cover safety behavior, the description fully covers what the tool does 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 tool has zero parameters and the schema description coverage is 100%, so there is nothing missing for the description to clarify. With no parameters, the description is not burdened with parameter semantics, and the baseline of 4 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 ('enumerate'), a specific resource ('every tag and category'), and the scope ('Kolmo's published blog posts') while also noting it returns post counts. This clearly distinguishes it from sibling tools like list_blog_posts, which list posts rather than their metadata.

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

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

It explicitly tells the agent when to use the tool: before calling list_blog_posts to discover topics, or to surface coverage gaps. This is actionable and provides clear context, even though it does not enumerate all possible alternatives.

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

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

The annotations already communicate read-only, idempotent, non-destructive behavior. The description adds context about output contents and the meaning of 'public', but does not disclose additional behavioral traits such as pagination defaults, rate limits, or authentication requirements. No contradiction exists.

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

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

The main function and filter options are front-loaded in one clear sentence. The certification details add length, but they are relevant to the 'public' category and not filler.

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

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

With an output schema present and annotations covering the safety profile, the description covers purpose, filter semantics, and output expectations well. Pagination and limit details are left to the schema, which is acceptable. The only slight gap is the lack of explicit guidance about when to prefer this over list_services.

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 covers all parameters with 100% coverage, so the baseline is 3. The description adds real semantic value by enumerating category values and especially by explaining that 'public' covers public works and government contracts, plus certification/eligibility details that make the filter meaningful.

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

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

The description clearly states the tool lists commercial construction services with specific output fields (slugs and citable page URLs). The 'commercial' + 'public-works' framing distinguishes it from the broader sibling list_services even though no sibling is named.

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

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

The description explains the optional category filter and gives useful context about the 'public' category, but it never explicitly says when to use this tool over list_services or other sibling list tools. Usage is implied rather than stated.

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

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

Even with annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds concrete behavioral details: compact-by-default output keyed by county with rows of {slug, name, verified}, approximate token size, and the existence of a detail mode. These shape and size tradeoffs go beyond what annotations provide.

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

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

The description is efficient and front-loaded, leading with the core purpose and then layering output shape, size, and parameter behavior. It is slightly dense, with long clauses and parentheticals, but every phrase contributes useful information and nothing is redundant with the schema.

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

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

With a high-coverage schema and an output schema present, the description covers the essential selection and invocation concerns: what the tool returns, how large the response is, and which parameter mode to use for which need. Prose coverage of `county` and `verifiedOnly` is absent, but those are fully documented in the schema, so nothing critical 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 already provides full parameter descriptions (100% coverage), so the baseline is 3. The description raises this by spelling out the fields in a full record ('department, fee-schedule URL, phone, code cycles, notes') and clarifying the compact output shape, which adds meaning beyond the schema's 'full record' phrasing. However, it doesn't add new semantic detail to `county` or `verifiedOnly`.

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 object: 'List the jurisdictions in Kolmo's permit catalog (King, Pierce, Snohomish counties).' It clearly identifies the resource and scope, and goes further by naming downstream tools that consume its output (estimate_permit_fee, check_permit_requirements, get_permit_rule_details), which distinguishes its purpose 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?

It explicitly states when to use this tool: 'enough to pick a jurisdictionSlug for estimate_permit_fee, check_permit_requirements or get_permit_rule_details.' It also provides intra-tool guidance, explaining when to use `slug` for one full record versus `detail: true` for all rows and noting that the full catalogue is compact (~4K tokens) with a much larger detail mode.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds useful behavioral context about the scope of the data, such as the targeted government portals and the primary NAICS code. It does not contradict the annotations, and the presence of an output schema reduces the need for return-format details.

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 first states the resource, the second gives usage timing, and the third provides useful content details. The description is front-loaded with the action and object.

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 one optional parameter, an output schema, and robust annotations, the description covers purpose, usage context, and data content. No material information an agent would need 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?

The single optional parameter is fully documented by the schema with an enum and default description, so the schema does the heavy lifting. The description adds general context about the code systems but does not add new parameter-level 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 begins with a specific action and object: 'List Kolmo's vendor procurement codes,' and disambiguates the resource by naming the code systems (NAICS, NIGP, UNSPSC). It is clearly distinct from sibling list tools like list_commercial_services and list_projects.

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 it: 'when vetting Kolmo for gov bids or setting up Kolmo as a vendor.' It does not explicitly name sibling 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, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful domain context: what the commercial/public-works bucket actually contains (tenant improvements, fit-outs, ADA remediation), which shapes what the agent will get back. It does not mention pagination defaults despite them existing, which keeps it from a 5.

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

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

Purpose and scope are front-loaded in the first sentence, and the category semantics follow in support. It's slightly dense in the final clause but every sentence earns its place; nothing is redundant filler.

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

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

With an output schema present, return-value explanation is unnecessary, and the annotations cover the safety profile. For a filterable list tool with fully documented params, the description supplies exactly the missing domain interpretation and nothing an agent needs is absent.

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

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

Schema coverage is already 100%, so the baseline is 3. The description goes further by interpreting the category parameter for the agent — mapping 'commercial'/'public-works' to the real-world content types it will return and naming the residential options' domain — adding meaning beyond the raw enum list 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?

Specific verb+resource: 'List Kolmo's completed projects' with explicit scope (residential AND commercial/public-works). It carves out a distinct niche apart from get_project (singular lookup) and list_project_types, and the category routing makes the tool's identity 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?

Gives a clear trigger condition — call it to browse completed work by category or keyword — and spells out which category values drive the commercial portfolio. It never states when NOT to use it (e.g., single-project retrieval via get_project), so it stops short of the 5-level explicit alternatives framing.

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=true and idempotentHint=true, so the agent knows this is a safe read-only operation. The description adds that it returns 20 types with required fields, but does not disclose additional behavioral traits like rate limits, ordering, or any edge cases.

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 wasted words. The main action and scope are front-loaded, and the second sentence adds a relevant usage hint. Every fragment in the description 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 an output schema present, no parameters, and annotations covering the non-destructive behavior, this description is fully complete. The fixed count '20' even tells the agent exactly how many results to expect, leaving no ambiguity.

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 and the schema coverage is 100%, so per the rubric the baseline is 4. The description doesn't need to explain parameters but does mention that each project type includes 'required input fields,' which clarifies what the return payload contains.

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'), a precise resource ('all 20 supported calculator project types'), and what is included ('required input fields and descriptions'). It clearly differentiates from sibling list tools by specifying 'calculator' project types and the fixed count of 20.

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 usage context: it is for discovery before calling get_estimate. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full 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 safe, but the description adds a crucial behavioral disclosure: total and averageRating describe the returned sample, not the overall business, and the authoritative values live in googleProfile. This prevents a likely mis-citation, which is exactly the kind of beyond-schema transparency needed.

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 purpose comes first, followed by source composition and filtering, then the critical citation caveat. The structure front-loads the listing behavior and defers the warning where it still lands naturally.

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

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

For a read-only, idempotent list tool with a detailed schema and output schema, the description covers what the agent needs: source aggregation, available filters, and the semantic meaning of result counts and ratings. No critical missing context remains.

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 covers 100% of the parameters with descriptions and constraints, so the description is not required to repeat details. It does add a high-level mention of minimum-star filtering, but no new semantics 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 opens with a specific verb and resource: 'List customer reviews and testimonials for Kolmo Construction,' and immediately clarifies it combines two source types, Google reviews and on-site testimonials. This makes the tool's scope and aggregation behavior clear and differentiates it from project-specific or single-source 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 establishes clear context: use this tool to list and filter customer reviews, with source and minimum-star filtering implied. It does not explicitly state when to prefer get_project_testimonials or another alternative, but the citation caveat tells the agent when to rely on the googleProfile fields.

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 the output scope (slugs, descriptions, page URLs) and the keyword-filtering behavior, but it does not address pagination semantics despite the limit/offset parameters existing in the schema. This is acceptable but not rich.

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

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

Two sentences, front-loaded with the resource and output fields, then the keyword usage note. There is no filler or repetition. The only minor ambiguity is that `search` could be read as the sibling search_content tool, but the backticks and schema context make it understandable.

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 list tool with fully documented parameters, rich annotations, and an output schema, the description plus structured data is complete. An agent can invoke it correctly: it knows the resource scope, what fields are returned, and how to filter by keyword.

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 repeats only the search keyword filtering, adding no new parameter-level meaning or format details. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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: 'List all residential remodeling services with slugs, descriptions, and page URLs.' The qualifier 'residential' differentiates it from sibling list_commercial_services, and the mention of return fields makes the scope concrete.

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 direct usage instruction: 'Use `search` to find by keyword.' This tells the agent when to apply filtering rather than simply listing everything. It does not explicitly exclude alternatives like get_service or list_commercial_services, but the residential/list framing makes the context reasonably 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 mark it read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it geocodes before resolving the parcel, includes a 30-day cache with a forceRefresh option, and notes which returned fields carry source attribution versus which do not. This goes well 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 dense but each sentence earns its place: purpose, return contents, source-attribution nuance, and explicit use guidance. It is front-loaded with the primary purpose and keeps the alternative routing at the end.

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 output schema, comprehensive input schema, and safety annotations, the description covers all needed context: geographic scope, cache behavior, return categories, source provenance, and when to use it relative to sibling tools. 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?

Schema coverage is 100%, so both parameters are fully documented in the input schema. The description reinforces the address geocoding scope and geographic counties but adds no new parameter meaning beyond what the schema already provides. 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: 'lookup_parcel_by_address' geocodes an address, resolves the parcel, and returns zoning, setbacks, overlays, lot area, jurisdiction, and permit history. It distinguishes itself from siblings by explicitly positioning it as the address-first lookup that precedes check_permit_requirements 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 says when to use it: for 'what can be built at 123 Main St Seattle?' and 'before calling check_permit_requirements / estimate_permit_fee for a specific parcel.' It also scopes it geographically to King, Pierce, or Snohomish County, which helps an agent decide whether this tool applies.

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, so the safety profile is covered. The description adds value by explaining data sources (real-time L&I and Kolmo's catalog) and the nature of the output (gap callouts). No contradictions with annotations are present.

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

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

The description is three sentences, with the primary action first, followed by output specification and data source context. Every sentence contributes meaning without redundancy. The structure is front-loaded and efficient, leaving no unnecessary words.

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

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

The description covers the purpose, output, and data sources. It does not explicitly address edge cases (e.g., missing license, permit with no required specialties) or error handling, but the presence of an output schema (stated) likely covers those. For a read-only, idempotent tool with clear parameters and output, this is adequately complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (contractorQuery, jurisdictionSlug, projectType) with clear examples. The description does not add additional parameter-level detail beyond the schema, but it reinforces the purpose of the parameters in the context of specialty matching. The baseline of 3 is appropriate because 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 states a precise action: cross-referencing a contractor's L&I specialty against a permit's required specialties. It clearly distinguishes itself from siblings like check_contractor_license_status (which checks license validity) and check_permit_requirements (which lists requirements) by focusing on the matching outcome. The output is explicit: qualification status with gap callouts.

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

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

The description implies a clear use case: determining if a specific contractor is qualified for a specific permit. It does not explicitly name alternatives or exclusions, but the specificity of 'contractor to permit' matching makes it obvious when to use this tool over siblings. The mention of real-time L&I data and Kolmo's catalog provides context but no explicit when-not 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 convey read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it returns confidence plus a single clarifyingQuestion when ambiguous, and it is backed by Gemini 2.5 Pro with a constrained JSON schema—helping the agent anticipate output shape and reliability.

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

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

Three tight sentences: purpose with field list, return behavior, and usage guidance. Front-loaded and free of filler, 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?

With an output schema, complete schema descriptions, and annotations handling structured details, the description covers the remaining essentials: when to use, what it returns, and the underlying model. No critical context is missing for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the input schema. The description does not add parameter-level detail, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Parse') and resource ('homeowner's natural-language project description'), enumerates the structured output fields, and distinguishes itself from downstream siblings like check_permit_requirements and estimate_permit_fee by positioning itself earlier in the pipeline.

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

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

Explicitly instructs: 'Use this before calling check_permit_requirements / estimate_permit_fee when you only have free text from the homeowner.' This names the alternatives and the exact condition that selects this tool, leaving no ambiguity about when to invoke 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 the tool as read-only, open-world, idempotent, and non-destructive, so the safety profile is covered. The description adds critical behavioral details: the output fidelity varies by jurisdiction (Seattle full with citations, other cities wa-baseline-stub until backfill, unverified jurisdictions return no-spec). This is valuable context beyond the annotations, though it does not describe pagination or error handling, which are minor given the output schema.

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

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

The description is concise and front-loaded, with the primary use case stated first. It is a single paragraph that efficiently covers purpose, differentiation, and jurisdiction-specific behavior. It is slightly dense but each clause earns its place, justifying a 4 rather than a 5.

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 moderate complexity (6 params, 2 required, output schema present), the description covers the key usage scenario, distinct from siblings, and jurisdiction-specific expectations. It doesn't delve into output schema details, but since an output schema exists, that is not required. It is complete enough for an agent to invoke correctly, though it could mention error cases (no-spec) more explicitly.

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 all parameters. The description adds context that scope is a project-type x work-class identifier and that envelopeChange/structuralChange drive triggers, but these are also partly in the schema. The baseline of 3 is appropriate because the schema does the heavy lifting; the description does not add significant new semantics beyond confirming the pipeline's use.

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

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

The description clearly states the tool resolves a structured submittal-item set for a given parcel and permit scope, explicitly differentiating it from check_permit_requirements (rule-level summary) and noting the per-item checklist includes triggers, citations, filler actor, and gap-resolution path. This is a specific verb + resource + scope, fully distinguishing it from 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?

It explicitly states when to use: when you need the per-item checklist, not just the rule-level summary that check_permit_requirements returns. It also outlines output fidelity differences by jurisdiction, which guides expectation-setting. While it doesn't enumerate all alternatives, it clearly specifies the primary alternative and the condition 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by noting results are 'ranked' and 'grouped by type,' 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 core scope and return format are front-loaded, and the usage guidance is compact but complete.

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, combined with a rich schema and a full set of safety annotations, gives an agent everything needed to select and call this tool correctly. Return value details are covered by the output schema, so no additional explanation is required.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including examples and defaults. The description adds no parameter-specific detail beyond mentioning a 'single keyword query,' which is consistent with the schema but not supplementary.

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 ('search'), a clear resource ('all Kolmo content'), and enumerates the covered types ('services, projects, and blog posts'). It explicitly distinguishes itself from the list_* siblings by naming the alternative approach it replaces.

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

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

Gives direct usage guidance: 'Use this instead of calling list_services + list_projects + list_blog_posts separately.' This makes the when-to-use decision explicit and routes the agent away from less efficient alternatives.

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

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

Annotations already indicate this is a write operation with side effects, so the description's job is lighter. It adds useful behavioral information beyond the annotations by explaining that dryRun previews the submission without actually sending it, and it clarifies the action is performed 'on behalf of a user.' It does not cover auth or duplicate risks, but the annotations and dryRun guidance cover the main behavioral concerns.

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 the core action front-loaded and the dryRun preview behavior placed second. It contains no filler, repetition, or 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?

With a fully documented six-parameter schema and an output schema present, the description covers the remaining contextual essentials: what action is taken, who receives the request, and the special preview mode. Nothing critical appears missing for an agent to invoke this 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 of 3 applies; the schema already documents all six parameters clearly. The description only restates the dryRun behavior already described in the schema and adds no new parameter-level semantics or formatting guidance.

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

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

The description uses the specific verb 'Submit' and names the resource and destination: 'a contact or quote request to Kolmo Construction.' This clearly distinguishes the tool from the read-oriented get/list/check sibling tools. The phrase 'on behalf of a user' also adds contextual precision about who the request is for.

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 makes the tool's core use clear and gives practical guidance for the dryRun flag, but it does not explicitly state when to choose this over sibling tools like answer_permit_question or get_estimate. There is no exclusion or alternative guidance, so usage context is implied rather than explicit.

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