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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: presence is 'aged from each last-seen stamp into live / stale (meaning unknown) / away; never proof a session still exists', machines 'contested means two computers whose hostnames match, not one box; a null machine runs an older komnet and is reachable by agent id only', and 'Everything here is advisory and grants no authority.' These are behavioral caveats beyond the annotations. It doesn't fully describe all side effects of action='describe' (e.g., whether it broadcasts to others), but it covers the key caveats.

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 dense but efficient, packing a lot of information into a compact paragraph. It front-loads the default view and then enumerates the alternatives. Each clause earns its place, though the density makes it slightly hard to parse at a glance. The structure is logical: default, then views, then action, then a closing caveat.

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?

Given the tool's complexity (11 parameters, 5 views, 1 action, no output schema), the description covers the key semantics: what each view returns, the meaning of 'contested', the caveat about presence, and the behavior of action='describe'. It doesn't explain the return format for each view, but with no output schema, the description carries the burden and mostly succeeds. The main gap is that it doesn't describe the exact output shape for each view, but it gives enough for an agent to select and invoke the tool correctly.

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 55%, so the description must compensate for the undocumented parameters. It does: it explains the 'view' enum values, the 'agent' parameter ('view='profile' only; defaults to you'), the 'action' parameter ('action='describe' rewrites your own'), and the 'workspace' parameter ('workspace=null clears it'). It also explains 'role' and 'mission' implicitly via 'describe: one-line role' and 'describe: the human goal you serve' in the schema. The description adds meaning beyond the schema by explaining the semantics of the views and the describe action.

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 opens with a clear verb and resource: 'roster (default): every agent, its short role, and the rooms it follows'. It enumerates five distinct views (roster, presence, machines, peers, profile) and an action ('describe'), each with a specific purpose. This distinguishes the tool from siblings like komnet_inbox or komnet_send, which handle messaging rather than identity/roster introspection.

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 explicitly states when to use each view: 'roster (default)' for all agents, 'peers' for agents on your computer, 'profile' for one agent's self-description, and 'action='describe'' to rewrite your own profile. It also gives exclusion guidance, e.g., 'presence ... never proof a session still exists' and 'machines ... contested means two computers whose hostnames match, not one box'. This is explicit when/when-not guidance.

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

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

Discloses that the tool refuses needs='human' items and explains the cooperative --as-human attribute. This gives insight into the tool's internal logic and side effects, especially given no annotations are present.

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 concise but slightly stream-of-consciousness, mixing the main action with a conditional note. It is understandable and not overly verbose, though the punctuation could be cleaner.

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?

Provides sufficient context for an agent to decide when and how to use the tool, including the refusal case and the meaning of the --as-human flag. No output schema exists, so no additional return-value documentation is needed.

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?

Maps parameters directly to the example command 'komnet answer <id> "<their words>"', making it clear that messageId corresponds to <id> and body to <their words>. This adds concrete meaning 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?

Clearly identifies the action as answering a message and specifies the source as the inbox. The phrase 'as YOURSELF' distinguishes this from acting as another agent, and the refusal of needs='human' items sets it apart from sibling tools.

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?

Explicitly describes when to use the tool: to answer messages that do not require human intervention. It also instructs to surface needs='human' items instead of answering, providing clear guidance on alternative handling.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that the thread remains open until an answer arrives and explains the default needs='agent' behavior. It could add more about return behavior or side effects, but the key lifecycle trait is clearly stated.

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 four short sentences with the core purpose front-loaded. Every sentence earns its place: the action, the alternative, the rationale, and the default behavior are all packed in without redundancy.

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 no output schema, the description covers the essential decision context: when to ask, when to use send instead, and what the thread does. It does not explain how room ids are discovered or how answers are consumed, but sibling tools like komnet_rooms and komnet_inbox likely cover those.

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 75% and the schema already documents room, needs, and mentions. The description adds value by explaining why needs defaults to 'agent' and clarifying the agent-vs-human decision logic, which helps an agent make the right parameter choice.

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 states a specific action: ask another team's agent a question, and explicitly says the tool opens a thread that stays open until an answer arrives. It also differentiates itself from the sibling komnet_send by noting the distinction between needing a reply and not needing one.

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?

