kolmo-mcp-server

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates the tool's purpose and data freshness ('updated daily'), but doesn't mention potential limitations like rate limits, authentication requirements, error conditions, or what happens with invalid queries. The description doesn't contradict any annotations since none exist.

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 efficiently structured with two sentences that each serve distinct purposes: the first explains what the tool does and its scope, the second provides practical usage context. Every word contributes value with no redundancy or filler 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 single-parameter lookup tool with no output schema, the description provides adequate context about what information is retrieved and why to use it. However, without annotations and with no output schema, it could benefit from more detail about return format, potential errors, or data limitations to be fully complete.

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

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

Schema description coverage is 100%, so the schema already fully documents the single 'query' parameter. The description doesn't add any additional parameter semantics beyond what's in the schema description. This meets the baseline expectation when schema coverage is high.

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 ('look up'), resource ('Washington State contractor's license, bond, and insurance status'), and data source ('public L&I data updated daily'). It distinguishes this tool from siblings by focusing on contractor verification rather than permits, projects, or other 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 context for when to use this tool ('verifying a contractor before hiring') and specifies it works for 'any Washington State contractor' including competitors. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the 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?

No annotations are provided, so the description carries the full burden. It mentions the tool provides 'estimated permit cost' and 'official source links', which adds some behavioral context beyond basic functionality. However, it doesn't disclose critical traits like whether this is a read-only operation, if it requires authentication, rate limits, accuracy of estimates, or how recent the information is. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

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

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

The description is efficiently structured in two sentences: the first states the core functionality, and the second provides usage examples. Every sentence adds value without redundancy, and it's front-loaded with the main purpose. No wasted words or unnecessary 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?

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the purpose and usage well but lacks behavioral details (e.g., data sources, update frequency, limitations) and doesn't explain the output format. Without annotations or an output schema, more context on what to expect from the tool would improve completeness.

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

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

The input schema has 100% description coverage, clearly documenting both parameters ('location' and 'projectType') with examples. The description doesn't add any additional parameter semantics beyond what's in the schema—it doesn't explain how these parameters affect the output or provide further context. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: checking permit requirements, estimated cost, and providing official source links for Seattle-area construction projects. It uses specific verbs ('check', 'requires', 'estimated') and identifies the resource ('construction project'). However, it doesn't explicitly differentiate from sibling tools like 'get_estimate' or 'list_project_types' which might overlap in domain.

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: for questions about permit requirements and costs for construction projects in the Seattle area, with examples like building a deck or kitchen remodel. It doesn't explicitly state when not to use it or name alternatives among siblings, but the context is sufficiently specific to guide usage.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is retrieved (biography, credentials, etc.), which is useful context. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving gaps in behavioral understanding for a tool with no annotations.

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

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

The description is two sentences, front-loaded with the core purpose and followed by usage examples. Every word earns its place without redundancy, making it efficient and well-structured for quick 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?

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete. It covers purpose and usage well. However, without annotations or an output schema, it lacks details on return format or behavioral traits like error handling, which slightly reduces completeness for a tool with no structured metadata.

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, with the 'author' parameter documented as 'Author name or slug'. The description doesn't add any parameter-specific details beyond this, but since schema coverage is high, the baseline is 3. It gets a 4 because the description reinforces the tool's focus on author data, which aligns with the parameter's purpose, adding slight contextual value.

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 ('Get') and resource ('biography, credentials, expertise areas, and recent articles for a Kolmo Construction blog author'), making the purpose specific. It distinguishes from siblings like 'get_blog_post' (which gets content) and 'list_blog_posts' (which lists posts), as this tool focuses on author 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?

The description explicitly states when to use this tool: 'to answer "who wrote this?" or to add author context to blog content.' This provides clear scenarios for usage, and it implicitly distinguishes from siblings by focusing on author information rather than blog content, projects, or other resources.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieving content but does not specify whether this is a read-only operation, if authentication is required, potential rate limits, error handling, or the format of the returned markdown. For a tool with no annotation coverage, this leaves significant behavioral gaps.

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 that front-loads the core purpose ('Get the full markdown content of a blog post') and includes essential detail ('by its slug') without any wasted words. It is appropriately sized for the tool's simplicity.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and parameter context but lacks details on behavioral aspects like safety, permissions, or return format, which are important for a tool with no structured annotations or output schema.

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

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

The schema description coverage is 100%, with the parameter 'slug' fully documented in the schema as 'The URL slug of the blog post'. The description adds no additional semantic context beyond what the schema provides, such as examples or constraints, so it meets the baseline for high schema coverage without compensating value.

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

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

The description clearly states the specific action ('Get'), resource ('full markdown content of a blog post'), and mechanism ('by its slug'), distinguishing it from sibling tools like 'list_blog_posts' which likely lists posts without full content. It precisely defines what the tool does 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 usage when you need the full content of a specific blog post identified by its slug, but it does not explicitly state when to use this tool versus alternatives like 'list_blog_posts' or 'search_content'. There is no guidance on exclusions or prerequisites, leaving some context 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?

With no annotations provided, the description carries full burden but only states what data is retrieved without disclosing behavioral traits like rate limits, authentication needs, or response format. It mentions no constraints or side effects, leaving gaps for a read operation.

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 that front-loads the purpose and lists key data points without waste. It could be slightly more structured but is appropriately sized for a no-parameter tool.

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

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

Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers what data is fetched but lacks details on behavior, response format, or error handling, making it minimally viable for a simple read tool.

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

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

The tool has 0 parameters with 100% schema description coverage, so no parameter info is needed. The description adds value by specifying the types of company information retrieved (e.g., contact details, service area), which goes beyond the empty schema, earning a baseline 4.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('Kolmo Construction company information'), including details like contact details, hours, and specializations. It distinguishes from siblings by focusing on company info rather than projects, services, or other data, though it doesn't explicitly name alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'get_service' or 'list_services', nor does it mention prerequisites or exclusions. It implies usage for retrieving company info but lacks explicit context for selection among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool returns specific cost breakdowns, handles material ID resolution with fallback logic, provides error messages for ambiguous inputs, and has complex project-type-specific requirements. It doesn't mention rate limits, authentication needs, or mutation effects, but covers core functionality well for a calculation tool.

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

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

The description is excessively long and poorly structured—it's a massive block of technical specifications rather than a concise tool overview. While the information is valuable, it should be front-loaded with a summary and better organized. The length (over 500 words) makes it difficult to parse quickly.

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

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

Given the tool's high complexity (11 project types with nested structures), no annotations, and no output schema, the description provides complete contextual information. It explains what the tool does, how to use it, parameter semantics, material ID handling, error behavior, and return values—everything needed to understand and invoke the tool correctly.

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

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

The description adds extensive meaning beyond the input schema. While the schema has 100% description coverage for its 2 parameters, the description details 11 projectType-specific structures with nested objects, enums, and conditional fields—compensating for the schema's generic 'additionalProperties' approach. It explains material ID resolution strategies and required fields per projectType.

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

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

The description clearly states the tool's purpose: 'Calculate a Seattle-area cost estimate' with specific outputs (total, material, labor costs, days, itemized line items). It distinguishes itself from siblings like get_material_options by focusing on cost calculation rather than material lookup or other functions like checking licenses or 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 clear context for when to use this tool (for cost estimation of various project types in Seattle) and references get_material_options as a helper for material IDs. However, it doesn't explicitly state when NOT to use it or compare it to all sibling alternatives like get_project_roi or get_financing_options.

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?

No annotations are provided, so the description carries full burden. It mentions what the tool returns (loan types, payments, terms, eligibility notes) but doesn't disclose behavioral traits like rate limits, authentication needs, data freshness, or whether this is a simulation vs real application. The description is functional but lacks operational context.

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

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

Two sentences efficiently convey purpose and scope. The first sentence front-loads the core functionality, and the second adds helpful context about specific financing types. No wasted words, though the second sentence could be slightly more concise.

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

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

For a tool with 2 parameters, 100% schema coverage, and no output schema, the description provides adequate purpose and return value information. However, without annotations and with no output schema, it should ideally mention more about the response format structure or data limitations to be fully complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema (projectBudget requirement, creditProfile enum values). Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb 'Get' and resource 'home improvement financing options' with specific context 'for a Seattle remodeling project'. It distinguishes from siblings by focusing on financial options rather than contractor checks, permits, materials, or content retrieval.

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

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

The description implies usage for homeowners understanding payment options for remodels, but doesn't explicitly state when to use this vs alternatives like 'get_estimate' or 'get_project_roi'. No explicit exclusions or comparisons to sibling tools are 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?

With no annotations provided, the description carries full burden. It mentions browsing with pricing and returns material IDs, but doesn't disclose pagination behavior (implied by limit/offset), rate limits, authentication needs, or error conditions. The description adds basic behavioral context but lacks comprehensive disclosure for a catalog browsing tool.

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

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

The description is appropriately concise with two sentences. The first sentence front-loads the core purpose with examples, and the second provides key usage notes. No wasted words, though it could be slightly more structured for optimal scanning.

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

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

Given 4 parameters with full schema coverage but no output schema or annotations, the description provides adequate context for a read-only catalog tool. However, it doesn't explain the return format beyond 'material IDs compatible with get_estimate', leaving gaps in understanding the output structure and any limitations.

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 all 4 parameters. The description adds minimal value beyond the schema: it mentions 'Use category to filter' which aligns with the schema's category parameter description. No additional parameter semantics are provided, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Browse the full material catalog with pricing' and lists specific material types (flooring, paint, decking, etc.). It distinguishes from sibling 'get_material_options' by specifying it returns material IDs compatible with 'get_estimate', though the distinction could be more explicit about scope differences.

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 some usage context: 'Use category to filter' and mentions compatibility with 'get_estimate'. However, it doesn't explicitly state when to use this vs. 'get_material_options' or other filtering alternatives, leaving the agent to infer from the description's details.

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

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

With no annotations provided, the description carries the full burden. It implies a read-only operation by using 'Get', but does not disclose behavioral traits such as authentication needs, rate limits, error conditions, or the format/structure of the returned material choices. It adds some context about the purpose of returned IDs.

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 purpose in the first clause, followed by a practical usage note. Both sentences are essential—the first defines the tool, and the second guides integration with another tool—with zero wasted words.

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

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

Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is adequate but incomplete. It explains the purpose and usage with 'get_estimate', but lacks details on return values, error handling, or behavioral constraints, which are important for a tool with no output schema or annotations.

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 single parameter 'projectType' with its enum values. The description adds marginal value by implying the parameter selects among material categories like flooring or paint, but does not provide additional syntax or format details 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 clearly states the verb 'Get' and resource 'available material choices for a project type', with specific examples like flooring types, paint grades, etc. It distinguishes from siblings by focusing on material options rather than estimates, licenses, or other project-related functions.

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

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

The description provides clear context on when to use it ('for a project type') and hints at an alternative use case ('Use the returned IDs in the project fields of get_estimate'), but does not explicitly state when not to use it or compare with all relevant siblings like 'get_material_catalog'.

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?

No annotations are provided, so the description carries the full burden. It discloses the tool's behavior by stating it returns 'project counts by category, example projects, and typical project descriptions', but lacks details on potential limitations (e.g., data freshness, coverage of all neighborhoods, error handling). It does not contradict any 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 front-loaded with the core purpose, followed by return details and usage examples, all in two efficient sentences with zero wasted words. Every sentence adds value by clarifying functionality or context.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is largely complete—it explains what the tool does, when to use it, and what it returns. However, without annotations or output schema, it could benefit from more behavioral details (e.g., data scope or limitations) to fully compensate for the lack of structured data.

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

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

The input schema has 100% description coverage, with the single parameter 'neighborhood' well-documented in the schema. The description adds minimal value beyond the schema by implying the parameter's use for 'Seattle neighborhood or city' queries, but does not provide additional syntax or format details. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('see what remodeling projects... has completed') and resource ('Kolmo Construction'), and distinguishes it from siblings by focusing on neighborhood-level project activity rather than general listings (like list_projects) or other business functions. It explicitly mentions the return data (project counts, examples, descriptions).

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 usage guidance with examples ('e.g. "Has Kolmo worked in Ballard?" or "What has Kolmo done in Capitol Hill?"'), specifies the context ('hyperlocal social proof'), and distinguishes it from siblings by focusing on neighborhood-specific queries rather than broader searches or other contractor-related tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the lookup mechanism (slug), the fallback behavior ('If not found, returns a list of available slugs'), and the data scope (details, images, testimonial). It does not cover potential errors, rate limits, or authentication needs, but provides substantial operational context.

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

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

The description is front-loaded with the primary purpose in the first sentence and uses a second sentence to clarify fallback behavior. Both sentences earn their place by providing essential operational context without redundancy or fluff, making it highly efficient.

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 no annotations and no output schema, the description does well by covering the tool's purpose, usage context, key behavior (fallback), and data scope. It adequately compensates for the lack of structured fields, though it could benefit from mentioning output format or error handling for full completeness.

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

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

Schema description coverage is 100%, with the parameter 'slug' documented as 'The URL slug of the project'. The description adds context by specifying it's used 'by its slug' and mentions the fallback behavior, but does not provide additional semantic details beyond what the schema already covers, meeting the baseline for high coverage.

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

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

The description clearly states the verb ('Get full details') and resource ('for a specific project'), specifying the lookup mechanism ('by its slug') and the scope of returned data ('including before/after images and testimonial'). It explicitly distinguishes from sibling 'list_projects' by focusing on individual project retrieval rather than listing.

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 ('for a specific project by its slug') and implicitly contrasts with 'list_projects' for bulk retrieval. However, it does not explicitly state when NOT to use it or name alternatives beyond the implied distinction, missing full explicit 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool's purpose and data source but doesn't describe important behavioral traits like whether it's a read-only operation, what format the ROI is returned in (percentage, dollar amount), whether it provides historical trends, or any rate limits. The description adds useful context about the geographic and data scope but leaves gaps in operational behavior.

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

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

The description is appropriately sized at three sentences, front-loaded with the core purpose. Each sentence adds value: the first states what the tool does, the second specifies data source and scope, the third provides usage context with examples. There's no redundant information, though the example queries could be slightly more concise.

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

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

For a tool with 2 parameters, 100% schema coverage, but no annotations and no output schema, the description provides adequate purpose and usage context but lacks details about return format, data freshness, error conditions, or limitations. The description covers the 'what' and 'why' sufficiently but doesn't address important operational aspects that would help an agent use it effectively.

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 both parameters thoroughly. The description mentions 'projectType' through examples ('kitchen remodel') and 'estimatedCost' through context ('project budget'), but doesn't add meaningful semantic information beyond what's in the schema. It implies optional parameters through 'Omit to see all projects' but this is already clear from the schema's lack of required parameters.

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

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

The description clearly states the tool's purpose: 'Get the estimated return on investment (ROI) for a home remodeling project in the Seattle area.' It specifies the verb ('Get'), resource ('ROI'), geographic scope ('Seattle area'), and data source ('Remodeling Magazine Cost vs. Value data for the Pacific Northwest'). It distinguishes from siblings like 'get_estimate' or 'list_projects' by focusing on ROI calculation rather than general project details or cost estimates.

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

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

The description provides clear context for when to use the tool: 'Helps homeowners decide which projects add the most resale value' with example queries like 'What ROI does a kitchen remodel get in Seattle?' or 'Which remodel pays off the most?' It implicitly suggests using this for ROI comparisons rather than other project-related queries handled by siblings. However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different needs.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'Get'), handles not-found cases by returning a list of slugs, and specifies the resource type as 'residential service'. However, it doesn't mention potential errors, rate limits, or authentication needs, leaving some gaps for a tool with no annotations.

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

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

