Get Tweet Details

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

Annotations already declare read-only, idempotent, non-destructive, open-world, but the description adds cost and auth context they cannot express: an API key is required, one request is made per call, the cost is usually 1 unit, and each result carries a cost estimate. It also discloses the pagination contract (one page per call) and the responseFormat trade-off, neither of which is inferable from the safety annotations alone.

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?

Four sentences, front-loaded with what the tool returns before routing advice and operational constraints. Every sentence carries load: payload scope, alternatives, auth/cost, pagination contract. No restatement of the title or filler.

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 is a paginated, billed, authenticated read with an output schema; the description covers all four concerns and explicitly defers return-value detail to the output schema while still naming the key cursor field. An agent has everything needed to call it correctly, page it, and budget for it.

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 the baseline is 3, but the description adds cross-field meaning the schema only states locally: it ties the cursor input to the output field completeness.nextCursor, explaining the pagination loop end to end. sortBy and responseFormat semantics are left to the schema, which already documents them fully with enums and defaults.

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 ('Fetch one tweet with full details') and goes further by naming the payload shape: parent tweets for replies plus a page of replies. It explicitly distinguishes itself from tweetapi_tweet_metrics (counts only) and tweetapi_tweet_details_by_ids (many tweets), so an agent can differentiate it from siblings without reading schemas.

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?

It names two concrete alternatives with the exact condition that selects each: metrics for counts only, details_by_ids for many tweets. It also gives operational guidance for pagination ('call again with cursor set to this result's completeness.nextCursor') and for omitting the cursor on the first page, leaving nothing to inference.

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