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

Annotations only declare this is a non-idempotent, non-destructive write; the description goes well beyond that by stating reports are unverified observations, cannot change saved ratings or taste, are subject to host approval controls and viewer opt-out, and return a receipt acknowledgement. It also sets a firm one-report-per-signal rate limit, which the annotations do not convey.

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 paragraph is front-loaded with purpose and then layers constraints in roughly priority order, with no filler sentences. It is dense and somewhat run-on — several rules (evidence types, confidence limits, excluded content) are packed into single clauses, making it easy to skim past one.

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 nested-object write tool with an output schema, it covers the essential burdens: privacy exclusions (no transcripts, identity, credentials, sensitive details), evidence integrity, and the fact that reports have no effect on recommendations. The only real hole is that 'when permitted by viewer and host' leaves the agent without a way to verify the precondition before calling.

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 reported as 0%, so the description must carry the load, and it does for most fields: reference_request_id must be copied and never invented and grants no access, title_ids are copied from results with a five-item cap, and summary is a ≤300-character paraphrase. It falls short on the seven enum values for 'category' and 'reaction,' which are never mapped to concrete situations, leaving the agent to guess at 'constraint_missed' versus 'tool_problem'.

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 — 'Record a brief quality report' — and narrows the scope to 'a meaningful acceptance, rejection, correction or concrete problem with ReelRecs results.' No sibling tool in the list does anything similar (all others are retrieval/recommendation), so an agent can identify this as the sole feedback-capture tool without opening the schema.

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 gives real when-to-use signals: only 'when permitted by the viewer and host,' 'at most one report per new signal across ReelRecs tools,' and explicitly 'silence or continued use is not evidence of a reaction.' The main gap is that the permission gate ('when permitted by the viewer and host') is named but not operationalized — the agent isn't told how to determine permission.

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