remove_issue_label

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

Annotations declare readOnlyHint=false and destructiveHint=false, which is expected for a label removal. The description adds valuable context that the operation is reversible ('reversible by adding the label again'), which is genuinely useful behavioral information beyond what annotations provide. It also implies mutation through 'remove' without overstating destructiveness.

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?

Two sentences, zero wasted words. The first sentence states the core operation and scope, the second adds a valuable nested detail about reversibility. Perfectly front-loaded and concise.

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 simple single-label removal with no output schema, the description covers the essentials: what it does and its reversibility. However, it doesn't detail exactly which params are required (though the schema marks 4 required), doesn't clarify whether removing a nonexistent label errors or fails gracefully, and lacks any mention of failure modes. Adequate but not comprehensive for a mutating tool.

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 description coverage is 40%, with only 2 of 5 parameters described (repository and issueNumber). The description adds no parameter-level detail beyond what the schema provides. The label parameter has constraints (maxLength 50) in schema but its exact format/values are not documented. Baseline 3 is appropriate given partial schema coverage with limited description compensation.

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 clearly states 'Remove one label from an issue or pull request,' using a specific verb+resource. It doesn't explicitly distinguish from sibling tools like add_issue_labels, but the verb 'remove' makes the purpose clear. The title also matches the intent well.

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 doesn't provide explicit when-to-use or when-not-to-use guidance. It states it works for both issues and pull requests, but doesn't mention alternatives (e.g., add_issue_labels) for adding labels. There's no context about when this tool is preferred over other label-related operations.

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