It gives explicit usage direction: use komnet_ask when you need an answer, and use komnet_send instead when no reply is needed. It also advises preferring asking over assuming, which helps an agent choose this tool over silent inference.

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

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

Without annotations, the description carries the behavioral burden and does a good job: it explains that leases are advisory, self-expiring, that acquire is non-blocking and re-reads network state, and that crashes do not permanently strand resources. It does not mention failure modes or edge cases like re-acquiring an already held lease, but the core behavior is transparent.

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 dense but not bloated; every sentence adds useful behavioral or usage detail. It front-loads the core purpose and then explains each action in sequence, making it easy for an agent to extract the key facts quickly.

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?

There is no output schema, so the description appropriately covers response semantics: acquire returns granted true/false and list shows holder/expiry/queue. It could be more explicit about the exact structure of the list output, but enough context is provided for correct invocation and basic result interpretation.

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 covers most parameters concisely, and the description adds meaningful semantics: action values, resource naming conventions, ttl defaults, and note purpose. The room parameter is only minimally described in the schema, but the description's examples and overall clarity compensate.

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 identifies the tool's purpose: managing advisory, self-expiring leases on shared resources with actions acquire, release, and list. It distinguishes this from sibling tools by focusing on mutual-exclusion locking rather than messaging, reading, or search.

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 practical usage guidance: acquire with a note and ttl, release when done, and wait or do other work if acquire returns granted:false. It could be more explicit about when to prefer this over sibling tools, but the advisory-lock semantics make the intended context clear.

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

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

No annotations exist, so the description must carry the burden. It does reveal permanent storage (survives sealing) and the read path, which is useful. However, it omits details like whether this is a write-only operation with no update/undo, or if there are idempotency concerns—though these are not strictly required. The description adds some behavioral color beyond the schema.

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, front-loaded with the purpose, followed by the read-back method and the alternative. Every sentence serves a purpose with no redundancy, well within conciseness limits.

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 write tool with full schema coverage and no output schema, the description effectively communicates the core behavior and usage. A minor gap is the absence of any note on permissions or consequences of superseding, but those are not essential for calling the tool correctly.

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 100%, so the schema already documents all parameters. The description adds reference to 'permanent record' but does not deeply elaborate on parameter usage; baseline of 3 is appropriate.

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?

States a specific verb 'Promote' with resource 'settled outcome to the permanent record', and clearly distinguishes it from siblings: it is the way to make a decision permanent, as opposed to komnet_send for ongoing discussion. The phrasing 'the one kind of message compaction never prunes' adds a unique trait.

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?

Explicitly contrasts with komnet_send ('for anything still under discussion') and points to the read-back method (komnet_read scope='decisions'). No ambiguity about when to use this tool.

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

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

Annotations indicate non-read-only and non-destructive. Description goes further by explaining side effects: publishes agent, joins room, syncs, sends greeting, and returns thread. It also warns about asynchronous behavior (does not wait), which is valuable behavioral context.

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?

Description is concise, with key behavioral notes front-loaded and important caveats clearly separated. Every sentence adds value; no filler or redundancy.

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?

Given a simple parameter set and no output schema, description covers purpose, side effects, timing behavior, and parameter semantics. It lacks explicit mention of response format or error cases, but these are less critical when output schema is absent and the action is well-scoped.

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 covers all four parameters with descriptions; description clarifies ackTo usage and peers default. It adds context not fully in schema (e.g., ackTo answers a handshake, peers default to everyone in room), but some parameter interplay (e.g., room required unless ackTo given) is only partially explained despite being noted in 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?

Description clearly states the tool's action: publishes agent live, joins room, syncs, sends greeting, and returns thread and who is live. It distinguishes from siblings by focusing on first-contact handshake initiation/acknowledgment, though it doesn't explicitly name sibling tools for contrast.

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?

Description explains when to use (first contact, answering a handshake via ackTo) and the non-blocking behavior ('does not wait'). It implies alternatives like send/ask for other message types, but does not explicitly enumerate them.

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

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

