Appeal the grade of my report

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

Annotations already indicate destructiveHint=true and idempotentHint=false, but the description adds meaningful behavioral context: the appeal cannot be withdrawn, the number of appeals per report is limited, the organization sees the grounds, and a different assessor handles it. These details go beyond the raw hints and help the agent set user expectations.

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 dense sentences carry purpose, process, constraints, prerequisites, and timing without waste. The key warnings are front-loaded with purpose first, and each sentence earns its place. No redundancy with annotations 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?

Given the tool's complexity and the fact that an output schema exists, the description covers everything needed to call it correctly: what is appealed, who performs the re-examination, what the organization sees, the user-approval requirement, the source of required IDs, the limitation on appeals, the irreversibility, and the deadline. This is complete for both selection and invocation.

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 the schema already documents all three parameters. The description adds some supportive context by explaining what a 'grade' means and pointing to get_report for both reportId and adjudicationId, but it does not materially enrich the parameter-level semantics 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 uses a specific verb ('Appeal') with a clear resource ('grade ... of one of the signed-in researcher's own reports') and scope ('assessed severity and reward'). It also explains the neutral third-party re-examination, which clearly separates it from sibling tools like grade_report. An agent can identify exactly what this tool does and what it does not do.

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 gives explicit when-to-call guidance: 'only call this when the user explicitly asked to appeal', plus the prerequisite that 'they are shown the exact grounds and must approve them'. It also states the time constraint (appeal window), the non-withdrawable nature, and where to get IDs ('get_report'). This gives clear operational context for invocation.

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