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

Beyond the annotations (write, non-destructive, non-idempotent), the description adds the key behavioral fact that recording "does not change any answer right away" and instructs the agent to confirm to the user afterwards. It does not discuss duplicate reports or what happens to a report later, but the core write semantics are disclosed.

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 purpose is front-loaded and every sentence carries a distinct instruction: trigger, exclusion, parameter handling, and post-call follow-up. There is no redundant restatement of the title or schema.

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 small write tool with no output schema, the description covers trigger, params, and what to tell the user after the call. Remaining gaps are minor, mainly how to pick kind when the report is praise or a feature request.

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?

With 75% schema coverage the baseline is 3, and the description earns more by giving conditional usage for three params: message gets the user's own words, card_id only when it is a specific card, expected only when the user states the right answer. The kind enum's extra values (feature_request, praise, other) are not addressed, which sits slightly at odds with the "only when wrong/missing" framing.

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?

"Record the user's report that POKEKA data is wrong or missing" gives a specific verb (record) and resource (user report), then enumerates the concrete cases: wrong price, wrong card match, unfindable card, missing data. This clearly separates it from the read-only siblings such as card_price or search_card.

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 both the trigger ("Call it when the user says a POKEKA answer is wrong or something is missing") and the exclusion ("Do not call it for ordinary questions"). It stops short of naming which sibling answers the ordinary-question case, so the agent must infer the alternative.

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