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

The annotation only supplies readOnlyHint=false, so the description carries most of the burden and does add useful context: it is a live-claim-gated write, human verification is mandatory in manual mode, and a Defamation filing silently fails without the accusation_untrue attestation. It omits whether the call is idempotent, what happens on a rejected subreason, and what the response contains.

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 core instruction is front-loaded, but the middle is three long run-on sentences stacking subreason and attestation rules, which makes it slow to parse. The trailing "(capability: cases.mark_filed_own)" is internal metadata that does not help the agent decide or invoke.

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 complexity of the subreason branch and the Defamation attestation rule, the description covers the hard cases well, but there is no output schema and it never describes what a successful or failed call returns. It also references "manual mode" without indicating how the agent determines which mode applies.

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 0%, so the description must explain the parameters and it largely does: verified_by is "who verified the packet", draft_id is "the exact draft_id", confirmed is "every checklist item marked confirm", and subreason/attested_by each get scenario-specific semantics. case_id is never explained and "in manual mode" refers to a mode that has no corresponding parameter, leaving a residual gap.

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 that you filed one of your cases in Trustpilot's portal" states a specific verb (record a filing) and resource (a case in Trustpilot's portal), which is distinct from approve_filing and record_decision. It does not explicitly differentiate itself from those siblings, leaving the agent to infer the boundary between recording a filing and approving a packet.

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 concrete preconditions: a live claim packet is needed, and in manual mode a human check with verified_by, draft_id, and confirmed items. It also gives a hard stop condition ("without it nothing is recorded, so get it before you submit the report"). It never says when to call this instead of approve_filing or record_decision, so the alternative-routing guidance is absent.

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