compare_fees

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar for credit is behavioral context beyond them. The description adds meaningful, non-obvious behavior: results are 'ranked by lowest fee after CoinRebate rebate discount'—an agent would otherwise assume raw exchange fees—and passing a country code switches filtering behavior. This genuinely shapes expectations about the returned data.

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

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

Three tight sentences with zero fluff: the core purpose, the ranking behavior, then the optional country filter. Each sentence earns its place and no word is wasted.

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 two-parameter, single-required-param read-only tool with strong annotations and no output schema, the essential decision-making context is all here: comparison scope, ranking criterion, rebate-adjusted fees, and compliance filtering. Minor gaps—such as whether the result is a fully ranked list or top-N, and what the filtered list contains—are low severity for an agent deciding to call this 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 input schema already describes both parameters fully (purpose enum, ISO country code, and 'for compliance filtering'), so the schema does the heavy lifting and the baseline is 3. The description restates the purpose constraint and the compliance use of country, adding only slight interpretive value by tying the fee computation to the rebate discount context.

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

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

The description opens with a specific verb and resource: 'Compare trading fees across all exchanges for a specific purpose (spot or futures trading).' The scope qualifier 'across all exchanges,' the ranking claim, and the compliance-filter note distinguish it from siblings like get_exchange_fees and get_compliant_exchanges without needing to open the schema.

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

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

The description implies the use case—fee comparison across exchanges for spot or futures—and tells the agent when to pass the country code for compliance-filtered results. However, it never names an alternative or states when not to use it, so the agent must infer the boundary against siblings like get_exchange_fees and get_compliant_exchanges on its own.

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