get_tweet

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

Annotations already declare readOnly, idempotent, and openWorld, so safety is covered. The description adds real context beyond them: the backing endpoint is the public syndication API, long posts are auto-enriched when truncated, and conversation context is out of reach. It doesn't mention rate limits or failure modes (deleted/protected posts), which would round this out.

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 verb and action, then behavior, then limits — a sensible order with no filler. The enumerated return fields (author, timestamp, metrics, media, card, quoted post) partially duplicate the output schema, which costs a little space.

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?

Covers input forms, default enrichment behavior, and the thread/reply limitation, which is the main trap for this tool. Since an output schema exists, the return-value paragraph is surplus but harmless; adding guidance on when to prefer get_tweets would make it fully complete.

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 all five parameters are already documented, including enrich, include_raw, resolve_links, and include_quoted. The description's mentions of enrichment and resolved t.co links describe output rather than adding constraints or defaults beyond the schema, so it sits at the baseline.

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 verb and resource ("Fetch one X/Twitter post by ID or URL") and clarifies scope with "returns one post, not a thread," which separates it from get_tweets and search_tweets by cardinality. It stops short of naming any sibling explicitly, so differentiation is inferred rather than stated.

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 closing note — "The public syndication endpoint returns one post, not a thread. Replies and the rest of the conversation are not available" — is a genuine exclusion that tells an agent when this tool will fail. It never names the alternative tools (get_tweets, search_tweets) to use instead, leaving the routing step to inference.

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