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

Annotations only say non-read-only, non-destructive, closed-world; the description goes far beyond with the access model (token holder, 'readers', the project lead who reads every secret, nobody else), the two write modes and their consequences, that the stored value is never returned, that it is attributed to the current token, and the failure path for unknown readers in 'dropped'. This is exactly the context an agent needs before calling a credential-writing tool.

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 most important fact (what the tool is for and why not to use a comment) is front-loaded in sentence one, and the security instruction about not echoing the value is repeated at the end where it matters. It is long, and a couple of clauses are more exhortative than informative ('a value that passes through you stays in your context and in your client's logs'), but almost every sentence carries decision-relevant content.

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 exactly what would be missing: the shape of the response in both modes ('form' link versus id and name, never the value), the 'readableBy' field and how to report it to the user, and 'dropped' with its reason. Permissions and partial-failure behaviour are also stated, so nothing needed to call or interpret this tool is absent.

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 real meaning on top: it says to pass issueKey or pageId (the schema marks neither as required, so this clarifies the actual requirement), what happens when 'value' is omitted versus supplied, and that 'readers' entries may be silently dropped with a reason. That is genuine interaction semantics beyond the per-field schema text.

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?

Opens with a concrete verb+resource: attach a secret (password, key, test login) to an issue or a wiki page. It explicitly distinguishes itself from the obvious alternative behaviour (writing the value in a comment or description), so the agent understands it is a dedicated secret store rather than a generic write.

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 routing rule away from siblings ('instead of writing it in a comment or a description'), plus a strong preference rule for the omitted-'value' form flow 'whenever the value is not already in the conversation', and a prerequisite ('Needs the right to edit the issue or the page'). Both when-to-use and when-to-prefer-the-alternative-path are stated.

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