The description is two sentences, front-loaded with the main purpose and followed by the fallback behavior. Every sentence adds value: the first defines the tool's core function, and the second clarifies error handling and usage guidance, with no wasted words.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, usage, and key behavior. However, it lacks details on output format or error handling beyond the not-found case, which could be useful for an agent, though not critical for this simple tool.

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

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

Schema description coverage is 100%, so the schema already documents the 'slug' parameter with an example. The description adds context by explaining what the slug is used for ('to get full details') and the fallback behavior, but doesn't provide additional semantic details beyond what the schema offers, meeting the baseline for high coverage.

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

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

The description clearly states the verb 'Get' and resource 'full details for a specific residential service', specifying the identifier 'by its slug'. It distinguishes from siblings like 'list_services' (which lists services) and 'list_commercial_services' (which focuses on commercial services), making the purpose specific and differentiated.

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 ('for a specific residential service by its slug') and provides an alternative behavior ('If not found, returns a list of available slugs to help you pick the right one'), which implicitly guides usage by suggesting to check available slugs first if uncertain, and distinguishes from list-based tools like 'list_services'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal key behaviors: it's location-specific (Seattle), provides recommendations based on project requirements, and returns a structured forecast. However, it doesn't disclose important operational details like rate limits, authentication needs, data freshness, or what happens when parameters are omitted (e.g., default days behavior). The description doesn't contradict any annotations since none exist.

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 appropriately sized with two sentences that are front-loaded with the core purpose. The first sentence clearly states what the tool does, and the second adds valuable context about perfect use cases. There's minimal redundancy, though the list of project examples could be slightly trimmed since they're already in the schema enum.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but has gaps. It explains the purpose and context well, but doesn't describe the return format beyond 'day-by-day forecast with go/no-go recommendations' - no details about structure, units, or confidence levels. For a recommendation tool with no output schema, more information about the response would be helpful.

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 fully documents both parameters. The description adds some context by mentioning 'project-specific requirements' that map to the projectType enum, but doesn't provide additional semantic meaning beyond what's in the schema descriptions. It doesn't explain how different project types affect the recommendations or clarify the relationship between days and projectType.

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

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

