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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds valuable context: data source (public L&I data), update frequency (daily), and that it works for any contractor (including competitors). No contradictions with annotations. This exceeds the baseline required by annotation 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 concise—three sentences with no fluff. The core action and data source are front-loaded, followed by usage context. Every sentence adds value without redundancy.

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

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

The tool has an output schema, so return values are covered. The description includes the key details needed: scope (WA contractors), data source, update frequency, and usage scenario. Given the low complexity (single parameter) and output schema, nothing critical is missing. A minor gap is not mentioning potential limitations (e.g., only public data may not include all contractor info), but this is not essential 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?

The schema provides 100% coverage for the single parameter 'query', including format examples for license number or business name. The description does not add additional parameter-specific semantics beyond what the schema already offers, so the baseline 3 for high coverage 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 clearly states the specific action: looking up a Washington State contractor's license, bond, and insurance status. It names the data source (public L&I data) and the scope (any contractor, including competitors), making it distinct from sibling tools 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 provides a clear use case: 'Great for verifying a contractor before hiring.' It implies when to use this tool (pre-hiring verification) but does not explicitly name alternative tools or state when not to use it. The context is sufficient, though exclusions are absent.

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 context beyond those hints: it enumerates the return payload, states a preference for jurisdiction-verified rules, and discloses fidelity differences ('Seattle is full SDCI fidelity, other 9 verified cities are wa-baseline-stub'). This is meaningful but not exhaustive, so a 4 is appropriate.

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

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

The description is dense but efficient: it front-loads the core purpose, lists return contents, gives example usage, and then explains the special address behavior. Every sentence earns its place, though some jargon like 'wa-baseline-stub' and 'unified permit engine' adds complexity without fully clarifying.

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 annotations are rich, the description is nearly complete for selection and invocation. It explains what the tool returns, when to use it, and the key address-dependent behavior. It could be more explicit about default jurisdiction behavior or the role of limit, but those are covered by the schema and are not major gaps.

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 each parameter is already documented in the schema. The description mostly restates the address behavior already captured in the schema ('when provided, the response includes `submittals_v2`') and does not add new meaning for projectType, limit, or the deck parameters. Baseline 3 is correct.

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

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

The description states a specific action ('Check whether a residential construction project... requires a permit'), names the geographic scope (King/Pierce/Snohomish counties), and lists concrete return items. The 'Use for...' examples make the intended query patterns unmistakable and help distinguish this tool from broader permit-related siblings like answer_permit_question.

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

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

The description gives explicit example queries ('Do I need a permit to build a deck in Seattle?') and a clear behavioral note ('Pass `address` to also receive...'). It does not explicitly name alternative tools or state when not to use it, so it stops short of a full 5, but the usage context is clear.

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

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

Annotations already signal read-only and idempotent behavior. The description adds useful return-value context—the yes/no/nearby verdict, matched service city, and completed-project count—and frames the tool as a pre-recommendation check, all consistent with the annotations.

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

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

Three tight sentences: function, return values, and usage context. The main verb and resource are front-loaded, and every sentence earns its place without redundancy or 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?

For a single-parameter, read-only lookup with an output schema, the description covers everything an agent needs: what the tool does, what it returns, and when to invoke it. No significant gap 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 schema already documents the single 'location' parameter at 100% coverage with examples. The description reinforces this by adding the geographic scope ('Seattle / King County area') and naming the three accepted forms (city, neighborhood, ZIP), which augments the schema meaning.

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

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

The description opens with a specific verb and resource: 'Check whether Kolmo services a given city, neighborhood, or ZIP in the Seattle / King County area.' This clearly distinguishes it from sibling tools by naming the exact geospatial coverage task and geographic scope.

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

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

The final sentence gives an explicit when-to-use instruction: 'Use before recommending Kolmo to a lead to confirm coverage.' It provides clear context for selection, though it does not explicitly name when not to use it or suggest 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 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond what the annotations provide, such as data freshness, source, or output characteristics. With no additional behavioral disclosure, this dimension is minimally served.

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

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

The description is a single, efficient sentence with the action and resource first, followed by a clear list of content areas. Every word earns its place, and there is no filler or redundant restatement of the tool name.

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

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

This is a low-complexity, parameterless retrieval tool with a comprehensive annotation profile and an output schema available. The description tells the agent exactly what kind of company information will be returned. Nothing essential for selecting and invoking the tool is missing.

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

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

