geckoterminal_token_pools

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explain what 'top' means (e.g., sorted by volume or transactions), how pagination works, or that it returns a list of pools. The description only states the basic purpose without revealing sorting, pagination, or other behavioral traits.

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, front-loaded sentence that states the action, resource, and context. No filler or redundant information exists, making it appropriately concise for a tool that relies on the schema for parameter details.

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 provides the core purpose but leaves gaps: no usage guidelines, no mention of sorting/pagination options, and no return format details. Since there is no output schema, the description should compensate by explaining what output to expect, but it does not. The context is partially complete for a tool with moderate complexity.

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 covers all four parameters with descriptions, giving 100% schema coverage. The description adds no new parameter semantics beyond mapping 'specific token' to tokenAddress and hinting at the sort concept through 'top pools,' but this is marginal and not needed given the schema already documents each parameter.

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 a specific verb ('Get') and resource ('top pools for a specific token'), making the tool's function unambiguous. It distinguishes itself from sibling tools like geckoterminal_trending_pools by emphasizing the token-specific scope, while 'find liquidity and trading venues' adds context about what the result represents.

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 phrase 'for a specific token' implies the tool is used when a user has a token address and wants its top pools, but it does not explicitly state when to use this tool over alternatives (e.g., dex_get_token_pools or geckoterminal_get_token). No exclusions or alternative tool recommendations are provided, leaving usage context implied rather than explicit.

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