Create, claim, and drive collaborative tasks

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

Annotations only provide readOnlyHint=false and destructiveHint=false, carrying minimal safety info. The description adds substantial behavioral depth: it explains the append-only nature, 'one guarded transition' for updates, the race condition in claims (visible via list), and the requirement that updates carry evidence and a next step. This goes well beyond the annotations and helps an agent predict side effects.

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 two sentences, front-loaded with the core concept ('append-only thread') and then systematically explains each action in a compact list. Every clause adds essential information, with no redundancy or filler. It is dense yet 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 tool with 13 parameters, 5 actions, and no output schema, the description covers the main workflow and key constraints. It explains the purpose of each action and the evidence/next-step requirement, while the schema handles individual parameter details. It does not cover edge cases like error handling or return structure, but those are not critical for correct invocation given the rich schema.

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 92%, so parameters are well documented. The description adds semantic context beyond the schema, such as clarifying that claim carries responsibility and must precede work (elucidating the 'note' param) and that update appends a guarded transition (contextualizing 'transition'). This enriches understanding without repeating schema details.

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 title and description clearly state the tool manages collaborative tasks via five specific actions (create, claim, update, show, list). The description explicitly frames it as an 'append-only thread' and describes each action's role, forming a clear, distinct purpose compared to sibling tools like komnet_claim (which appears to be a separate narrow tool) and others.

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 gives usage guidance for each action: 'claim takes responsibility and must precede any work', 'show... read it before continuing work you did not start', and 'list gives the room's derived state'. It also explains that updates need evidence and a next step. While it doesn't explicitly contrast with sibling tools, the internal action usage is clear and actionable.

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