The description clearly states the tool's purpose with specific verbs ('check', 'returns') and resources ('upcoming weather in Seattle', 'day-by-day forecast with go/no-go recommendations'). It explicitly distinguishes this weather-checking tool from all sibling tools which focus on contractors, permits, content, projects, services, and business information rather than weather analysis.

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 about when to use this tool: for 'scheduling exterior construction projects' with specific examples like painting, decking, roofing, etc. However, it doesn't explicitly state when NOT to use it or mention alternatives (e.g., general weather forecast tools), and doesn't address potential conflicts with sibling tools like 'get_project' or 'list_projects' that might also involve scheduling.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions filtering capabilities but omits critical details: whether the tool is read-only (implied by 'List' but not stated), pagination behavior (offset/limit are in schema but not explained in description), rate limits, authentication needs, or what the return format looks like (no output schema). This leaves significant gaps for safe and effective use.

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 that front-loads the core purpose and key filtering options. Every word contributes directly to understanding the tool's function, with zero redundant or vague phrasing, making it highly scannable and actionable.

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

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

Given the tool's moderate complexity (4 parameters, filtering logic) and lack of annotations and output schema, the description is incomplete. It fails to address behavioral aspects like safety (read-only vs. mutative), response format, error handling, or usage constraints, leaving the agent under-informed for reliable invocation in a broader context.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters (tag, limit, author, offset). The description adds minimal value beyond the schema by mentioning filtering by 'tag or author name', which is already covered. No additional semantics like default behaviors or usage examples are provided, meeting the baseline for high schema coverage.

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

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

