arcat

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

The description clearly explains the behavior for each parameter combination, such as listing all divisions with no parameters and drilling into groups, sections, and narrowscope levels with division and level. This goes well beyond the annotations' read-only and idempotent hints, providing valuable context on how the tool traverses the hierarchy.

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

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

The description is concise and well-structured, using bullet-like lines for each parameter scenario. Every sentence adds value, and the examples are tightly integrated without unnecessary 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 complexity (three optional parameters, hierarchy depth, and section drilling), the description covers all usage modes and provides enough context for correct invocation. Annotations and output schema supply the remaining safety and return-value details, 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?

Although the input schema already documents all three parameters with 100% coverage, the description adds significant semantic detail. It defines each level (1=Group, 2=Section, 3=Narrowscope), provides concrete examples (e.g., '07' for division, '072000' for section), and explains how parameters combine to filter results.

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 'Browse CSI MasterFormat building product categories,' which clearly states a specific verb and resource. It goes on to detail the hierarchy browsing behavior, making it readily distinguishable from sibling tools that search manufacturers or products.

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 guidance on how to use the tool with no parameters, division only, division + level, and adding a section. It clearly implies when to use the tool (browsing hierarchical categories), but it does not explicitly mention alternatives or exclusions relative to 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, providing the safety profile. The description adds the list of returned data (company info, CSI sections, content types, product count), but does not disclose additional behaviors like error handling, authentication needs, or rate limits. 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 a single sentence that clearly states the action, resource, identifier, and return data. No unnecessary words or repeated information; it is front-loaded with the purpose.

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 simplicity (one parameter), the presence of an output schema, and good annotations, the description is complete. It explains what the tool does and what it returns, and the output schema handles return value details, so no critical information is missing.

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

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

The input schema provides 100% coverage for manufacturer_id, including a description ('ARCAT manufacturer ID (seq/coid)'). The tool description merely repeats 'ARCAT ID', adding no new semantic meaning beyond the schema. Baseline 3 is appropriate given 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 uses the specific verb 'Get detailed profile' with a clear resource ('specific building product manufacturer') and identifier ('ARCAT ID'). It also lists the key return contents, distinguishing it from sibling tools like search_manufacturers which are broader searches.

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 this is for retrieving a profile when the ARCAT ID is known, which differentiates it from search_manufacturers. However, it does not explicitly state when not to use it or mention alternatives, so it falls 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=true and idempotentHint=true, so the core safety profile is covered. The description adds a small behavioral detail about returning company details with ARCAT profile links, but does not disclose pagination limits, ordering, or how filters interact. With annotations present, this modest addition warrants a 3.

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: the first states the action and search criteria, the second states the return values. Every word contributes value, with no repetition or filler.

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

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

The description effectively covers the core functionality and return type. With an output schema present and good annotations, it does not need to explain return formats. Minor gaps include not mentioning pagination behavior (limit/offset defaults) or whether query and CSI parameters can be combined, but these are not critical for basic use.

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 five parameters have descriptions in the schema. The tool description only paraphrases the search dimensions (name, keyword, CSI section) that are already in the schema, adding no new meaning. Per the baseline rule for high schema coverage, this scores 3.

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

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

The description uses a specific verb ('Search') and identifies the resource ('building product manufacturers'), with explicit search dimensions: name, keyword, or CSI MasterFormat section. It also mentions the return type (company details with ARCAT profile links), effectively distinguishing from sibling tools like search_products and get_manufacturer.

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: when searching for manufacturers by name, keyword, or section. However, it does not explicitly state exclusions or alternatives (e.g., 'use get_manufacturer for a single manufacturer' or 'use search_products for products'), 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 this as a read-only, idempotent operation. The description adds valuable context by stating that results include links to specifications, CAD, BIM, and catalog downloads on arcat.com, which helps the agent set expectations about the response.

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

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

The description is two sentences long, front-loaded with the core purpose, and every phrase earns its place. No redundant information 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 tool's moderate complexity (7 parameters, output schema present), the description covers the essential search dimensions and return value. It does not explicitly explain pagination behavior, but the schema covers offset/limit, and the output schema handles return structure.

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

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

Schema description coverage is 100%, so the input schema fully documents all 7 parameters. The description adds minimal extra semantic value beyond the schema, mentioning keyword, CSI section, and content format, which maps directly to existing parameter descriptions.

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

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

The description uses a specific verb ('Search') and clearly identifies the resource ('building products') along with the search dimensions (keyword, CSI MasterFormat section, content format). It also states the return value (product details with download links), distinguishing it from sibling tools like search_manufacturers.

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 indicates when to use the tool: when searching for building products by keyword, CSI section, or format. However, it does not explicitly mention alternatives or exclusions, so it misses the top rating for comparative guidance.

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