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

With no annotations, the description discloses the paid data source, possible unavailability, and instructs the agent to state errors plainly and point to alternatives. It also describes what data is returned (floor path, high/low, net change, etc.) and the effect of compare_to. This goes beyond a simple read/write hint, though rate limits and output format aren't mentioned.

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 dense but not wasteful. Each sentence adds relevant information: core function, single vs comparison behavior, expected inputs, and a caveat about data availability. It is slightly long but well structured with clear examples.

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 (optional comparison, multiple return metrics) and the absence of an output schema, the description is remarkably complete. It covers inputs, outputs, failure modes, and provides example queries. It doesn't specify exact output formatting, but that would be redundant without a 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 already covers all parameters (100% coverage), and the description adds value by explaining the semantic role of compare_to (time above the other floor) and emphasizing that collection names should be given. It also contextualizes 'days' as the window, which reinforces the schema description.

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 retrieves historical NFT floor prices from CoinGecko, for one or two collections, and distinguishes itself from siblings like 'nft_floor_price' by emphasizing 'Historical' and 'COMPARISON'. It uses specific verbs and describes what answers it provides.

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 gives concrete example questions the tool answers, clarifying when to use it (e.g., 'what was X's floor N hours/days ago', 'how much time has X floored above Y'). It also instructs to provide collection NAMES. However, it does not explicitly mention alternative tools for current floor or when not to use it.

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