addCollaborator

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

With no annotations provided, the description carries the burden of disclosure. It does reveal a key non-obvious behavior: the operation 'republishes full announcement' rather than simply updating a tag. However, it does not describe other important implications, such as whether the maintainer list is additive or replaced, potential side effects, or required authentication beyond what the schema mentions.

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 description is one concise sentence with a parenthetical that packs important mechanism details. It is front-loaded with the primary action and avoids unnecessary words, though the parenthetical makes it slightly dense.

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?

This is a mutation tool with no annotations, no output schema, and limited description. It explains the republishing mechanism but not the full effect on the announcement, whether it is destructive, what the expected outcome is, or any prerequisites. The reference to 'matches gittr UI' may be unhelpful to users unfamiliar with that UI, leaving the description incomplete for a tool with this complexity.

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?

The schema description coverage is 60% (three of five parameters have descriptions), and the tool description does not clarify the remaining parameters (relays, repoId) or add meaning to the existing ones. While 'maintainer' hints at collaboratorPubkey, the description fails to compensate for the uncovered parameters, so it adds little semantic value beyond the schema.

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 action ('Add maintainer') and the specific resource ('kind 30617'), and it distinguishes the tool from sibling tools by detailing the underlying mechanism ('republishes full announcement with updated maintainers tag'). The reference to 'matches gittr UI' adds further specificity, making the purpose unambiguous.

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 usage when one wants to add a maintainer, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The mention of matching the gittr UI provides some context but no direct guidance on alternatives or when not to use it.

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