There are zero parameters, and the schema coverage is 100%, so there are no parameter semantics for the description to clarify. The description's enumeration of returned categories adds some value for callers even though it is not parameter-related. A baseline of 4 is appropriate for a parameterless tool.

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, naming 'Kolmo Construction company information' and enumerating the content areas: contact details, hours, service area, specializations, and tools. This is sufficiently distinct from sibling getters like get_service, get_blog_post, or get_estimate, so an agent can identify the correct tool without ambiguity.

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 a caller needs general company information, including contact details and specializations. However, it does not explicitly say when not to use it or name a more specific alternative among the many sibling getters. The context is clear but the exclusion guidance is absent.

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, and the description reinforces this with a calculation/estimate framing. It adds valuable behavioral detail beyond annotations: close material ID matches resolve, ambiguous IDs return a valid list, certain fields have defaults, and some fields are conditionally required. This goes well beyond what annotations alone 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 long, but every section earns its place given the 13 project types and nested input complexity. It is front-loaded with purpose and return summary, then material resolution guidance, then compact project-specific schemas. There is no filler or redundancy.

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

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

For a tool with this many project types and nested objects, the description is remarkably complete: it documents required fields, optional fields, defaults, constraints, enums, and cross-tool dependency on get_material_options. An output schema exists, so the brief return-value summary is sufficient.

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

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

Although both schema properties have descriptions, the real parameter semantics live in the tool description: per-project-type required fields, optional markers, enums, numerical ranges, default behaviors, and material ID constraints. This is extensive, precise, and covers every parameter across all 13 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 a specific verb and resource: 'Calculate a Seattle-area cost estimate.' It lists concrete outputs (planning range, point cost, material/labor split, days, itemized line items) and is clearly distinct from siblings like get_material_options or get_project.

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

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

The description clearly establishes when to use the tool: for Seattle-area cost estimates by projectType. It also directs the agent to get_material_options for material IDs. It lacks explicit exclusion statements, but the context is clear enough that an agent will not confuse it with the listed sibling tools.

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

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

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 fully covered. The description adds useful context about the output being IDs for get_estimate, but it does not disclose additional behavioral traits such as response size, ordering, or availability assumptions. This is adequate 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?

The description is two sentences with no filler: the first states the purpose with concrete examples, and the second gives the essential integration hint. It is front-loaded and every clause earns its place.

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

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

For a single-parameter tool with a full enum, rich read-only/idempotent annotations, and an output schema, the description is complete enough for an agent to call it correctly. It even explains how the results should be used downstream, which reduces ambiguity about the return value's role.

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 projectType parameter already has an enum plus a clear description. The tool description lists example material categories but does not add meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get available material choices for a project type,' and then gives concrete examples that immediately clarify scope. It also connects the output to get_estimate, further distinguishing this from generic catalog or reference tools. Even without naming sibling tools, the project-type framing is a clear differentiator.

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 the downstream context: 'Use the returned IDs in the project fields of get_estimate,' which tells an agent when this tool is useful. It does not explicitly name alternatives like get_material_catalog or state exclusions, so it stops short of the strongest usage guidance.

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

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

Annotations already 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 readOnlyHint, idempotentHint, and destructiveHint, so the safe read-only nature is established. The description adds useful behavioral scope: it lists only completed projects, includes photos and locations, and clarifies that both residential and commercial/public-works portfolios are covered. 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 front-loaded with the core action and scope, then provides focused filter guidance. The second sentence is somewhat long with many examples, but those examples are directly relevant to correct parameter usage. No filler or redundant restatement of the tool name.

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 4-parameter schema with 100% description coverage, an output schema, and safety annotations, the description is largely complete. It covers what gets listed, the category filtering behavior, and the return contents (photos and locations). Minor missing details like default category behavior and pagination are already handled by the schema's parameter descriptions.

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. The description adds extra value by explaining the category parameter's meaningful values ('commercial' or 'public-works') and giving concrete examples of what counts as commercial work, which helps the agent choose correct category inputs.

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 Kolmo's completed projects', and clearly distinguishes the scope (residential remodels plus commercial/public-works) from the many sibling tools. The title 'Completed project portfolio' reinforces the purpose and makes it easy for an agent to select this tool over get_project, list_services, or list_project_types.

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

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

The description gives concrete guidance on how to filter: 'Filter by category or keyword' and explicitly instructs to pass category 'commercial' or 'public-works' for commercial portfolio results. It does not name sibling alternatives or exclusion conditions, but the usage context is clear enough for correct invocation.

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, so the safety profile is covered. The description adds useful behavioral context by stating the tool returns all 13 types along with their required input fields and descriptions, which 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 two sentences with no filler. The first sentence states the core action and deliverable, and the second offers a practical usage hint, making it easy to scan and act on.

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

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

