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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses result ordering, partial-failure semantics ('listed in meta.notFound instead of failing the request'), that missing ids are not billed, and the exact billing formula. These are precisely the operational facts an agent needs before deciding to call it at volume.

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 short sentences, front-loaded with purpose, then usage, then failure behavior, then cost. 'Billed per post returned' and 'Costs 1 credit + 1 credit per post returned' overlap slightly, but the second adds the base-credit detail, so the redundancy is minor.

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, yet the description covers return ordering, the meta.notFound shape, and the cost model — covering the gaps an output schema would normally fill. For a single-parameter batch read tool, nothing an agent needs to call it correctly is missing.

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 already 100% (comma-separated numeric ids, 1-100, no spaces, duplicates ignored), so the schema carries most of the burden. The description still adds real meaning: returned posts follow the requested order, and unresolvable ids surface per-id in meta.notFound rather than as an error, which shapes how the agent interprets the single 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?

The first sentence gives a specific verb ('get'), resource ('public X posts'), and hard scope ('up to 100 ... by id'). The follow-up 'Looks up many posts in one request' implicitly separates it from the single-post sibling get_x_post and makes the batch nature unambiguous.

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 states a clear use case — 'for hydrating ids you already hold (from a webhook, a dataset, or another response)' — which tells the agent this is a batch-hydration tool, not a discovery tool. It stops short of naming an alternative such as get_x_post for single lookups or search_x for discovery, so there are no explicit exclusions.

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