add_issue_labels

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

Annotations state idempotentHint=true but no readOnly/destructive hints beyond that; readOnlyHint=false and destructiveHint=false are present. The description notes the non-replacing behavior and that label names go through stdin (a notable I/O detail), but doesn't add context about idempotency or what happens with non-existent labels. 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?

Two sentences with zero filler. It front-loads the core purpose and notable behaviors. Could arguably mention that labels must already exist, but it's already concise enough that adding more would be acceptable.

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 moderate-complexity tool with no output schema and one undocumented param (hostname), the description is reasonably complete. It states the add-only behavior and stdin mechanism. It doesn't specify behavior when a label doesn't exist or is already applied, and doesn't describe return value. However, given the tool's relative simplicity and idempotent annotation, this is a mild gap rather than a critical one.

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 low (40%), covering only repository and issueNumber in descriptions. The description adds meaningful semantic info about the labels parameter ('existing labels... without replacing'), which clarifies behavior beyond the bare schema definition. The stdin mention also adds parameter-related context, though the hostname param has no description anywhere.

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 the verb+resource ('Add existing labels to an issue or pull request') and explicitly notes the key behavior of not replacing current labels. It distinguishes meaningfully from the sibling tools list_labels, list_issue_labels, and remove_issue_label by indicating additive behavior.

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 implies when to use it ('add existing labels... without replacing'), which differentiates it from tools like create_label (creating new labels) and remove_issue_label. However, it doesn't explicitly state when not to use it or mention alternatives like update_issue which might also handle labels, so no explicit exclusions are given.

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