The description clearly states the verb ('List') and resource ('published blog posts') with specific topical scope ('home remodeling, renovation costs, and construction tips'), making the purpose unambiguous. It distinguishes from most siblings like 'get_blog_post' (singular retrieval) and 'search_content' (broader search), though not explicitly compared to 'search_content' which might overlap.

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

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

The description implies usage for filtering blog posts by tag or author, but lacks explicit guidance on when to use this tool versus alternatives like 'search_content' (which might handle broader queries) or 'get_blog_post' (for single posts). No exclusions or prerequisites are mentioned, leaving the agent to infer context.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions filtering capabilities and some certification details for the 'public' category, but doesn't describe return format, pagination behavior, error conditions, or performance characteristics. For a list tool with 3 parameters, this leaves significant behavioral gaps.

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 reasonably concise but has structural issues. The first sentence clearly states the purpose, but the second sentence mixes filtering information with certification details that belong elsewhere. The certification information about Kolmo is contextually relevant but disrupts the flow and could be better organized.

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 list tool with 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't describe the return format, pagination behavior, or what constitutes a 'service' in this context. The certification details for 'public' category are useful but don't compensate for missing core behavioral information.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds marginal value by listing the category filter options and providing certification context for 'public', but doesn't explain parameter interactions or provide usage examples beyond what's in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'List commercial construction services' with optional filtering by category. It specifies the resource (services) and verb (list), but doesn't distinguish it from sibling 'list_services' which appears to be a broader version. The description is specific about the commercial construction context.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'list_services' or 'get_service'. It mentions filtering capabilities but offers no context about appropriate use cases, prerequisites, or exclusions. The agent must infer usage from the tool name alone.

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

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