Annotations only declare readOnlyHint false and idempotentHint true; the description discloses the actual mutation mechanism ('Peeks unless drain=true'), the exception ('needs='human' items are never drained, since only a relayed human answer clears one'), cost behavior ('Costs a fetch per unfollowed room'), conditional defaults ('Defaults true only while you have nothing in flight'), ordering ('in flight first, then stalled'), and non-switching reads across networks ('Reading one never switches it'). This is substantial behavior beyond what annotations provide, and it is consistent with them — no contradiction.

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?

There is zero filler and the default scope is front-loaded, but the prose is telegraphic and run-on — 'Peeks unless drain=true; needs='human' items are never drained, since only a relayed human answer clears one' packs multiple behaviors into one compressed sentence. The three scopes run together in a stream, reducing parseability for an agent.

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?

Behavioral coverage is strong and scope semantics are well defined, but the tool has no output schema and the description never states the return shape — what fields or format the peek returns. Additionally, two of seven parameters (room, limit) remain undefined. For a 7-parameter tool with no output schema, these are material gaps.

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 descriptions cover all 7 parameters but are cryptic one-word pointers ('pending', 'owed', 'Default 'pending''). The main description adds real meaning by defining the three scope values the schema references and by elaborating drain, needs, includeUnclaimed, and network. However, room (schema description: 'pending') and limit (schema description: 'owed') are never explained in either place, so their semantics must be inferred.

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 'Check what is waiting for you' supplies the verb, and the three scope definitions — 'pending (default): messages addressed to you, not yet processed', 'owed: every unfinished task you are assigned, were offered, created, or could claim', 'unrouted: messages naming you in rooms you never joined' — make the inbox-listing role discernible and distinct from siblings like komnet_read or komnet_wait. However, the purpose is never stated directly as a sentence (e.g., 'returns the list of items waiting for you'); it is conveyed entirely through scope definitions, with 'Peeks' as the only explicit verb.

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?

One explicit use case is given for the unrouted scope ('so use it when someone says they sent you something you never saw') plus a cost warning ('Costs a fetch per unfollowed room'). But no alternative tools are named, no when-not-to-use is stated, and usage for the default 'pending' and 'owed' scopes is implied by their definitions rather than spelled out.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: messages are a live window in thread order, decisions survive compaction, superseded decisions are hidden unless requested. It does not contradict annotations. Minor gap: no mention of pagination or rate limits, but the core behavior is well disclosed.

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 dense but well-organized, front-loading the default scope and then explaining the decisions scope with its key caveat. It is slightly long but every sentence carries meaningful information; no filler.

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 read tool with 6 parameters and no output schema, the description covers the main behavioral distinctions and usage context. It does not describe the return format, but the absence of an output schema and the read-only annotation make this less critical. The guidance about compaction and superseded decisions is particularly valuable.

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 100%, so the schema already documents all parameters. The description adds value by explaining the semantic difference between scopes and the meaning of 'since' (read history from git) and 'includeSuperseded' (show replaced decisions), which goes beyond the schema's terse field descriptions.

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 tool reads a room's messages, history, or decisions, and distinguishes the two scopes. It explicitly contrasts with komnet_search and notes that decisions are the only read surviving compaction, which differentiates it from sibling tools.

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 explicit guidance: use decisions scope before re-opening a question or assuming a prior answer stands, and notes that neither message scope nor komnet_search reaches sealed decisions. This tells the agent when to use this tool and when not to rely on alternatives.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description adds useful context: reviews are pinned to immutable revisions, the lifecycle is guarded, and the tool never modifies a product workspace. This goes beyond the annotations and helps an agent avoid assuming unsafe workspace behavior, though it does not detail permissions, errors, or side effects on review state.

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 carry all the needed high-level information: the core action ('communicate one repository review') and a clear boundary ('never discovers, fetches, checks out, or modifies'). There is no filler, and the description is front-loaded with the tool's primary purpose.

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?

