token_identity

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context: the tool reports coverage per call, charges $0.025, and returns free empty results if no coverage. This goes beyond the schema and annotations, informing the agent about cost and data availability.

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 compact and front-loaded: it starts with the cost, then the core question, and lists key data points. Every sentence adds value—cost, scope, decision-point role, and coverage behavior. No fluff or redundancy.

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 tool has one parameter, full schema coverage, and an output schema, so the description doesn't need to explain return values. It covers the purpose, cost, and coverage behavior. However, it doesn't mention edge cases like how to interpret empty results beyond being free, or whether results are ordered by relevance, leaving minor gaps for an agent seeking complete decision support.

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?

Schema coverage is 100% with the 'mint' parameter described as 'Solana token mint, base58.' The description doesn't add to this but doesn't need to, since the schema is clear. It indirectly refers to the mint as the token being analyzed but provides no additional semantic details beyond the schema. Given high coverage, a baseline of 3 is appropriate, but the description's 'mint' usage in context adds slight value, earning a 4.

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 explains the tool's purpose: to reveal the identity behind a token by analyzing its largest holders' history and outcomes. It uses a specific metaphor ('Who is BEHIND this token') and cites concrete aspects (largest holders, sibling tokens, upside band). However, it doesn't explicitly differentiate from siblings like check_token or inspect_token, relying on the phrase 'decision-point call' to imply uniqueness.

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 when to use this tool: at the decision point, when you need identity context beyond basic checks. It mentions coverage reported per call and free empty results, which suggests using it iteratively. However, it doesn't explicitly state when not to use it or mention alternatives like check_wallet or find_serial_insiders, which may overlap.

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