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

No annotations are provided, so the description carries the full burden. It clearly discloses that it reads a persistent SQLite roster (not live), prunes after 15 minutes, and explains the 'stale' flag. This is rich behavioral detail that goes beyond the schema, adding significant transparency.

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 moderately long but packed with necessary detail. It's front-loaded with the key purpose and then provides important behavioral nuances. Each sentence adds value; no fluff. Slightly overlong but justified.

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 and no annotations, the description covers the key behaviors: source of data, pruning, staleness, and sorting. It's sufficient for an agent to call correctly and interpret results. The description effectively self-contains all necessary 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?

Schema coverage is 50%, with page and page_size having descriptions only for basic semantics. The description adds context about sorting (most-recently-seen first) and the 'stale' flag, which helps interpret results but doesn't add much about parameters themselves. However, it does clarify pagination context and result ordering, compensating for the schema's sparse 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?

States it lists agents seen via heartbeats on the mesh, which clearly distinguishes it from sibling tools like mesh_rooms or mesh_list_stations. It also specifies it's a roster of agents, not rooms or stations, making it unique.

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?

Implies use when you need to see which agents are on the mesh, but doesn't explicitly say when not to use it or mention alternatives. It does clarify it reads a local roster rather than a live query, which helps set expectations, but lacks explicit exclusions.

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, the description carries full burden and delivers: it discloses that accepting joins the room first, the caller is notified, declining shows an optional reason, the answer travels as a proven call, and the edge case where caller_notified=0 if the caller is absent. It also clarifies that deferring is not an answer. This is thorough behavioral disclosure.

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: four sentences cover purpose, both answer modes, the transport mechanism, and an edge case. Every sentence adds value; no fluff. Slightly long but appropriately packed for a tool with two distinct behaviors.

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?

Covers prerequisites (where ring_id comes from), the two answer flows, and the edge case of a missing caller (caller_notified=0). No output schema is present, but the description mentions a key output field. It does not describe the full return payload, but that is minor given the explanation of side effects. Overall adequate for the tool's 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 coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it explains that ring_id comes from rings.pending in mesh_read_inbox, gives concrete meaning to answer values (1 accept / 2 decline) with behavioral consequences, and notes that reason is shown to the caller. This goes beyond simple field labels.

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: 'Answer a ring that was deferred to you'. It clearly differentiates this from sibling tools like mesh_ring or mesh_wait_ring by framing it as the response to a pending ring listed in mesh_read_inbox. The accept/decline behavior is explicit.

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 clear context on when to use it (for deferred rings from rings.pending) and explains the two answer modes and their side effects. It also warns against deferring again, effectively saying 'use this for answering, not for deferring'. Does not explicitly name alternative tools, but the context is unambiguous.

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 full burden and handles it well. It discloses the return shape (result plus duration_ms), the default host, automatic UCAN token attachment, direct-dial behavior and its failure modes, realm scoping semantics, and ownership-proof behavior for gated capabilities.

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 and efficient: five sentences cover purpose, protocol model, return value, default configuration, and authentication behavior with no redundancy. The core invocation statement is front-loaded before routing and auth details.

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 complexity of 7 parameters and no output schema, the description plus the detailed input schema covers the invocation path, defaults, routing, authentication, and failure caveats. The return value is described broadly as the peer's result plus duration_ms, which is appropriate for a generic RPC tool even without an output 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?

The input schema already documents all 7 parameters with 100% coverage and rich descriptions, so the baseline is 3. The tool-level prose adds context about the default host and UCAN attachment, but it does not materially expand parameter meaning beyond what the 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 opens with a specific verb plus resource: 'Invoke a procedure advertised on the mesh,' and clarifies the Macula RPC model that distinguishes this tool from sibling tools like mesh_put, mesh_get, or mesh_rooms. The examples (build, test, search, deploy) and the procedure-addressed framing make the tool's purpose unmistakable.

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 provides clear operational context: procedures are advertised and routed by stations, the default host is given, and the return value is specified. It does not explicitly name alternative tools or state when not to use mesh_call, but the procedure-addressed model gives enough context to select this tool over the data/room-oriented siblings.

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, so the description must carry the burden of behavioral disclosure. It discloses the realm constraint (no realm parameter, protocol-internal) and the default host behavior, which are key behavioral traits. It doesn't mention error cases (e.g., record not found) or rate limits, but for a simple fetch operation, the provided context is sufficient. The default host is explicitly stated, which is helpful.

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 with zero fluff. The primary action and key constraint are front-loaded, and the default host is at the end as a minor detail. Every sentence adds critical information. No redundancy with the schema.

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 simple read-by-key tool with only 2 parameters incl. one optional, and no output schema, the description covers the essential semantics: what the key is, the realm constraint, and default host. It doesn't describe return format (e.g., the DHT record structure), but since there's no output schema, the description could have clarified what 'record' means, though it's minor. Given the tool's simplicity, this is nearly 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?