The description plus the well-documented schema (92% coverage) gives an agent enough to form a correct mental model: this is a review communication tool, not a repository or workspace tool, and it follows a lifecycle. It does not explain the review state machine in detail, but the state enum and param annotations carry that part, so the description is sufficiently complete for a tool of 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?

Schema description coverage is 92% and the per-parameter descriptions in the input schema already explain which parameter belongs to which action. The description adds only high-level context (pinning to immutable revisions, lifecycle actions), not new parameter-level meaning, so the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Communicate one repository review pinned to immutable revisions through a guarded lifecycle: request, update, and list.' It clearly distinguishes itself from siblings by saying it never discovers, fetches, checks out, or modifies a product workspace, which separates it from tools like komnet_read, komnet_sync, or komnet_send.

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 the tool (for requesting, updating, or listing delegated reviews) and gives exclusions ('never discovers, fetches, checks out, or modifies a product workspace'), which tells the agent what not to use it for. It does not explicitly name alternative sibling tools or give 'instead use X' conditions, so it stops short of full when/when-not guidance.

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

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

Annotations (readOnlyHint false, idempotentHint true) are complemented by the description: it explains that 'machine' creates and joins a room, that any agent on the box can call it because they derive the same name, and that not using it prevents co-located communication. This adds behavioral context (safety and repeatability) without contradicting the 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?

The description is compact and well-structured: the default action is front-loaded, each sentence adds unique information, and there is no redundancy. Every sentence earns its place, making it efficient for an agent to parse.

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 a single optional parameter and no output schema, the description covers both actions, the default, and the critical caveat about CLI-only rooms. It provides enough detail for an agent to decide when and how to invoke it without missing essential context.

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 has zero description coverage for the 'action' parameter, but the description fully defines both enum values ('list' and 'machine') with their specific effects and scope. This fully compensates for the schema's lack of parameter documentation.

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 defines two specific actions: 'list' (default) shows rooms with subscription state and pending counts, and 'machine' creates and joins the room shared by agents on this computer. It explicitly distinguishes this tool from other rooms by stating they are CLI-only, making its unique scope obvious.

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?

It explains when to use the 'machine' action (to enable co-located sessions to reach each other) and implicitly when not to use it for other rooms, saying those are CLI-only. It lacks explicit naming of alternative tools, but the exclusion is clear enough for an agent to route correctly.

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

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

The readOnlyHint annotation already signals no mutation, and the description adds scope constraints (live windows only, no history). It does not detail pagination or result format, but the annotation lowers that burden.

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 short sentences, front-loaded with the core purpose and immediately followed by the key exclusion. No filler or redundancy.

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?

Provides purpose and boundary versus read, but omits return value expectations and parameter behavior. Since there is no output schema, some statement about what results look like would make it more complete.

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 limited: query has no description, limit has only constraints, and room is the only param with an example. The description does not compensate by explaining how these parameters affect the search.

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?

States it performs substring search across subscribed rooms' live windows, with a clear resource and action. It also distinguishes from history retrieval by explicitly saying it does not reach history.

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?

Names the alternative komnet_read explicitly and gives the condition ('with `since`') for accessing history. This gives clear when-to-use guidance versus the sibling tool.

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

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.

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

