Read how the recorded posts performed

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description goes far beyond them: it explains accrual and skipping, how missing metrics are recorded as ABSENT (never zero), how failures become 'could not tell', the default skipping of X due to billing, and the requirement to inform the user about credits. This rich disclosure about side effects, cost, and data handling is exactly what an agent needs and exceeds annotation coverage.

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?

The description is longer than average but every sentence carries necessary information: accrual schedule, skip behavior, ABSENT vs zero, failure handling, billing for X, and the reporting of skips. It is structured with punctuation and a clear flow. It could be slightly tighter, but the density is justified for a tool with multiple behavioral nuances. Front-loads the core action.

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 tool with no output schema and moderate complexity, the description is remarkably complete. It tells the agent what it does, when to call it (due readings), how it handles data quirks (ABSENT, 'could not tell'), billing implications (X costs credits), and the need to inform the user. It also notes that skips are always reported, preventing misinterpretation. Nothing critical for selecting or invoking the tool 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 description coverage is 100%, so both 'max' and 'includeMetered' already have clear descriptions in the schema. The tool description reinforces the billing aspect of includeMetered ('tell the user it costs credits BEFORE you do') but does not add fundamentally new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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 clear, specific verb+resource: 'Fetch fresh performance numbers for this brand's recorded posts and store them as a time-series.' It precisely defines scope ('this brand's recorded posts') and the accrual model (24h and 7d readings), making it distinct from per-platform metrics tools like x_post_metrics or bluesky_post_metrics. Even without naming siblings, the behavior clearly separates it.

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 description implies when to use it—when metrics are due per the accrual schedule—but does not explicitly contrast it with alternatives or state when not to use it. It says 'this collects whichever readings are due and skips the ones already taken,' which gives a condition, but no explicit route to sibling tools or exclusions. This is adequate but not explicit.

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