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

Goes well beyond the annotations: initial status `new`, opener auto-follows, attachments web-only (agents send none), consent-gated `context`, a concrete 20-cases/user/day limit with 429 `rate_limited` and the retry_after/Retry-After details, published events (`ops.support.case_opened`, `audit.tenant.support_case_opened`), team notification, and the 'via AI agent' write label.

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?

Front-loaded and information-dense, but it repeats itself: the 20-cases/day + 429 rate limit appears twice, and the 'only when the user asks for help from the BoardMark team' trigger is restated in the final paragraph. The prose is also packed with backtick-heavy clauses that are hard to scan.

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?

With no output schema, the description still tells the agent what comes back ('Returns the case — tell the user its `number`'), how replies arrive (case thread via get_support_case, email to followers), and every constraint needed to call it correctly.

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?

Adds meaning beyond the 75%-covered schema: severity choice guidance ('do not overstate it'), a content checklist for `body` (what happened, steps, expected vs actual, project/issue keys, when, error text), the subject/body length constraints restated as authoring rules, and a safety rule against passwords/tokens/secrets.

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+resource (open a support case for the company) and immediately scopes who it is for (any member, people and AI agents). It also distinguishes itself from the issue-creation siblings by stating support cases are 'never for the user's own project work (that is issues: create_issue, search_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?

Gives an explicit trigger with an exclusion: only when the user asks for help from the BoardMark team or agrees to report a problem, and explicitly not for project work. It also prescribes a prerequisite workflow — check list_support_cases first and reply in an existing case about the same thing instead.

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