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

Goes well beyond the annotations: it discloses human gating with a before -> after diff, the no-elicitation pass-through case and why it is safe (never reaches Stripe, no amounts/limits/billing model changes), reversibility, and the non-obvious write behavior that setting a flag false deletes the key rather than storing false. It also mentions the exported plans.json side effect that must be regenerated.

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 core action and structured with the write-safety details following. It is on the long side, and the parenthetical about the "gold/carbon BEST VALUE card with the rainbow title and app icon" is more color than an agent needs, but nearly every other sentence carries actionable information.

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?

Mutation tool with no output schema and an undefined dry_run parameter, but the description compensates with approval flow, side effects, reversibility and the sync follow-up. The omission of dry_run semantics is the one thing an agent might need before calling it correctly.

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 0%, so the description carries the burden. It meaningfully covers name, tier (as a slug sourced from list_plans), is_elite and recommended, including their values and side effects. But app_id is only implied and dry_run is never mentioned at all, leaving a meaningful gap for a 6-parameter mutation tool.

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 plus the exact fields touched: display name and the two badge flags. It clearly separates itself from the pricing/limits siblings by framing this as display metadata used by the public pricing page, and even explains that the page reads the flag rather than the slug.

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?

Gives explicit when-to-use ("Use this to repair that" when a top tier lacks is_elite), explicit prerequisites ("Use list_plans first for tier slugs and current flags"), and an explicit follow-up (run `bun run plans:sync`). It also warns that the tool does not clear flags from siblings, so a second call is required to move a badge.

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