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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world). The description adds real behavioral context beyond that: 'allowed_actions' tells the agent what mutations are currently permissible, 'permalink once live' signals field availability is state-dependent, engagement numbers are 'null where the platform gives none', and suggested_times appear only for overdue/near-due approvals.

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?

A single enormous run-on sentence with multiple nested parentheticals and semicolon-chained clauses, much of it enumerating return fields the output schema already defines. The key routing fact (use show_posts to render) is buried mid-paragraph rather than front-loaded.

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?

For a read-only single-resource getter with an output schema and full annotation coverage, the description is more than sufficient — it even over-delivers on return-field detail. The only real omission is how post_id is obtained and an explicit statement of when an agent should reach for this 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?

Only one parameter (post_id) with 0% schema description coverage, so the description carries the explanatory burden — but it never says what a post_id is or where to obtain one. The parameter's meaning is inferable only from the tool name and the 'with its post_id' aside. Adequate but with a clear gap.

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 by scoping the resource precisely ('One post: its targets..., its approval..., allowed_actions; and history') and explicitly disambiguates from show_posts ('It draws nothing; show_posts with its post_id draws it for the person'). An agent can distinguish this retrieval tool from its draw-oriented sibling 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?

It names the alternative explicitly and the condition that selects it: use show_posts when you want the post rendered for the person, use get_post when you only need the data. It stops short of stating the positive trigger ('call this to inspect a single post's state'), leaving the when-to-use for this tool implied.

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