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

Goes well past the readOnly/idempotent annotations by disclosing cost mechanics (25 free calls/day, then $0.02 USDC via x402), the simulation behavior (a real holder sell to test liquidity pull), and the exact verdict/rug_chance output shape. For a paid, open-world external call, these are precisely the traits an agent needs before invoking.

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?

Front-loaded with the trigger and the output vocabulary, then evidence, then an example, then cost — a sensible priority order with little redundancy. The trailing "Outputs explained: GET /api/tools/token_safety" is cryptic (a URL fragment rather than a sentence) and the middle clause listing checks is dense, but nothing 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?

With no output schema, the description still names the verdict enum, the rug_chance semantics (high with reasons, or null), and the cost model, which is enough to decide and call. The full output payload is deferred to an external docs path, leaving the agent to infer field-level detail.

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%, so both parameters are already documented, including the mainnet-beta vs devnet distinction. The description adds a worked example showing the token address format, but says nothing about the network parameter or what an invalid/unknown token returns — marginal lift over the schema.

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?

States a specific action (safety-check a token) and a concrete, enumerated return (SAFE / CAUTION / AVOID plus rug_chance), and lists the exact signals checked (liquidity pull, creator record, insider wallets, mint/freeze powers, Token-2022 traps). This is unmistakably distinct from siblings like find_token or tokens, which only resolve addresses.

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?

"Run before buying, accepting or recommending a token" gives a clear triggering condition, and the parameter description routes the agent to find_token/tokens first to obtain the address. It stops short of naming a when-not case or an alternative verdict tool, but the usage context is unambiguous.

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