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

Beyond the annotations, the description discloses that the report may lead to normal support follow-up, that Fiveable resolves the content and reporter identity, and that requestId should be reused on retries. These are meaningful behavioral traits that the annotations alone do not express, and there is no contradiction with readOnlyHint=false or idempotentHint=true.

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?

Every sentence earns its place: the trigger condition, the follow-up effect, the content boundaries, the identity-handling note, and the retry instruction. The description is compact, front-loaded, and contains no fluff or repetition of schema details.

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 5-parameter reporting tool with an output schema and supporting annotations, the description covers the essential behavioral context: when to call it, what to exclude, what will happen after submission, and how to handle retries. Nothing critical for correct invocation 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?

The input schema already describes contentId, description, and confirmReport, and the description adds helpful semantics for requestId by framing it as an idempotency key to reuse on retries. It also reinforces that description must contain only the reported issue and not transcript or personal data, although contentType semantics are left entirely to its enum.

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 specific verb and resource: 'Submit a content issue to Fiveable support.' It makes the tool's sole purpose unmistakable and distinguishes it from the surrounding get/list/score siblings, none of which perform this reporting action.

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 states an explicit trigger condition: 'only when the student explicitly asks to report it.' It also gives clear exclusions ('Do not automatically report disagreements or send conversation history, unrelated notes, or personal information'), telling the agent when not to use the tool and what content must not be included.

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