structure_addIssues

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds the important default behavior: 'Skips issues already under that parent unless skipIfPresent=false.' It also discloses the API transport (POST action=add), giving the agent context about the nature of the call. No contradiction with annotations.

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?

Three sentences with no filler. Each sentence adds distinct value: the core action, the API endpoint/action, parent identification, issue identification, and the skip behavior. Front-loaded with the purpose and highly scannable.

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 mutation tool with 9 parameters and no output schema, the description covers the key decision points: parent selection, issue selection, and idempotency behavior. It does not mention return values or error handling, but the schema details individual parameters and annotations provide safety context. Some gaps remain (e.g., ordering via afterRowId/beforeRowId), but the description is complete enough for correct invocation in most cases.

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 baseline is 3. The description adds combinatory semantics not explicitly in the schema: parent can be identified by underRowId, folderName, or folderId, and issues can be passed via issueKeys and/or issueIds. It also reveals the default of skipIfPresent=true. This goes beyond individual field 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 'Add one or more Jira issues under a Structure folder (or any parent row)', a specific verb+resource statement that clearly distinguishes this write tool from the sibling list/get/read tools. It also names the API endpoint and action, leaving no ambiguity about the tool's function.

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 provides practical usage guidance: 'Identify parent via underRowId, folderName, or folderId. Pass issueKeys and/or issueIds.' It does not explicitly mention alternatives, but no sibling tool performs additions, so the intent is clear. It could improve by stating when to prefer underRowId over folderName/folderId, but the schema already notes 'Prefer this when known.'

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