With no annotations provided, the description carries full burden. It mentions filtering and that projects are 'completed' with photos/locations, but doesn't disclose behavioral traits like pagination behavior (implied by limit/offset but not explained), rate limits, authentication requirements, or what happens with no filters. The description is minimal beyond basic functionality.

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 that front-loads the core purpose ('List completed remodeling projects...') and adds filtering details. Every word earns its place with zero waste 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 read-only list tool with 4 parameters and 100% schema coverage but no output schema, the description is adequate but has gaps. It covers what's listed and filtering options, but lacks context on result format (e.g., what fields are returned), pagination details, or error conditions. It meets minimum viability given the schema handles parameters.

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

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

Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds marginal value by mentioning 'Filter by category or keyword', which maps to 'category' and 'search' parameters, but doesn't provide additional semantics beyond what's in the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('List') and resource ('completed remodeling projects'), specifying they include 'before/after photos and locations'. It distinguishes from siblings like 'list_blog_posts' or 'list_services' by focusing on projects, but doesn't explicitly differentiate from 'list_project_types' 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 provides no guidance on when to use this tool versus alternatives like 'get_project' (for single project details), 'list_project_types' (for categories), or 'search_content' (for broader searches). It mentions filtering capabilities but gives no context for tool selection.

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

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

No annotations are provided, so the description carries the full burden. It describes what the tool returns (project types with input fields and descriptions), which is useful, but lacks details on behavioral traits like rate limits, error handling, or response format. It adds some value but not comprehensive behavioral context.

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

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

