Katzilla MCP

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it specifies the data source ('U.S. Department of the Treasury'), update frequency ('updates daily'), return format ('Katzilla envelope'), and quality metrics ('freshness/uptime/confidence'). This provides practical implementation details the annotations don't cover.

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 that each serve distinct purposes: the first covers purpose and scope, the second covers source, update frequency, and return format. There is no wasted verbiage, and critical information is front-loaded appropriately.

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, comprehensive annotations, complete schema coverage, and existence of an output schema, the description provides excellent contextual completeness. It covers purpose, data source, temporal scope, update frequency, and return format - everything needed to understand the tool's behavior without duplicating structured field 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?

With 100% schema description coverage, the input schema already fully documents all four parameters. The description mentions 'date range filtering' which aligns with startDate/endDate parameters, but adds no additional semantic meaning beyond what's in the schema descriptions. This meets the baseline expectation when schema coverage is complete.

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 ('Fetch US national debt data'), resource ('from the Treasury Fiscal Data API'), and scope ('total public debt outstanding and debt held by the public'). It distinguishes itself from sibling tools like 'economic__treasury-fiscal-data' by focusing specifically on debt data rather than broader fiscal data.

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 usage ('Supports date range filtering for historical data back to 1993'), but does not explicitly state when to use this tool versus alternatives like 'economic__treasury-fiscal-data' or other economic data tools. The historical data range guidance is helpful but not comprehensive about tool selection.

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