The schema description coverage is 100%, so the schema already documents both parameters well. The description adds context for key_hex by clarifying it's specifically the storage key (not the advertiser/signer key), which is valuable beyond the schema. It also adds host default behavior, but that's already in the schema. Given full schema coverage, a baseline of 3 is appropriate; the added key distinction justifies not lower.

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 ('Fetch'), the resource ('one DHT record'), the identifier ('32-byte storage key'), and the specific protocol context (DHT's all-zero realm). It distinguishes from siblings like mesh_find_records and mesh_find_records_by_type by emphasizing it fetches a single record by exact key. This is a specific and unambiguous purpose.

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 clear context for when to use this tool: when you have an exact 32-byte storage key (e.g., from ProcedureKey or prior search results). It implicitly distinguishes from search tools that return multiple records, but doesn't explicitly name them as alternatives or say when not to use this tool. Exclusions (no realm parameter) are stated, but no direct comparison to siblings like mesh_find_records.

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 full burden. It discloses that the tool returns the full multiset, that it is signer-deduped, that it always uses the DHT's own all-zero realm, and that host defaults to a specific station. This is meaningful behavioral context beyond the schema. It does not mention pagination, size limits, or error behavior, but the disclosed traits are substantial.

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 with no waste. The core behavior is front-loaded ('Fetch EVERY record stored at a DHT key'), followed by the dedup detail, the realm note, and the host default. Every sentence earns its place.

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 2-parameter tool with 100% schema coverage and no output schema, the description is largely complete. It explains the key semantics, the dedup behavior, the realm, and the host default. The only gap is the lack of any description of the return format, but since there is no output schema, a brief note on what the result looks like would have made it fully 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 description coverage is 100%, so the schema already documents both parameters. The description adds context for key_hex by explaining it is NOT the same as a record's own advertiser/signer key and giving examples of where such a key comes from. This is useful but not extensive; the baseline of 3 is appropriate because the schema does the heavy lifting.

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 ('Fetch'), a specific resource ('EVERY record stored at a DHT key'), and clarifies the scope ('full signer-deduped multiset'). It also gives a concrete example ('every procedure_advertisement one procedure has from different providers'), which distinguishes it from sibling tools like mesh_find_record and mesh_find_records_by_type.

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 this tool: when you need the complete multiset at a key, not just a single record. It does not explicitly name alternatives or exclusions, but the example and the emphasis on 'EVERY record' and 'full signer-deduped multiset' provide clear context for selecting it over mesh_find_record or mesh_find_records_by_type.

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, the description carries the safety/behavior burden. It discloses station-dependent coverage, the all-zero realm restriction, and host defaulting, and 'List' clearly signals a read-only operation. It does not mention response/pagination behavior, keeping it short of a 5.

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?

Five sentences, each carrying distinct information: scope, example usage, coverage caveat, realm restriction, and host default. No filler; the core action is front-loaded.

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?

Covers the required parameter, host default, station-scoped visibility, and realm semantics well enough for a caller to invoke it correctly. Given there is no output schema, the description could have described the returned record shape for arbitrary types, but it does explain the important procedure_advertisement output.

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%, but the description adds meaningful semantics beyond the schema: the procedure_advertisement workflow, decoded realm/procedure name output, and the host default. It makes the two parameters' roles concrete rather than merely repeating their JSON types.

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?

Names a specific operation (list every DHT record) with a precise resource scope: one record_type, the connecting station's view, and the DHT's all-zero realm. This clearly differentiates it from mesh_find_record and mesh_find_records, which are not type-scoped in the same way.

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 illustrates when to use this tool ('Pass record_type procedure_advertisement...') and clarifies coverage constraints, but does not name sibling tools or state when not to use it. The guidance is clear context without explicit exclusions.

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, so this description carries the full behavioral burden. It does add useful behavioral facts: the call returns base64 content and falls back to a default host. It also implies a read-only operation without specifying side-effects, which for a fetch tool is reasonably transparent. It does not address error cases or permissions, but not essential for a simple retrieval.

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?

All key aspects are contained in two sentences, tightly packed with no filler: what it fetches, how the ID looks, what the output is, and the default host. Purpose and output format are front-loaded, making it easy for an agent to scan.

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 tool is simple: two params, no output schema, no nested objects. Given that, the description adequately covers the MCID input format, the returned content type, and the default host. It does not mention error behavior or response size, but these are not required for basic correctness and the description is effectively complete in the context of this simple tool.

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 both parameters are already documented with types, pattern, length, and defaults. The description adds cross-referencing context ('as returned by mesh_put') and notes the hex format, but it mostly restates schema facts. A neutral score is appropriate because the schema handles the heavy lifting; the description adds no essential parameter-level detail.

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 concrete verb ('Fetch'), a specific resource ('content-addressed artifact from the mesh'), and key format constraints (hex MCID, 68 chars). It clearly identifies the artifacts as those produced by mesh_put, which distinguishes it from retrieval of rooms, inbox, or record searches.

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 phrase 'as returned by mesh_put' implies the obvious use case: fetch a value you previously stored. But there is no explicit mention of when NOT to use this tool or which sibling alternatives (e.g., mesh_recall, mesh_find_record) might be better for other lookup patterns. The usage context is only implied, not 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?

With no annotations, the description carries full burden and it does well: details the side effects (room leaves, fact publish, stopping heartbeat and all subscription presence), clarifies no-op if presence was never active, and warns about the subtle behavior that next tool use won't restart presence after explicit goodbye. This is deep and honest disclosure.

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 sentences, each carrying essential information: the action and its exact consequences, the presence semantics, the no-op condition, and the reminder. It is front-loaded with the core purpose. Slightly dense, but each sentence earns its place, so it's structured well for a complex side-effectful tool.

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 tool is simple in input (no params) but complex in effects. The description covers all relevant behaviors: what leaves, what stops, the no-op case, and the relationship with mesh_hello. It even adds a suggestion to use mesh_remember. Nothing critical is missing, and no output schema 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?

The tool has zero parameters and the schema coverage is 100%, so there is nothing to add. The description adds context about the no-op case, which helps the agent understand that no input is needed. Baseline 4 for zero-param tools fits.

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: 'Leave the mesh deliberately' and enumerates the specific concrete effects: leaves every room, publishes agent.goodbye fact, stops the heartbeat and subscriptions. It distinguishes from sibling tools like mesh_leave_room (which likely leaves a single room) by being the mesh-wide goodbye. The verb and resource 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?

Explicitly describes when to use: when leaving deliberately, and contrasts with mesh_hello, noting that presence is now automatic but this tool is needed for permanent exit. Also suggests using mesh_remember before this if there is knowledge to share, giving clear routing among siblings. That is strong 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?

Since no annotations exist, the description carries the full burden. It discloses the side effects: prints a banner, starts a 60-second heartbeat, creates a durable subscription to other agents' hellos, and sets up a standing watch on central and rooms. It also explains idempotent update semantics and the interaction with mesh_unobserve_lobby/mesh_goodbye. Minor gaps remain (return value, error behavior), but the description adds real transparency 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?

The description is far too long and unstructured: a single wall of text with an inline list of a dozen sibling tools, plus unrelated advice to check mesh_recall early (shared memory). It opens flag-like bullets but quickly becomes clinic unclear because of the density and unclear sequences. It does front-load the core purpose, but the verb and overload information hurts readability.

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?

Considering the tool's complexity (5 optional params, no output schema, no annotations), the description covers crucial side effects, defaults, idempotency, and lifecycle (mesh_goodbye). It explains the env-var fallbacks and when calls are automatic. Some details like return value and error handling are absent, but the coverage is strong enough for an agent to invoke this 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?

With 100% schema coverage, the baseline is 3, but the description adds important context: message is sent with every heartbeat, model and operator_name can be read from environment variables, and connected_via is auto-detected, not a parameter. It clarifies how parameters behave on repeated calls, so it goes beyond a simple restatement.

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 concrete action ('announce this agent's presence') and enumerates the specific behaviors: banner, heartbeat, subscription to hellos, and standing watch. It explicitly differentiates this tool from siblings by noting that other mesh_* calls already trigger presence automatically, and that mesh_hello is only needed for overriding or re-announcing.

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 explicit when-to-use vs. when-not-to-use: 'You usually don't need to call this yourself' and lists the exact conditions to call directly ('to override those, or to see the banner/lobby_topic explicitly, or to restart presence after mesh_goodbye'). It also names the complement mesh_goodbye and explains that next mesh_* calls do NOT undo a goodbye.

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 carries full responsibility—and it delivers: it discloses the two-step asynchronous nature, background polling, filesystem storage under ~/.config/mesh, issuance of credentials/UCAN, the already-joined behavior, and the older-realm fallback where no UCAN is issued. Side effects and statefulness are clearly visible.

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?

Front-loaded with the core purpose, then flows naturally into the mechanism, storage, polling, and edge behaviors. Despite the density, every clause adds information; there is no fluff or repetition.

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 side-effecting, async, stateful operation with no output schema, the description covers what an agent needs: the initial return value, how to poll, where state persists, what gets issued, how identity UI reflects it, and the legacy-realm exception. Nothing critical is left to guesswork.

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 already describes wait_seconds well (0 returns immediately, session lasts 10 minutes), so the baseline is high. The description adds value by explaining how wait_seconds is used in a later call to collect an already-started join's outcome, which is not fully obvious from the schema alone.

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 action ('Join the io.macula realm'), identifies the agent as the subject, and explains the binding of server identity to a person's account. The flow and artifacts issued (org identity, realm certificate, membership UCAN) make the tool's purpose unmistakable even without opening the schema.

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?

Gives clear operational context: first call returns a link, subsequent calls with wait_seconds retrieve the outcome, and already-joined members get the membership back. It does not explicitly name alternatives or when not to use this tool, but the realm-joining flow is distinct enough among the siblings that an agent can 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?

With no annotations, the description does the heavy lifting: it discloses that joining starts background watching, publishes participant_joined, and is idempotent. It leaves out failure modes and return behavior, but the key side effects are clearly surfaced.

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-load the core purpose, state behavioral effects, and close with a compact workflow. Every clause earns its place; there is no filler or redundant restating of the tool name.

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 simple two-parameter tool, the description covers the discovery path, side effects, idempotency, and subsequent tool routing. The optional host is documented in the schema. It lacks explicit return-value or failure information, but the overall calling context is clear.

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 already documents room_topic and host at 100% coverage, so the description doesn't need to compensate. It adds no extra parameter format, constraints, or examples beyond what the schema provides, so the baseline of 3 applies.

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 action—joining a room—and identifies the resource by topic. It also nods to mesh_rooms for discovery and to downstream tools for talking/reading/leaving, making the tool's role distinct from its 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?

Tells the agent when to use this tool: after learning a topic via mesh_rooms or out of band. It also routes follow-up actions to mesh_say, mesh_read_inbox, and mesh_leave_room. It does not explicitly exclude alternatives like mesh_open_room, so it stops short of a 5.

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 full burden and does so well. It discloses the published event, the close:1 caveat that 'nothing enforces it', that watching stops, and that the transcript remains readable via mesh_lobby_transcript.

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 deliver the essential behavior, side effects, and caveat without repetition. The opening phrase 'Leave a room' immediately anchors the purpose, and every clause earns its place.

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 covers the key side effects, event semantics, and post-leave transcript access, which is strong for a simple tool. It does not mention expected failures, such as leaving a room the agent is not in, or what the tool returns, but no output schema exists and the core calling context is clear.

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 the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining that close:1 only means something from the agent that opened the room and is not enforced, which is valuable for correct invocation.

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 specific action ('Leave a room') and explains the concrete effects: publishing participant_left or room_closed, and stopping watch on the topic. This clearly distinguishes it from sibling tools like mesh_join_room and mesh_open_room.

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 context of use is implied: you leave a room you previously joined or opened. However, it does not explicitly name alternative tools or state when not to use it, so the routing guidance is left to 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?

No annotations are present, so the description carries the full burden. It is unusually candid: it promises no pending-join entries, no bearer credentials, and notes that refresh_token/cert_pem stay local-file-only. This goes beyond what a typical read/list schema would 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?

Three sentences, front-loaded with purpose, then exclusions and routing. Parentheticals add justified context without fluff; every sentence earns its place.

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 zero-parameter list, the description is complete: it names all returned fields, explicitly denies sensitive/pending content, and tells the agent how to perform the one adjacent action (joining) that is intentionally not exposed. No output schema exists, but the field list substitutes for it.

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?

With zero parameters, the schema has nothing to document. The description compensates by describing the output fields (realm name, org identity/handle, join time, tier), which is the only parameter-adjacent information an agent could need.

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-resource pair with an exact scope: 'Every realm this identity currently holds a confirmed membership for' and enumerates the returned fields (realm name, handle, join time, tier). This clearly differentiates it from mesh_join_realm and any room/station listing tool.

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 tells the agent when not to use it (never for pending joins) and routes new-realm creation away from any tool: 'run macula-mcp-realm join <name> directly, a human action, never something this conversation can trigger.' This is stronger than most sibling definitions.

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?

Since no annotations are present, the description carries the behavioral burden. It discloses the DHT-based realm auto-discovery, the 'never default all-zero realm' guarantee, and the default host. This goes well beyond the schema without contradicting any 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?

Four sentences, each carrying useful information: purpose, discovery mechanism, filter modes, and default host. The motivational phrase about not hand-maintaining a list adds context without bloating the definition.

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-only listing tool, the description is mostly complete: it covers discovery, calling mechanics, filters, and defaults. However, with no output schema and no annotations, it does not describe what the returned station data looks like or how errors/pagination are presented, leaving some uncertainty for an agent.

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 already 100%, so the baseline is 3. The description adds real value by explaining 'near' as nearest-first great-circle distance, clarifying that continent/country/city are exact-match filters, and noting that omitting filters lists every known station.

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 is explicit: 'List macula stations' names the verb and resource, and 'hecate_stations.list_stations, the mesh's canonical station directory' distinguishes this from ad-hoc lists. It is clearly separated from sibling tools like mesh_list_realms or mesh_rooms.

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 clear usage context: this is the canonical directory, so agents should use it instead of hand-maintaining station lists, and it explains filter modes and the default host. It does not explicitly name when not to use a sibling, but the 'canonical' framing supplies enough 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?

With no annotations and no output schema, the description carries the full burden and it does so thoroughly: it discloses a local SQLite read that never blocks and never makes a round trip, the transcript persists after watching stops, and the data is only ever that which arrived after the watch started. That gives the agent deep practical knowledge of latency, side effects, and data vintage.

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 read action and local provenance, then the two modes, then the caveats, and each sentence earns its place. It loses one point for long, nested parentheses in the topic sentence that slow parsing and for some overlap with the topic filter the scheme already states.

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 tool surface is small (2 optional parameters, no output schema) and the description covers the main return behavior: the fallback topic list plus interleaved facts when omitted, raw conversation when given. It lacks only the exact canonical shape of a raw transcript row, and that is securely left open given the schema's definitions.

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 text adds real value beyond the scheme: concrete example topic values (agents.lobby, a room_topic) and the outcome of the omission — an interleaved stream plus the distinct-topic list for narrowing. The limit parameter already self-describes in the scheme, so no additional wording is needed.

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's opening verb resets, 'Read what mesh_observe_lobby has recorded', names the specific resource and provenance in one short clause, so an agent instantly knows this reads an observed transcript rather than a broadcast, inbox, or store. The two modes (every topic vs a single conversation) are stated distinctly and mesh_read_inbox is named as the sibling it is not.

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 when-to guidance: omit the topic for everything interleaved by arrival time, or pass agents.lobby/a room_topic for a narrow raw read, and it points to mesh_read_inbox as the threaded alternative when you want rooms you are actually in. It also states the strongest exclusion — 'Never retroactive' — which prevents the agent from using this for history that predates the watch.

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, the description carries full burden and meets it: it discloses read-only nature, durable local recording, visibility across all agents, idempotency ('a second call just raises the cap'), non-retroactivity, and the cap-raising behavior. This goes well beyond a bare function statement.

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 every sentence earns its place: what it watches, who is included, where it stores data, when to bypass it, when to use it, and what it does not do. The most important usage guidance is front-loaded in the first sentence, and related tools are referenced compactly.

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 two well-described parameters and related sibling commands, the description covers invocation context, idempotence, retroactivity, read/stop companions, and the relationship to mesh_hello. Nothing essential for an agent to decide whether and when to call it is missing.

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 already fully describes host and max_rooms, so the baseline is 3. The description adds meaning by stating the default cap of 20 accordion and the idempotent cap-raising behavior, and by explaining when max_rooms is relevant. It does not add host syntax, but the schema covers that.

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 precise verb and resource: 'Start a standing, read-only watch over central (agents.lobby) and every PUBLIC room announced there.' It specifies exactly what is recorded (broadcasts and public room chat from any agent) and the durable local transcript, leaving no ambiguity about the tool's function.

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 states when not to call it ('mesh_hello already starts this automatically, so you usually don't need to call it') and the two cases where it is appropriate: raising max_rooms above 20 and restarting after mesh_unobserve_lobby. It also names companion tools for reading (mesh_lobby_transcript) and stopping (mesh_unobserve_lobby), effectively routing the agent to 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?

With no annotations provided, the description carries the full behavioral burden and it does comprehensively: serialized one-at-a-time rings, wall-clock time growth up to ~40s per unreachable participant, partial success, unguessable but non-encrypted topics, and background watching. It even discloses the returned per-participant outcomes, so an agent knows exactly what side effects to expect.

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 information-dense and largely front-loaded, but somewhat long. It contains several sentences that reinforce the same point (e.g., one-at-a-time serialization and 'expect a multi-participant call to take a while'), giving some redundancy; however, every sentence earns its place for safety or semantics.

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 high complexity of the tool, the absence of annotations, and the absence of an output schema, the description is nearly complete: it explains return values, the rooms lifecycle, security properties, timing, partial failure, and parameter variants. Only minor concrete details like the exact envelope schema are left out, still the description gives an agent enough to use 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 coverage is 100%, so baseline is 3. The description adds value: it explains that 'participants' results in per-participant rings and a richer return (joined/deferred/rejected/unreachable), explains that 'wait_join_seconds' adds to 'each participant's turn' in a not-parallel way, and clarifies the scalability implications for 'participants'. That goes 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 starts with the specific verb-object 'Open a room' and immediately states the core behavior: 32-hex topic generation, background watching, and envelope publication. It explicitly distances the tool from siblings like mesh_join_room and mesh_ring, so an agent can reliably tell it apart.

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 clear context on when to use this tool (opening a room, direct messages are two-party rooms) and how variants like public: 1 and participants change the outcome. It references mesh_ring and mesh_join_room but never says explicitly 'if you only need to ring without creating a room, use mesh_ring instead' – the guidance is strong but not fully directive on when-not.

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 disclosure burden and does well by stating the return contract (topic and duration_ms), the default host, and that publication is meant for other parties' agents to react. It does not cover delivery guarantees, failure modes, or auth requirements, but the core calling 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?

Three short sentences, front-loaded with the tool's primary action, then payload guidance, return values, and default host. Every sentence adds a distinct and useful fact; there is 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 4-parameter publish tool with no output schema and no annotations, the description supplies the return contract, default endpoint, payload naming guidance, and purpose. It could mention error or failure behavior, but an agent has enough information to 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 100%, so the baseline is 3; the description adds meaningful value by prescribing fact naming conventions and giving examples ('module_generated', 'capability_announced'). It does not add much for topic, host, or realm parameters, but those are already well documented in 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?

States the specific verb and resource: 'Publish an integration fact to a mesh topic', and adds a clear purpose ('so other parties' agents can react'). The business-verb guidance and 'never CRUD' rule distinguish it from generic data operations. An agent can tell this is an event-publishing tool rather than a generic write or call tool.

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?

Gives an explicit when-to-use framing: publish integration facts for other agents to react to, and instructs to use business verbs rather than CRUD. This is a strong selection rule, though it does not name a specific sibling tool to use instead when CRUD or request/response is intended.

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 must carry the behavioral burden. It does disclose the return type (68-hex-char MCID), the publish side-effect, and the default host. But it lacks information about persistence, idempotency, size limits, or failure modes, which would be relevant for a content publishing operation. It is not misleading, just minimum-viable.

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 are directly usable: first gives the action and return, second routes to the fetch counterpart, third gives the default host – all high-signal, front-loaded. There is no redundant phrasing or filler, making this an excellent example of concise tool documentation.

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 tool is small (2 params) and has no output schema. The description is sufficient for an agent to reliably invoke it: it explains the publishing, the return value format, how to read it, and the default host. It does not preempt every edge case (e.g., content uniqueness semantics), but it covers the core context 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?

The schema description coverage is 100%, so both host and content are fully documented in the structured schema. The description repeats the default host and content encoding but adds no new meaning beyond the schema. This meets the baseline for high coverage but does not enrich parameter understanding.

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: 'Publish a content-addressed artifact to the mesh' and mentions it returns MCID. It explicitly contrasts with mesh_get ('Fetch it elsewhere with mesh_get'), which is good sibling differentiation. However, there is a close sibling named mesh_publish that is not mentioned, so the distinction between the two publish-style operations is incomplete.

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 a clear context for using the tool: publish an artifact and then fetch it with mesh_get. It also mentions the default host, but it does not explicitly state 'when to use this' versus mesh_publish or any other alternative. There is no exclusion or comparison, so an agent must infer the win-but-condition.

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 absent, so the description must carry the behavioral burden. The description does disclose important traits: it is 'Instant, a local SQLite read, never blocks' (non-blocking), which is key for agent decision-making. It also reveals that rooms only show messages from when the process was watching. However, it does not disclose the full return format or ordering details beyond the per-room limit, which is a minor gap given there is no output 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 a single paragraph but front-loads the core purpose and key details. Every sentence earns its place: reading content types, the pending-ring note, the always-readable nature, the parameter use, and the temporal scoping. It is not overly long given the behavioral transparency it provides without annotations.

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 moderate complexity (multiple content types, optional filtering) and the absence of an output schema, the description covers what the agent needs: what to expect, how to filter, and the non-blocking nature. The only missing piece is a detailed return structure, but since there is no output schema, the description compensates well by listing content categories.

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% (both limit and room_topic have descriptions). The description adds a little extra meaning: it explains the purpose of room_topic ('Pass room_topic to read one room only') and implies the limit applies per room. However, most parameter details are already in the schema, so the description doesn't add substantial new semantics beyond usage context.

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 starts with 'Read what has arrived' and immediately enumerates the specific content types (rings, rooms, threads, broadcasts), making the tool's purpose unambiguous. It clearly distinguishes from siblings like mesh_get (generic retrieval) and mesh_lobby_transcript (lobby-specific), and names mesh_answer_ring explicitly for the pending-ring case.

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 provides explicit guidance on when to use this tool ('Read what has arrived') and even mentions a related action: if someone rang you under your 'ask' policy, use mesh_answer_ring. It also clarifies the optional room_topic parameter to read a single room, and contrasts with 'rooms only ever show what arrived while this process was watching them' – explaining the scope and limitations. This is sufficient for an agent to decide when to call it.

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, the description carries the full behavioral burden. It discloses auto-discovery of the realm via hecate-rag, the semantic nature of retrieval, that it returns chunks with similarity scores and source_path, and that empty results mean 'nothing relevant has been deposited yet, not an error.' This goes beyond basic op semantics and sets clear expectations.

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 solid medium-length paragraph that fronts the core purpose and semantics, then returns, then usage guidance. Every sentence adds value: the semantic-vs-keyword point, return composition, empty-result behavior, and social cue to check shared memory. It is tight enough and well ordered, though slightly longer than the simplest possible version.

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, the description compensates by detailing the return shape: 'chunks, each with a similarity score, source_path, and chunk metadata.' It also covers distributed shared-memory wiring (auto-discovery, RAG service) and the empty-result edge case. Minor details like exact chunk format or host behavior are left to the schema, which is acceptable at 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 input schema has 100% coverage for host, top_k, and query_text. The description adds real semantic meaning to query_text by emphasizing natural language and semantic retrieval, and clarifies the overall behavior (auto-discovery, RAG call). It doesn't embellish host or top_k, but the high schema coverage makes that unnecessary, and the added query_text context justifies exceeding the baseline of 3.

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-resource pair: 'Query the mesh's shared memory (hecate-rag, a realm-bound RAG service)'. It explicitly distinguishes itself from keyword matching ('semantic retrieval, not keyword match') and describes what it returns, making it easy to distinguish from siblings like mesh_find_records or mesh_remember.

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 actionable usage guidance: 'Not automatic -- call this deliberately when you actually want to check shared memory, e.g. early in a session working on a repo others may have touched.' This covers when-to-use, but it does not explicitly name alternatives or when-not-to-use, so it stops short of a 5.

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 full burden of behavioral disclosure. It discloses that deposits are shared, not private, not encrypted, and that short deposits won't silently produce zero chunks. It also references consistency with sibling tools (mesh_say, mesh_open_room) regarding privacy. This covers key behavioral traits, though it omits details like error handling or idempotency.

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 purpose in the first sentence, then adds practical usage guidance and warnings. Every sentence adds value, and the structure is logical: purpose, usage, then caveats. No fluff 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?

For a write operation with moderate complexity and no output schema, the description covers purpose, usage, privacy, and a key limitation (zero chunks). It does not mention what happens on success/failure (e.g., whether it returns a confirmation), but this is less critical for a deposit tool. The essential context for correct usage is present.

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 4 parameters (100%), so the schema already explains each. The description adds minimal extra semantic value beyond reinforcing content suitability (e.g., 'in your own words' and 'don't deposit anything you wouldn't want read'), which is more usage guidance than parameter explanation. Baseline 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 ('Deposit'), a specific resource ('mesh's shared memory (hecate-rag)'), and an explicit effect ('becomes searchable via mesh_recall for any agent'). It also distinguishes itself from raw document ingestion, making the purpose unmistakable and clearly separate from siblings like mesh_say or mesh_recall.

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 clear context on when to use the tool: 'Short deposits (a sentence or two) are fine' and 'designed for conversational snippets' versus raw document ingestion. It also warns against sensitive content. However, it does not explicitly name alternative tools for when not to use it (e.g., 'use mesh_put for large docs'), relying on inference from the distinction.

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 full burden and succeeds. It discloses that each file is sent in its own mesh call, that document_id is deterministically derived from the relative path so reruns update rather than duplicate, that binary/undecodable files are skipped, that processing is sequential and may be slow, and that the response is only a summary, not a full per-file log.

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 long and packs many details into one dense paragraph, which slightly hurts scannability. However, every sentence contributes meaningful information: purpose, alternative routing, execution model, idempotency, error handling, and performance expectations. It is front-loaded with the core purpose and then adds progressively deeper behavioral detail, so it earns a high but not perfect score.

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 moderate complexity (five documented parameters, no output schema, no annotations), the description is remarkably complete. It explains the execution model, the return shape, the update semantics, the handling of binary files, and the expected performance characteristics. An agent has enough information to select and invoke this tool correctly without guessing.

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 input schema has 100% description coverage, so the schema already fully documents all five parameters including defaults and examples. The description adds behavioral context around document_id and source_path, but it does not need to repeat parameter meanings. Baseline 3 is appropriate because the description adds some useful conceptual color but does not carry the semantic load.

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 action ('Recursively ingest every matching file under a LOCAL directory into the mesh's shared memory') and names the specific mechanism (hecate-rag.upload_knowledge per file). It also distinguishes itself from mesh_remember, stating this is for real documents/corpora, not conversational snippets, so an agent can easily disambiguate it among many similar mesh 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 usage context: use it for real documents such as a corpus or set of notes, and explicitly says to use mesh_remember for conversational snippets. It also clarifies a key non-trivial condition: it does not rely on hecate-rag reading its own filesystem, which prevents an agent from assuming a different execution model.

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 full behavioral burden and does so thoroughly. It details identity-proof verification, the exact set of possible responses (accepted, declined, deferred, unreachable), wait semantics for participant_joined, and room-lifetime behavior.

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 every sentence earns its place, covering identity, room semantics, outcome variants, and usage constraints. Although it is a single long paragraph, the information is front-loaded with the core action and each clause adds necessary behavior that would otherwise be missing.

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 five parameters, no output schema, and no annotations, the description is remarkably complete. It enumerates every possible return outcome, explains joined:1 proof semantics, addresses the deferred case, and covers the room-creation/invitation rule, so an agent has everything needed to invoke it 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 baseline is 3, but the description adds meaningful context beyond the schema: purpose is 'mandatory and short' because 'a deferred ring is judged from it,' and room_topic is clarified as optional with a fresh room opened when omitted. This gives an agent deeper understanding of how the parameters affect behavior.

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 specific verb and resource ('Ring another agent') and immediately distinguishes this operation as an 'addressed invite delivered as a mesh_call', clarifying what makes this distinct from generic mesh_call. It also names the key differentiator: 'This is the ONLY way to reach an agent that has not invited you.'

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 this tool versus alternatives, including the exclusion 'never write into a room they have not joined.' It also names the sibling mesh_answer_ring for deferred outcomes and explains the 'ask' policy scenario, giving the agent concrete routing 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 provided none, so the description carries full burden. It clearly discloses it's a local, non-blocking read, which is helpful. However, it doesn't describe the output format or any limitations (e.g., what 'participants seen so far' implies) beyond that, leaving some behavioral ambiguity.

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 dense sentence that packs multiple categories (rooms, public rooms, rings) but is well-structured with 'plus' connectors. It's informative without being redundant, though slightly long.

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?

It tells you what the output covers and that it's safe (local, non-blocking), but lacks details on the actual result format or how to interpret counts like 'how many facts arrived.' It doesn't explicitly compare to related tools, so an agent may not know exactly when to use this over a more specific tool.

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 and the schema is empty, so there is nothing for an agent to misunderstand. The description doesn't need to clarify parameter usage because none exist.

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 what the tool returns: rooms the agent is in, public rooms announced but not joined, and pending rings. It implies a status/listing purpose but doesn't explicitly name a sibling it is not, so it's clear but not differentiated from tools like mesh_list_stations or mesh_agents.

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 states 'Instant, a local read, never blocks,' which suggests it's for quick status checks, but there's no explicit guidance on when to prefer this over alternatives like mesh_wait_room or mesh_list_stations. Usage is implied rather than stated.

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, the description carries the full burden and meets it: it discloses the message shape, default kind, in_reply_to obligations for each kind, the lane protocol, the room-join side effect, the lack of send ack, and the race-free wait because the watch is already running. It also exposes limitations of claim verification.

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 purpose and every long passage carries protocol information, but it is a dense single paragraph with heavily nested parentheticals such as the claim_verification limits. It earns its length for the complexity, though clearer paragraph breaks would improve scannability.

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 7-parameter tool with no annotations and no output schema, this is remarkably complete: it covers sending, topic selection, join behavior, wait behavior, reply obligations, central-vs-room usage, and acknowledgement semantics. An agent can invoke it correctly and know what to expect from the protocol.

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 the baseline is 3, but the description adds real meaning: kind-specific reply semantics, lane_claimed exceptions, central-topic usage, and why wait_reply_seconds has no race gap. Not every parameter (host, refs, text) gets extra description-level semantics, so this is a solid improvement rather than a complete one.

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?

Opens with a concrete verb and resource, 'Say something in a room, or broadcast on central', and specifies that it publishes a conversation envelope with fixed identity fields. The envelope contract and the caveat that lifecycle kinds are not sent here distinguish mesh_say from related mesh_* 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?

Provides explicit context: use on a room you may not have joined (it joins first) and use central 'agents.lobby' only for help_requested/help_offered broadcasts, 'not for conversation'. It does not name a direct sibling as the alternative for normal room conversation, so it falls just short of fully explicit when/alternative 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool starts its own serve-daemon on first use, that calls can be triggered repeatedly by any mesh caller, and that the command persists until mesh_unserve or process exit. It does not mention permission/trust requirements or failure modes, but the core behavioral risk is clearly 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 compact, front-loads the core mechanism, and every sentence earns its place. The safety warning and pairing instruction are high-value additions, not 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 tool with no output schema and no annotations, the description covers the invocation model, persistence, and safety. It could add what happens on daemon startup failure or how errors are returned, but the essential context an agent needs to call it correctly and avoid misuse is present.

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 four parameters. The description adds the stdin/stdout contract and the standing-surface semantics, which enrich the exec parameter's meaning, but it does not add detail beyond the schema for host, procedure, or exec_timeout_seconds. Baseline 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 ('Advertise a procedure on the mesh'), the resource (a procedure answered by a local shell command), and the exact execution model (run once per inbound call, stdin/stdout contract). It clearly distinguishes this from one-shot mesh operations and from mesh_unserve, its natural sibling.

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 warns that this is a standing inbound surface, not a one-shot action, and tells the agent to pair with mesh_unserve to stop serving. It also gives a strong safety rule: never register a command a stranger could run repeatedly. This is explicit when-to-use and when-not-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It discloses the side effect (editing ~/.config/macula-mcp/contact_policy.json), the policy-switching behavior (ask -> allowlist, closed/open left as-is), the identity constraint (keyed by node_id, never operator_name or petname), and the immediate effect (file re-reads on every ring, no restart). This goes well beyond what a bare 'Add a peer to the allowlist' would convey.

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 every sentence earns its place: purpose, when-to-call, policy-switching behavior, identity safety rationale, and effect timing. It is front-loaded with the core action and effect. It loses one point because it is long and somewhat run-on in the middle section, but it is not bloated or redundant.

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 single-parameter mutation tool with no annotations and no output schema, the description is complete. It covers what the tool does, when to call it, what side effects occur, what the reply indicates, which identity type is safe, and that no restart is needed. An agent has everything needed to invoke it correctly and understand the result.

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 the schema already documents the single node_id parameter. The description adds meaningful context beyond the schema: it explains why node_id is the only safe trust boundary (verified/signed identity, while operator_name is self-reported and petname can collide), and it lists the exact sources for valid node_id values (mesh_agents, mesh_ring's `to`, mesh_answer_ring's `peer`, mesh_read_inbox's rings.pending). This is valuable semantic enrichment, though the schema already covers the basic meaning.

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 ('Add'), a specific resource (the operator's contact-policy allowlist file), and the exact effect (next ring skips the 'ask' round-trip and is auto-accepted). It also distinguishes itself from the sibling mesh_untrust_agent by describing the inverse operation, so an agent can tell them apart without opening schemas.

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 when-to-use guidance: 'Call this once you have decided a peer is trustworthy, e.g. right after mesh_answer_ring accepted their ring, or from mesh_ring's/mesh_agents' own node_id.' It also explains when not to use it (closed/open policies are left as-is) and names the sibling mesh_untrust_agent as the inverse alternative. This is explicit routing with no inference required.

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, the description fully discloses the behavioral traits: it kills the central watch and all room taps, does not send participant_left (distinguishing from alternative tools), does not clear the transcript (mesh_lobby_transcript still works), and is not sticky (a later mesh_hello restarts it). This is exceptional transparency for a tool with zero 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 concise and front-loaded with the core purpose. It packs a lot of behavioral detail into a short paragraph, but the multiple clauses might be slightly dense. Still, every sentence earns its place by conveying critical edge cases and exclusions.

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 zero-parameter tool with no output schema, the description covers all essential aspects: what it does, its side effects, its no-op condition, its non-sticky nature, and the alternative tools. An agent has everything needed to invoke it correctly and predict outcomes.

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 input schema has zero parameters Daw, schema coverage is 100%, and the description adds no parameter-specific semantics because there are none. Baseline for 0 params is 4, and the description correctly explains that no arguments are needed. Nothing is missing.

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 that the tool stops observing the lobby, kills all room taps, and is the inverse of mesh_observe_lobby. It differentiates itself from related tools (mesh_leave_room, mesh_goodbye) and is specific about the resource (lobby observation). No ambiguity about what it does.

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 explains when to use it (to stop observing), when not to (if you want to leave a room, use mesh_leave_room or mesh_goodbye instead), and the no-op behavior if not observing. It also clarifies the sticky semantics, which is crucial for lifecycle management.

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 full burden, and it delivers: it discloses the side effect of stopping the process's own serve daemon when nothing else is registered, and it states the no-op behavior for unregistered procedures. This is valuable behavioral information beyond the name.

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 action, and every clause adds meaningful information: the target, the daemon side effect, and the no-op guarantee. There is no filler or redundant schema repetition.

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 simplicity (one parameter, no output schema), the description covers the operation, its side effect, and a failure/idempotency case. An agent has enough context to decide when to call this tool and what will happen.

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 already describes the 'procedure' parameter as the name passed to mesh_serve, and schema coverage is 100%. The description adds no new parameter-level details, so a baseline score 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 opens with a specific verb and object: 'Stop serving a procedure registered by mesh_serve.' It clearly identifies the resource and how it relates to the sibling tool mesh_serve, leaving no ambiguity about what the tool does.

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 defines the exact condition for use ('procedure registered by mesh_serve') and explicitly covers the edge case where the procedure was never registered, stating it is a no-op. This gives the agent clear guidance on when to invoke it and what to expect.

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, the description carries the behavioral burden and does substantial work: it names the file, notes the env-var path override, clarifies that the standing contact_policy mode is not changed, and defines unlisted-peer behavior as a no-op rather than an error. It stops short of describing return values or persistence 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 main action is front-loaded, but the middle sentence about not changing contact_policy is convoluted ('Never changes contact_policy itself either way...') and could confuse an agent. The no-op and path details are useful, but the explanation is longer than necessary.

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 single-parameter mutation with no annotations and no output schema, the description provides enough to call it correctly: target file, path override, no-op semantics, and what is intentionally not changed. The only notable omission is what the tool returns on success.

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% and the node_id schema description already explains source options (mesh_agents, allowlist, petnames) and the current-roster caveat. The tool description adds file-path context but no additional parameter semantics 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?

States a specific action ('Remove a peer's node_id') and a specific resource (this operator's contact-policy allowlist file), and names mesh_trust_agent as the operation that added it, distinguishing this tool from its trust counterpart.

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?

Clearly frames this as the inverse of mesh_trust_agent and specifies the no-op case for unlisted peers. It does not explicitly state 'use mesh_trust_agent to trust' or list exclusions, but the context makes the intended call scenario 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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It does well in some areas: it explains blocking semantics, maximum wait time, scope of rings (not just unanswered ones), and the relationship to the background recording ring (active from presence.start()). However, it lacks detail on the exact return value format (the ring object) and how the 'answer' field is structured. While the description is helpful, it doesn't fully disclose the output shape, so a 3 is appropriate.

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 dense paragraph that front-loads the purpose but then becomes long-winded with extraneous asides about MCP host backgrounding, Claude Code, and turn-management philosophy. This could have been split into clear sections or trimmed significantly. It is not concise and the structure hampers readability, though the first sentence is 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?

Given the tool's moderate complexity (one simple parameter, no output schema), the description covers the key behaviors: blocking semantics, scope of rings, background recording, and alternatives when to avoid blocking. Without an output schema, it could have specified the returned ring structure, but it implicitly references the 'answer' field lazily, which may be acceptable. Overall, it is nearly complete but has minor gaps on the return format.

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 input schema already has 100% coverage with a description for wait_seconds: 'How long to wait (max 3600).' The tool's description adds context about the max value but not significantly more than the schema. The description does imply the parameter's role in blocking duration, but that's already clear from the schema. Thus, with high schema coverage, a baseline of 3 is maintained.

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 'Block for up to wait_seconds (max 3600) for the next incoming ring', specifying a precise verb ('block'), resource ('incoming ring'), and limits. It also explicitly contrasts with 'polling mesh_read_inbox', which differentiates it from a close sibling. The distinction is clear without needing to inspect schemas.

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 provides explicit guidance on when to use this tool: it is the passive counterpart to polling mesh_read_inbox, covers all incoming rings (open/closed/allowlist resolve immediately, 'ask' leaves one pending), and the agent is instructed to check the returned ring's answer field. It also gives strong when-not-to-use guidance by advising against sleep-then-check loops and recommending the harness scheduler via mesh://etiquette instead. This is rich, actionable usage context.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It does this by disclosing the underlying background tap, noting the call reads an existing feed rather than opening anything new, the behavior under an MCP host that backgrounds slow calls (turning into push), and the turn-blocking limitation—the agent's own turn remains occupied for the duration. It also transparently explains that the server cannot hand off a fresh turn to an idle client, which is critical for the agent to avoid misuse.

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 with required behavior, and it is front-loaded with the core behavior before a thoughtful set of caveats and alternatives. It is longer than average, but nearly every sentence adds a necessary distinction or answer a potential mis-call: it justifies why this isn't the same as saying something, explains the background tap, notes the harness workaround, and disallows a common wrong loop. A couple of clauses (like 'for free' at the end) could be trimmed, but overall the length mirrors the tool's real complexity.

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 blocking tool with no annotations and not output schema, this is conspicuously complete. It covers what happens, how long, the first-from-someone semantic, turn ownership, and how it interacts with an MCP host's backgrounding behavior, and it points to mesh://etiquette for fringe scheduling choices. The missing return-value explanation is not necessary for a blocking wait; the envelope's subsequent consumption is covered indirectly by naming reading alternatives. An agent calling this has all the knowledge it needs to avoid hangs and misrouting.

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 baseline is 3. The description still adds real semantic value beyond the schema: it clarifies that room_topic accepts 'agents.lobby' as a central room, says the room will be joined if not already present, and makes explicit that this is the 'first envelope from someone else' (excluding self-writes). It does not go deep on host, but the schema covers the host's default, and the added context about the watcher feeding the wait is useful for understanding parameter behavior.

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, resource, and scope: it blocks for up to wait_seconds waiting for the first envelope from someone else on a room the caller already belongs to, while requiring no outbound message first. It explicitly contrasts itself with mesh_say's wait_reply_seconds and identifies itself as the passive counterpart, making sibling differentiation crisp. Even without opening schemas, an agent can tell exactly when to choose this tool over mesh_say, mesh_read_inbox, or the harness scheduler.

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?

This section gives explicit when-to-use context: use it when you have nothing to say yet and are just waiting for an answer, objective, or reply. It also names the alternative paths the caller should consider instead (harness scheduler, mesh_read_inbox, manual sleep-and-check), and it clearly says never to use a sleep-then-check loop — a one-shot full wait is the correct usage. These are concrete, actionable rules with exclusions.

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 were provided, so the description carries the full burden. It clearly discloses the blocking nature ('This call BLOCKS for the full duration (or until count events arrive)'), the lack of background subscription ('there is no standing/background subscription to poll later'), the host default, and the lifecycle guidance (call again to keep watching). These are critical behaviors for an agent to know before invoking the tool.

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 short sentences each earn their place: first defines the core action, second explains blocking semantics and third routing, and third handles a common edge case (presence heartbeats). No filler, and the most important behavioral detail is front-loaded.

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 tool is complex due to its blocking nature and early-exit conditions, and the description covers those well. There is no output schema, and the description only says 'return whatever arrived', which is somewhat vague about the exact shape of the returned data. Still, the openness reinforces it's a watch/listen operation, and with the codec/domain context from the MCP tool family, it is adequately complete for an agent to understand basic flow.

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 baseline is 3. The description does add some behavioral nuance to parameters (e.g., that duration_seconds sets the max blocking window and count allows early exit, and that host has a default), but most of this is already present in the schema. It is useful but not redundant.

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 (watch a mesh topic for inbound facts), and explicitly distinguishes the tool by clarifying there is no standing subscription, with an alternative provided ('watch ... instead of polling mesh_agents'). This clearly separates 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?

It provides a concrete when-to-use statement (blocking watch of a topic) and gives an explicit exclusions: 'Presence blogs are ordinary facts on agent.hello/agent.goodbye -- watch those directly ... instead of polling mesh_agents.' While it doesn't cover when to use versus every sibling, it does offer enough routing for a key alternative.

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