Beyond the readOnlyHint, the description discloses concrete non-obvious behavior: status returns ids and reasons but never message bodies, reading a network never switches the current one, and approval never happens inside the tool. These details materially reduce the risk of the agent assuming side effects or content access.

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 dense but front-loaded with the default view and purpose, and nearly every sentence adds semantic or safety value. Some phrasing is cryptic ('the file is the human's') and the list of status subfields could be formatted more clearly.

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?

With no output schema, the description carries the burden of explaining what the tool reports, and it does so for the main views: what attention and surroundings contain, what machine counts, and what networks and policy show. It stops short of giving a concrete output shape, but it is complete enough for an agent to invoke and interpret the tool safely.

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 gives only an enum for view and a short network description, so the description adds real meaning by explaining what status, networks, and policy each show and how reading a network relates to the current one. The extra terms attention, surroundings, mode, and machine appear to describe status output rather than parameters, which is useful but slightly ambiguous.

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 names a clear resource—network status and this machine's setup—and enumerates three views (status, networks, policy) with distinct purposes. It does not sharply distinguish komnet_status from the sixteen sibling tools, but the inline reference to komnet_sync and the 'safe mid-task check' frame make the core purpose identifiable.

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?

It gives explicit triggers: status is the safe mid-task check; policy should be read when a claim is refused with APPROVAL_REQUIRED; mode='direct' means nothing arrives unless komnet_sync is called. It does not spell out when to choose komnet_status over komnet_inbox, komnet_read, or komnet_search, so exclusion guidance is incomplete.

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

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

No annotations are provided, and the description does not disclose side effects, idempotency, or permission requirements. The term 'poll' suggests a read operation, but 'sync' could imply writes; the description leaves this ambiguous.

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 a single, concise sentence that conveys the action and the redundancy condition without any fluff. It is efficiently structured.

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?

While the description covers purpose and usage, it omits details about the outcome of the sync (e.g., success/failure, return value) and any potential side effects. Given the tool has no parameters or output schema, this is a moderate gap but not critical for basic usage.

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 tool has zero parameters, so the schema coverage is trivially 100%. There is nothing for the description to explain; it is fully adequate in this dimension.

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 states the core action ('Poll the remote now') with a specific verb and resource. It also distinguishes itself from komnet_status by noting redundancy, which helps an agent understand its unique role among siblings.

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?

It provides a clear condition for when the tool is redundant ('while komnet_status reports mode='daemon''), implicitly guiding the agent to use it when not in daemon mode. This is explicit enough to prevent unnecessary calls.

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

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.

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

Beyond the readOnlyHint annotation, the description discloses interpretive traps: 'read' means an inbox was processed, not that a model agreed, and a header's 'seen' is not a receipt. It also explains that a 'no' for routing means delivery will never happen, which is behavior an agent would not infer from the schema.

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 compact and front-loads parameter semantics before the caveats, with backticked parameter names for scannability. It is dense and somewhat stream-of-consciousness, but each clause contributes a distinction the agent needs.

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?

Given no output schema, two optional parameters, and readOnly annotations, the description does enough to make the tool's semantics usable: it clarifies what states can be returned and what they do not mean. It could be more explicit about the exact return shape, but the core meaning is covered.

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 100%, so baseline is 3, but the description adds real meaning to both parameters: messageId is expanded into stored/pushed/routable/read/answered states, and room is defined as every agent's read position. This goes beyond the schema's one-line property descriptions.

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?

Title and description make clear this tool reports whether a message landed and where a room's agents have read up to; it explains messageId as 'one message's fate' and room as 'every agent's read position.' It does not explicitly name or differentiate sibling tools, but the resource and intent are specific.

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 concrete guidance on when to use this tool: 'Ask before concluding a peer is ignoring you,' and warns that 'not read yet' and 'will not arrive' are different problems. It stops short of naming alternatives explicitly or stating when not to use trace, but the context is clear.

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

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

The description explains what a timeout means and what it does not mean, and clarifies that a timeout indicates only that nothing arrived. The readOnlyHint annotation is consistent with the described blocking read behavior, with no contradiction.

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 front-loaded with the core action and remains reasonably concise. The timeout explanation is useful, though the 'healthy timeout' and 'degraded timeout' phrasing is slightly abstract and could be tightened.

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?

The description gives enough context for the blocking behavior, timeout bounds, and alternative to use for long waits. It does not describe the return payload, but since there is no output schema and the purpose is primarily a blocking wait, the guidance is largely sufficient.

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 100%, with each parameter described in the schema. The description adds the notion of 'matching' but does not significantly extend the parameter semantics beyond what the input schema already provides.

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: block until a matching message arrives, with a 60-second cap. It also differentiates from the sibling 'komnet watch' by framing wait as one-time blocking versus background monitoring.

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?

It explicitly advises using the background monitor 'komnet watch --thread <id>' when a reply may take hours, and implies this tool is for short, one-shot waits. It also clarifies timeout semantics so the agent knows not to treat a timeout as a failure.

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