For a zero-parameter list tool with a read-only, idempotent annotation profile and an output schema, the description provides everything an agent needs. It names the exact result count, what the result items contain, and how the tool fits into a larger workflow.

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

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

The tool has zero parameters, so there is nothing for the description to explain. The schema coverage is effectively 100% since the input schema is empty, and the description correctly focuses on the discovery value instead.

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

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

The description uses a specific verb ('List') and resource ('all 13 supported calculator project types'), and specifies the content: required input fields and descriptions. The phrase 'calculator project types' clearly distinguishes it from sibling list tools like list_projects and list_services.

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

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

The description provides clear usage context by stating it is useful for discovery before calling get_estimate. It does not explicitly mention when not to use it, but the discovery-before-estimate guidance gives an agent enough context to select it 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 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?

Beyond the read-only/idempotent annotations, the description reveals that zoning, setbacks, and building facts carry their source, while geocode, lot geometry, and assessor records do not. It also lays out the geocode-resolve-return flow, adding meaningful behavioral context the annotations do not provide.

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

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

The description is four sentences, each earning its place: purpose, pipeline/outputs, source-attribution caveat, and usage guidance. It is front-loaded with the most important fact and reads as a compact operational brief.

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

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

For an address lookup with two well-documented parameters and an output schema, the description covers the service area, inputs, outputs, data provenance, and downstream actions. There is no obvious missing context an agent would need 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?

The schema already fully documents both parameters, so the baseline is 3. The description adds modest value by calling it 'address-first' and specifying the county scope and use pattern, but it does not add depth to forceRefresh beyond the schema 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 'Address-first parcel lookup' and then names the exact pipeline: geocoding, parcel resolution, and return of zoning, setbacks, overlays, lot area, jurisdiction routing, and prior-permit history. This clearly separates it from sibling tools like 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?

It explicitly tells the agent when to use this tool ('what can be built at 123 Main St Seattle?') and where it sits in a workflow ('before calling check_permit_requirements / estimate_permit_fee'). This is concrete routing guidance rather than a generic statement.

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 those hints by noting the use of real-time L&I data and the explicit gap callouts with an example format. 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 concise at two sentences, front-loaded with the core action, and includes a concrete example of gap callouts and data-source context. Every sentence contributes meaningful information without redundancy.

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

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

Given the presence of a complete input schema, an output schema, and read-only annotations, the description covers the essential behavioral and purpose context: what is matched, what is returned, and the data sources involved. Nothing material appears 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%, with each of the three parameters already described in the schema. The description does not add further parameter-level detail, so a baseline 3 is appropriate rather than a higher score for compensatory explanation.

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: 'Cross-reference a WA contractor's L&I license specialty against a permit's required specialties.' This clearly differentiates it from sibling tools like check_contractor_license_status or check_permit_requirements, since the focus is on the cross-reference matching action rather than a single status or requirement lookup.

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: use when you need to determine whether a contractor is qualified for a specific permit. However, there is no explicit when-to-use or when-not-to-use guidance, and no reference to sibling alternatives such as check_contractor_license_status or check_permit_requirements, leaving routing decisions 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 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral detail not in annotations: output fidelity varies by jurisdiction (Seattle 'full', others 'wa-baseline-stub', unverified 'no-spec'). This context helps an agent set expectations and avoid misinterpreting results.

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

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

The description is three sentences, each earning its place: it states the core function, specifies when to use it (with sibling comparison), and discloses output fidelity across jurisdictions. Information is front-loaded and there is zero 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?

Given the 6-parameter tool, presence of an output schema, and rich annotations, the description is largely complete. It tells what the tool returns, when to use it, and the jurisdiction variability. Minor omissions like pagination or error handling are acceptable because output schema exists and annotations cover safety. It does not duplicate schema details.

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

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

The input schema has 100% description coverage, so each parameter (address, scope, envelopeChange, etc.) is fully documented. The tool description does not add extra meaning about parameters beyond what the schema already provides, hitting the baseline of 3 as expected when schema carries the load.

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

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

The description clearly states a specific verb ('Resolve') and resource ('structured submittal-item set for a specific parcel + permit scope'), and explicitly contrasts it with check_permit_requirements, distinguishing its purpose. It also mentions the pipeline and output nature, leaving no ambiguity about what the tool does.

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

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

The description explicitly says 'Use this when you need the per-item checklist ... not just the rule-level summary that check_permit_requirements returns,' naming the alternative and the condition that selects this tool. It also clarifies jurisdiction-specific output behavior, giving concrete guidance on expected results.

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.