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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), it discloses the resulting status transition (waiting_staff, resolved reopens), the side effect of auto-following, the 409 case_closed failure mode, and the two emitted events (ops.support.customer_replied, audit.tenant.support_message_added). This is exactly the non-obvious behavioral context annotations cannot carry.

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 first line restates the title verbatim, and the core rule is stated twice ('a resolved case goes back to waiting_staff' followed later by 'the case goes back to the team (waiting_staff; a resolved case reopens)'; the 409 case_closed warning also appears twice). Useful content, but the duplication means some sentences do not earn their place and the routing guidance is buried mid-paragraph rather than front-loaded.

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?

There is no output schema, and the description covers the outcome an agent needs: resulting status, follower side effect, emitted events, and the closed-case error with its remediation. Nothing required to invoke the tool correctly or interpret the outcome 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?

Schema coverage is 50% (only case_id is documented), so the description must carry the body parameter — it adds that body is plain text, capped at 10,000 characters, and that files cannot be sent (attachments happen in the web app). The character limit duplicates the schema's maxLength, but the text-only constraint is genuine added meaning for body.

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?

States a specific verb and resource ('Reply in a case of your company') and explicitly separates the domain from the nearest sibling family: support cases are for asking the BoardMark team for help, 'never for the user's own project work (that is issues: create_issue, search_issues …)'. An agent can route between reply_support_case and the issue tools without opening a 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?

Gives explicit when-to-use triggers (user wants help from the BoardMark team, reports a bug, sign-in problem, billing, feature request), an explicit when-NOT-to (never for the user's own project work), and names the alternative family plus the dependent tool reopen_support_case for the closed-case path. Nothing is left to inference.

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