What to fix next, post by post

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces with 'Read-only, 0 credits.' It adds valuable behavioral context not in annotations: that it may return 'nothing here needs fixing' as a real answer, that it cannot see organic post conversions, and that the baseline is built from ALL recorded posts. These details meaningfully improve call quality.

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?

Though long, the description is front-loaded with purpose, uses clear section markers (headers, numbered refusals), and every sentence carries unique information. The structure makes it easy to skim for key rules. The length is justified by the complexity of the diagnostic logic. No redundancy.

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?

Given the tool's complexity, the description is thorough: it covers purpose, usage conditions, the four refusal cases, the converting behavior, output instruction ('Print summary verbatim'), and its read-only nature. There is no output schema, so the description compensates by specifying the call to action. An agent has everything needed to decide when to call and what to expect.

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 covers each parameter with descriptions, so baseline is 3. The description adds extra meaning: for limit, it states the baseline always uses every post, not just the limited set, preventing a bad month from becoming its own normal; for converting, it clarifies the condition under which converting:false should be passed and that it should be omitted when unknown. This adds value beyond the schema.

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 clearly states the tool's purpose: 'tells you what is WRONG with a given post and where the next edit goes.' It distinguishes itself from sibling post_performance by contrasting 'which hook is AHEAD' vs 'what is WRONG'. This is a specific verb+resource with clear differentiation from similarly named tools.

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 explicitly explains when to use this tool versus alternatives. It references post_performance for hook comparison, prescribes the sequence 'mine_angles, then list_hooks, then plan_variations' for hook problems, and details the four refusal conditions that tell the agent when NOT to call the tool. It also specifies when the offer rung runs (only with converting:false). This is exemplary.

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