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

Well beyond the annotations (which only say readOnly=false, destructive=false, openWorld=false): it discloses that the description auto-quotes authors and timestamps, that a permission-scoped backlink is always appended, that files are copied, that a «→ KEY» marker appears on the message, that filing obeys the target project's rights/rules/watchers, and that the response mirrors create_issue.

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?

Purpose is front-loaded and there is no filler, but the prose is dense and clipped, with constructions like 'Filed as create_issue files — your rights in that project, its rules, its watchers' that cost readability for the 14-parameter decision the agent has to make.

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?

Covers what would otherwise be unknowns for a 14-parameter mutation with no output schema: side effects (file copying, message marker, backlink), permission implications, filing rules, and the response shape ('Answers like create_issue, with files copied').

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 projectKey defaulting, description/summary defaults, copyFiles, and the 50-message thread cap are already documented in the schema. The description mostly restates those behaviors rather than adding new parameter meaning, so the baseline of 3 applies.

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 ('Make an issue of a message in one of the company's chats — or of a thread of them') plus the one-step scope, and names create_issue as the analogous flow so the agent can place it against the general issue-creation sibling.

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 a concrete routing rule for the main decision: 'A project's chat files into its project when projectKey is omitted; any other chat needs projectKey.' It does not explicitly compare against create_issue (e.g. 'use create_issue when not starting from a chat message'), so it's clear context without full exclusions.

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