Katzilla MCP

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, indicating a safe, repeatable, and open-ended search operation. The description adds valuable context beyond annotations: it specifies the return format ('Katzilla envelope { data, quality, citation }'), explains quality metrics ('freshness/uptime/confidence'), and details citation components ('source URL, license, SHA-256 data hash'), which are not covered by annotations. No contradiction with annotations is 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 efficiently structured in two sentences: the first states the purpose and source, and the second details the return format and its components. Every sentence adds essential information without redundancy, making it front-loaded and easy 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 complexity (a search tool with annotations and an output schema), the description is complete. It covers purpose, source, update frequency, and detailed return format, compensating for any gaps. With annotations providing safety hints and an output schema likely defining the envelope structure, the description adds sufficient context for effective use without needing to explain return values explicitly.

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

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

The input schema has 100% description coverage, with the single parameter 'query' documented as 'Search keyword for HTS tariff items'. The description adds minimal parameter semantics beyond the schema, only implying keyword-based search in the opening sentence. Since schema coverage is high, the baseline score of 3 is appropriate, as the description does not significantly enhance parameter understanding but doesn't detract either.

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 ('Search'), resource ('U.S. International Trade Commission Harmonized Tariff Schedule (HTS)'), and scope ('tariff codes, descriptions, and duty rates by keyword'). It distinguishes itself from siblings by focusing on trade tariff data, unlike other tools in the list (e.g., agriculture, consumer, economic datasets).

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 ('Search... for tariff codes, descriptions, and duty rates by keyword') and mentions the source and update frequency ('Source: USITC (Public Domain), updates monthly'), which helps set expectations. However, it does not explicitly state when not to use it or name specific alternatives among siblings, though the trade focus implies differentiation from non-trade tools.

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