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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: data source fallback (Coinbase CDP API vs Base RPC scan), use of internal JSONL telemetry for gapup-mcp.io, SHA-256 wallet anonymization, 30-minute LRU cache, 8-second timeout per source, and optional COINBASE_X402_API_KEY. This goes far beyond the annotations and helps the agent anticipate performance, data freshness, and privacy handling.

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 long but information-dense, using a numbered mode list and semicolon-separated details. It front-loads the core purpose, then flows into modes and technical specifics (network, contract, cache, timeout). While it could be more succinct, every sentence earns its place for this complex multi-mode tool, and the structure aids scanability.

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 covers network (Base mainnet), USDC contract address, caching, timeout, data source details for each mode, and high-level outputs (e.g., median, P25, P75 for price_radar). Given the presence of an output schema, it is not necessary to document return structures exhaustively. This is a complete and self-sufficient description for a multi-mode analytics 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?

Though the input schema already provides 100% parameter descriptions, the description adds meaningful context: it explains what each analytical mode returns, how data sources vary by mode, and the fallback behavior tied to the API key. For example, facilitator_stats description clarifies that network-wide settlement stats may originate from Coinbase CDP API or an RPC scan. This adds value beyond the schema's per-parameter summaries.

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: 'Real-time analytics on x402 protocol USDC micropayments for MCP endpoints on Base network.' It then enumerates four distinct modes (facilitator_stats, endpoint_intel, agent_caller_profile, price_radar), each with clear output focus. This clearly distinguishes it from siblings like x402_liquidity_monitor or x402_payment_flow_analyzer by positioning it as an intel/analytics tool with unique data aggregation.

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 provides clear context on when to use each mode (e.g., endpoint_intel for per-URL analytics, agent_caller_profile for per-wallet analytics) and highlights unique capabilities like internal telemetry access. However, it does not explicitly mention alternatives or exclusion conditions relative to sibling tools (e.g., 'for fraud detection, use x402_payment_fraud_detector'), so it stops short of full usage differentiation.

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