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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description goes beyond them by disclosing the access model: 1.00 USDC per call via x402 PAYMENT-SIGNATURE or free with an API key, including that x402-capable clients auto-pay. That is genuinely decision-relevant context, though the stated 'at most 10 posts' cap sits uneasily with the schema's limit default of 20 and is never reconciled.

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: purpose and routing come first, access/payment details are bracketed off as secondary, which matches how an agent reads. The payment sentence is slightly verbose but every clause carries operational meaning.

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?

There is no output schema, and the description compensates by telling the caller exactly what comes back (post text, id, timestamp, plus match count). Access cost and auth modes are covered. The only real gap is the unexplained conflict between the 10-post claim and the limit parameter's default of 20.

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 description coverage is 100%, so the baseline is 3. The description contributes only the result cap and the match count; it says nothing about hours_back or about what happens when limit exceeds the apparent 10-post ceiling, and that tension actively muddies rather than clarifies the limit 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?

Names a specific verb+resource (recent X/Twitter posts about a crypto asset or topic) and enumerates the returned fields (post text, id, time, matched count). It also draws a sharp line against the aggregated-sentiment sibling, so an agent can distinguish the two tools without opening either schema.

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?

Explicitly states the selecting condition — the user wants to see what is actually being said, or wants raw posts instead of an aggregated sentiment score — which functions as both a when-to-use and a when-not-to-use rule against get_social_sentiment. No additional inference is required to route between them.

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