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

Annotations already carry readOnlyHint=false and destructiveHint=true, so the safety profile is covered; the description adds genuinely new behavioral context beyond those hints: the blocker category 'raises one card in the Command Center (one per title)', the destination (operator's observability feed), and the approval-tier workflow (from-now-on vs just-once). No contradiction with annotations; the only gap is that the write-tier paragraph is slightly cryptic about what 'the card is the yes' means.

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 description is longer than average (three paragraphs) but front-loaded with core purpose and use triggers before routing and approval mechanics. Each section earns its place — routing and write-tier approval semantics appear nowhere else — though the bracketed write-tier paragraph is dense and jargon-heavy.

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 7-parameter write tool with no output schema, the description covers purpose, triggers, routing exclusions, side effects, and approval gates — everything needed to invoke it correctly. It doesn't describe the return value, but for a fire-and-forget feedback submission that is a minor gap given the schema and annotations already carry the parameter and safety burden.

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 100%, so the baseline is 3, but the description adds cross-parameter meaning by explaining the side effect of category='blocker' (Command Center card, one per title). It also frames which issues belong in company-scoped context versus product-request context, supplementing the schema's already-detailed per-parameter descriptions.

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 — 'Report an error, issue, observation, or suggestion you encountered during your work' — and the Routing paragraph explicitly contrasts it with submit_product_request, so an agent can distinguish it from its closest sibling without inspecting schemas. The purpose is concrete and scoped to observed agent-side issues.

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-use guidance ('Use this proactively when you notice something noteworthy — tool failures, recurring problems, quality issues, or improvement ideas') and explicit when-not-to-use routing (FreedomOS itself broken → submit_product_request; tenant product/KB gaps 'never go to the FO product inbox'). The write-tier note even instructs when to first call it ('Call it on the first clear ask').

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