The description is two sentences, front-loaded with the core purpose and followed by usage guidance. Every sentence earns its place with no wasted words, making it highly 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?

Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is complete enough for its purpose. It explains what the tool does and when to use it, though it could benefit from more behavioral details like response format. It adequately covers the essential context.

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

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

The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description does not add parameter semantics, but with no parameters, a baseline of 4 is appropriate as it doesn't need to compensate for gaps.

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

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

The description clearly states the tool's purpose with a specific verb ('List') and resource ('all 11 supported calculator project types'), and it distinguishes from siblings by specifying it's for discovery before using 'get_estimate', which is a sibling tool. This provides precise differentiation.

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

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

The description explicitly states when to use this tool ('Useful for discovery before calling get_estimate'), providing clear context and an alternative (use 'get_estimate' after discovery). This gives direct guidance on usage versus 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?

No annotations are provided, so the description carries the full burden. It mentions combining sources and filtering, but lacks details on permissions, rate limits, pagination behavior (beyond schema hints), or what the output looks like (e.g., format, fields). For a list tool with zero annotation coverage, this is a significant gap in behavioral disclosure.

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

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

The description is appropriately sized and front-loaded, with two concise sentences that directly state the tool's purpose and key functionality. Every sentence earns its place by providing essential information without redundancy or fluff.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the purpose and basic filtering, but lacks details on output format, error handling, or integration context, which would be helpful for an agent to use it effectively.

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 all parameters. The description adds minimal value by mentioning 'Filter by minimum star rating', which aligns with the 'minRating' parameter but doesn't provide additional semantics beyond what the schema already specifies. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('List', 'Filter') and resources ('customer reviews and testimonials for Kolmo Construction'), and distinguishes it from siblings by specifying it combines verified Google reviews and on-site testimonials, unlike other tools that focus on projects, services, or business info.

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

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

The description implies usage by mentioning filtering capabilities (e.g., by minimum star rating), but does not explicitly state when to use this tool versus alternatives like 'get_business_info' or 'list_projects'. No exclusions or specific contexts are provided, leaving usage somewhat open-ended.

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?

