Send a message

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

Annotations only indicate non-read-only non-destructive. The description adds that this is fire-and-forget ('expect nothing back'), that the send is subject to secret scanning that refuses the send, and implies messages may be compacted since komnet_decide is for when they must outlive compaction. Valuable context beyond 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; the core purpose is front-loaded, the sibling routing is in the middle, and the warning at the end. Some elaboration ('an update, a heads-up, a short note') gives useful concreteness though could be trimmed slightly. Dimensions generally efficient.

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 an 8-parameter messaging tool with no output schema, the description covers the key decision points: one-way nature, thread support, and the secret-scanning safety gate. It does not spell out return values or all optional fields, but those are mostly covered by the schema. Enough for correct selection and reasonable invocation.

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 75%, leaving the schema to document most parameters. The description adds a high-level 'send a note on a thread' concept, but does not detail any of the 8 parameters beyond the schema. It appropriately lets the schema carry the parameter burden, so a baseline 3 is suitable.

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?

Description clearly states a specific verb+resource: 'Say something into a room and expect nothing back' – a send operation. It also distinguishes itself from key siblings: komnet_ask when a reply is needed, komnet_answer when replying to an inbox item, komnet_decide when outcome must outlive compaction. No ambiguity.

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?

Provides explicit when-to-use and when-not-to-use conditions: use for updates/heads-up/notes on a thread, not when you need a reply (komnet_ask), not when replying to inbox (komnet_answer), not when the outcome is permanent (komnet_decide). The secret-scanner warning further clarifies the expected behavior.

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