No annotations are provided, so the description carries full burden. It mentions the tool lists services with specific fields, which is helpful, but doesn't disclose behavioral traits like pagination behavior (implied by limit/offset parameters but not explained), rate limits, authentication needs, or error conditions. The description adds basic context but lacks depth for a tool with parameters.

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 concise sentences with zero waste. The first sentence front-loads the core purpose and output, and the second sentence provides crucial usage guidance. Every word earns its place, making it highly efficient.

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

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

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is reasonably complete. It covers purpose, output fields, and usage guidelines. However, it lacks details on behavioral aspects like pagination or error handling, which would be beneficial for full completeness.

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

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

Schema description coverage is 100%, so the schema fully documents the three parameters (limit, offset, search). The description adds minimal value beyond the schema by mentioning 'search' for keyword filtering, but doesn't explain parameter interactions or provide additional semantics. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('List all'), resource ('residential remodeling services'), and output fields ('slugs, descriptions, and page URLs'). It distinguishes from sibling tools like 'list_commercial_services' by specifying 'residential' and from 'search_content' by indicating this tool lists all services while search is for keyword filtering.

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

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

The description explicitly provides when to use this tool ('List all residential remodeling services') versus alternatives ('Use `search` to find by keyword'), naming the specific sibling tool 'search' for keyword-based filtering. This gives clear guidance on tool selection.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description reveals that the tool returns 'ranked results grouped by type,' which adds valuable behavioral context beyond the input schema. However, it doesn't mention other important behavioral aspects like pagination, error handling, or performance characteristics that would be helpful for a search tool.

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

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

The description is perfectly concise with just two sentences that each earn their place. The first sentence establishes purpose and scope, while the second provides crucial usage guidance. There's no wasted language, and the most important information (what the tool does and when to use it) is front-loaded effectively.

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 search tool with 3 parameters, 100% schema coverage, but no annotations or output schema, the description provides good contextual completeness. It explains the tool's purpose, scope, and usage guidelines clearly. The main gap is the lack of output format details (since there's no output schema), but the description does mention that results are 'ranked' and 'grouped by type,' which provides some output context.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain search algorithm details or ranking criteria). With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding but doesn't need to compensate for gaps.

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

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

The description clearly states the tool's purpose with specific verbs ('Search across all Kolmo content') and resources ('services, projects, and blog posts'). It explicitly distinguishes this tool from its siblings (list_services, list_projects, list_blog_posts) by stating it searches across all content types with a single query, making the differentiation unambiguous.

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

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

The description provides explicit usage guidance by stating when to use this tool ('Use this instead of calling list_services + list_projects + list_blog_posts separately'). It clearly identifies the alternative approach (calling multiple sibling tools) and recommends this tool as a consolidated alternative, giving the agent clear decision-making criteria.

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

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

With no annotations provided, the description carries the full burden. It discloses the dryRun behavior (preview vs. actual submission), which is a key behavioral trait. However, it doesn't mention other important aspects like authentication requirements, rate limits, error handling, or what happens after submission (e.g., confirmation, follow-up). The description is accurate but incomplete for a mutation tool.

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

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

The description is two sentences, front-loaded with the core purpose and followed by a specific usage tip for dryRun. Every sentence earns its place with no wasted words, making it highly efficient and easy to parse.

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 mutation tool with no annotations and no output schema, the description is adequate but has gaps. It covers the purpose and dryRun behavior, but lacks details on authentication, response format, error conditions, or integration context. Given the complexity (submitting to a business), more completeness would be beneficial, though it meets minimum viable standards.

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 thoroughly (e.g., name as 'Full name', dryRun as 'If true, validate and preview without submitting'). The description adds minimal value by mentioning dryRun's purpose, but doesn't provide additional semantic context beyond what's in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('Submit a contact or quote request'), identifies the target ('Kolmo Construction'), and specifies the beneficiary ('on behalf of a user'). It distinguishes itself from sibling tools which are primarily informational/query tools (e.g., get_estimate, list_services) by being a submission/mutation tool.

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 guidance on when to use the dryRun parameter ('Set dryRun: true to preview what would be sent without actually submitting'), which implicitly suggests using false for actual submission. However, it doesn't explicitly state when to use this tool versus alternatives like get_estimate or list_services, nor does it mention prerequisites or exclusions.

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