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

With no annotations, the description carries the full behavioral burden and does well: it discloses persistence across restarts, the 15-minute prune window, most-recently-seen sort order, and the meaning of stale and presence_dropped. The dense, partly garbled final sentence about discarded events weakens it, but the core behavioral traits are unusually well 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?

The purpose is front-loaded and the tool's scope is stated early, which is good. But the second half is a dense run-on, and the trailing passage about discarded events is grammatically tangled and hard to parse, hurting 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?

There is no output schema, so the description must explain return values. It attempts this via stale and presence_dropped explanations, but the final sentence conflates fields and reads as broken text, leaving the actual response shape only partially 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 description never mentions the page/page_size pagination parameters. Schema coverage is only 50% (only 'page' has a description string), but the schema itself supplies defaults and a 100 max for page_size, so the agent is not left guessing values. 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 (list) and resource (agents) and adds a precise scope mechanism: agents seen via agent.hello heartbeats. This distinguishes it from send-side siblings like mesh_hello and inbox readers like mesh_read_inbox.

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 clarifies the data source ('reads a persistent local SQLite roster, not a live mesh query') and notes pruning behavior, which helps an agent judge freshness. However, it never states when to prefer this over alternatives (e.g., mesh_find_records, mesh_read_inbox) or any preconditions; guidance is implied at best.

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 and does most of it: accept joins the room and notifies the caller, the answer is delivered as a proven call to the caller's ring endpoint, and the caller_notified=0 fallback is disclosed along with the guarantee that the answer is still recorded. It stops short of stating auth/permission requirements or any rate limits, so it is strong but not exhaustive.

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-loads the core action and the pointer to rings.pending, then handles accept, decline, delivery, and the deferral exclusion in a few tight clauses. Slightly dense and parenthetical-heavy, but every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must explain what happens on completion, and it does: room join, caller notification, delivery semantics, and the caller_notified=0 edge case. Only permission/prerequisite details are absent, which is a minor gap for this operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: what accepting actually causes (you join the room first, caller is then told) and that the decline reason is visible to the caller. The accept/decline semantics themselves are already in the schema, so the gain is incremental rather than full.

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 (answer) and resource (a ring deferred to you), and immediately distinguishes it from the sibling mesh_ring by framing rings as items listed under rings.pending in mesh_read_inbox. An agent can tell this apart from mesh_wait_ring and mesh_ring without opening another 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 explicit when-to-use (after seeing a pending ring in mesh_read_inbox), what each answer value commits you to, and an exclusion: 'Deferring again is not an answer; leave it pending instead.' It also routes the agent to mesh_say as the natural follow-up after an accept, which is a genuine alternative-selection cue.

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 does so unusually well: it discloses identity exposure to the provider, the sealing model (preferred/required, reseal-on-failure), specific failure codes (confidentiality, sealed_refused), replay semantics of the ownership proof, and the return shape. Nothing material about how a call behaves is left to inference.

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 core purpose is front-loaded in the first clause and every subsequent sentence carries concrete information (bytes encoding, sealing, ownership proof, the caller prohibition). It is dense and undivided into sections, which makes it heavy to scan, but there is little 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 complex, security-sensitive RPC tool with no annotations and no output schema, the description covers invocation, encoding, security posture, error codes, and the return payload (result, duration_ms, seal, provider, means). Nothing an agent needs to call it correctly appears to be 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?

Schema coverage is 100%, so the schema already documents all six parameters (baseline 3). The description adds real value on top: the {"$bytes": ...} wire encoding convention, the prohibition on passing "caller" in args, and the once-and-only-for-these-args semantics of prove_ownership.

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 (invoke) and resource (a procedure advertised on the mesh), with concrete examples of what those procedures do (build, test, search, deploy). It is readily distinguishable from siblings like mesh_put/mesh_get (DHT storage ops), which is what makes the RPC nature clear without opening any 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?

The description gives conditional guidance for one parameter (confidential preferred vs required) and implies the discovery path by pointing to mesh_find_records_by_type in the realm parameter, but it never explicitly frames when to choose mesh_call over alternatives like mesh_put/mesh_get or mesh_publish. Usage is inferable 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 burden and does reasonably well: it enumerates the returned fields (type, signer/key_id, times, payload, decoded procedure advertisement), which substitutes for the absent output schema, and discloses the not-found behavior ('found: false when the stations hold none'). It omits any mention of side effects, permissions, or whether the lookup touches network stations beyond the implication of 'stations'.

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?

A single front-loaded sentence with no filler; the colon cleanly scopes what is returned. Slightly dense in the middle enumeration, but every clause adds information.

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-param read tool with no annotations and no output schema, the description compensates by describing the return payload and the not-found case. What remains missing — permissions and any station/network side effects — is minor for a lookup operation.

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% and the schema already documents the 64-char hex format, the example sources, and the key_id disambiguation note. The description repeats '32-byte storage key' without adding format or syntax meaning beyond the schema, so the baseline 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 verb and resource with explicit scope: 'Fetch one verified DHT record by its 32-byte storage key'. The singular 'one' and the key-based lookup implicitly distinguish it from the plural siblings mesh_find_records and mesh_find_records_by_type, though no sibling is named explicitly.

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 example 'a procedure's key, or a key already seen in a mesh_find_records_by_type result' usefully routes the agent to a sibling for obtaining input, but there is no explicit when-to-use vs when-to-use-an-alternative statement (e.g. look up by type vs by known key). 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. It usefully discloses a non-obvious behavior: it returns verified records AND a count of ones that failed to verify, implying a filtering/verification step. But it omits whether this hits the network (latency), permission needs, or whether it is a pure read, leaving meaningful behavioral gaps.

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?

A single, front-loaded sentence that opens with the verb and resource. The parenthetical example earns its place by clarifying a non-obvious scope, and 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?

No output schema and no annotations, so the description must carry more. It partially compensates by describing the return (records plus a non-verified count), and 'Fetch' implies a read, but it leaves return format and whether it is a network-bound read unspecified.

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%; the schema already fully documents key_hex, including the crucial warning that it is NOT the record's signer key_id. The description adds nothing parameter-specific beyond the schema's baseline, so 3 is the correct baseline.

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: 'Fetch EVERY verified record stored at a DHT key', and the parenthetical example (all procedure_advertisements from different providers) makes the intent concrete. The word 'EVERY' implies scope contrasting with the singular sibling mesh_find_record, but the sibling is never named outright.

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 example use case ('every procedure_advertisement one procedure has from different providers') implies when to reach for this over mesh_find_record, but no explicit when/when-not or alternative is stated. The agent must infer the distinction from the singular vs. plural sibling names.

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 carries the full burden. It adds real value by stating records are "verified" and that coverage reflects only what the linked stations' DHT holds rather than a census, which is an important completeness caveat. It is silent on pagination, result limits, ordering, and auth requirements, leaving genuine behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core purpose and the three-sentence structure earns its place (purpose, example, caveat). The em-dash aside is slightly dense but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description handles the essentials: it defines the resource, gives a worked example of the returned fields for one type, and warns about coverage limits. It falls short of explaining return shape for other record types or result volume, but is largely complete for a discovery query.

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 goes beyond the schema by explaining what a specific record_type value yields (realm, procedure, advertiser, serving station). It doesn't explain what the other record types return, but it adds concrete semantic value over the enum listing.

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 (List) and resource (verified DHT records of one type), scopes it to what the stations hold, and frames itself as "the discovery entry point," which distinguishes it from siblings like mesh_find_record and mesh_find_records. An agent can identify the tool's role 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?

Calling itself "the discovery entry point" and giving a concrete example (pass "procedure_advertisement" to enumerate capabilities) makes the intended use clear. However, it never explicitly contrasts with the near-identical siblings mesh_find_record / mesh_find_records, so the agent must infer the boundary.

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 does well: it discloses that bytes are verified against the MCID so no sharer is trusted, that the payload is returned as base64, and that code=not_shared signals no current sharer. It omits permission/auth requirements and any timeout or size limits.

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 tightly packed sentences, front-loaded with the action and resource, followed by the trust/return contract and the failure code. 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?

There is no output schema, so the description must explain return values — it does (base64 content, code=not_shared). For a single-parameter read tool this covers what an agent needs to call it and interpret 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% and the single parameter is fully documented (pattern, exact 100-char length). The description's '100 hex characters' and 'as mesh_put returns it' largely restate the schema, adding only a minor cross-tool provenance cue, so the baseline 3 is correct.

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 (Fetch) and resource (content-addressed artifact) plus the key scope constraint (from any node that shares it). It also anchors the input to a sibling ('as mesh_put returns it'), so an agent can distinguish this retrieval tool from the put/find family without reading any 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?

The description makes the usage context clear: fetch an artifact whose MCID you already hold from a prior mesh_put. It does not state when *not* to use it or name any competing alternative explicitly, so it stops short of the top score.

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?

No annotations exist, so the description carries the full burden and does so: it discloses the heartbeat interval and default, the durable subscription and lobby watch that are created, the idempotent-update semantics of repeat calls, the fact that a prior mesh_goodbye is not auto-undone, and that connected_via comes from the MCP handshake rather than a parameter.

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 purpose is front-loaded in the first clause, but the body is one sprawling run-on sentence with stacked em-dashes and parentheses, and it spends significant space listing 17 sibling tool names inline. Dense but overloaded; a shorter structured form would parse better.

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 five optional params, the description is thorough: it explains what gets produced (banner, lobby_topic), which other tools consume its effects (mesh_agents roster, mesh_read_inbox, mesh_lobby_transcript), and how it interacts with mesh_goodbye. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds real value by explaining that operator_name/session_name/message/model default from MACULA_MCP_OPERATOR_NAME/SESSION_NAME/HELLO_MESSAGE/MODEL env vars. It also correctly excludes connected_via as a parameter. Minor inconsistency: the schema claims session_name is 'Not auto-populated' while the description says it can come from an env var.

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 and resource ('Announce this agent's presence on the mesh') and enumerates the concrete side effects: welcome banner, periodic agent.hello heartbeat, durable hello subscription, and a standing lobby/room watch. It clearly distinguishes itself from mesh_goodbye and mesh_unobserve_lobby, so an agent can identify it 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?

Explicitly says you usually don't need to call it because 17 sibling calls auto-start presence, then names the exact conditions that DO warrant a direct call: overriding env-derived fields, seeing the banner/lobby_topic, restarting after mesh_goodbye, or re-confirming a lobby watch disabled by mesh_unobserve_lobby. When-to-use, when-not-to-use, and alternatives are all covered.

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 carries the full behavioral burden and does well: it discloses that joining starts background watching, publishes a participant_joined event, and is idempotent — non-obvious side effects an agent must know. It stops short of describing the immediate return value/timeout behavior, keeping it from 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?

A single dense but well-ordered sentence followed by three terse clauses; the verb+resource is front-loaded and every phrase (idempotent, publishes participant_joined, follow-up tools) 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 one-parameter join tool with no annotations and no output schema, the description covers initiation, side effects, idempotency, and lifecycle handoffs. It omits what the join call itself returns, which is the only meaningful gap.

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 single parameter is already documented as 'The agents.room.<32 hex> topic.' The description adds only that the topic may come from mesh_rooms or out of band, which is useful provenance but not syntax beyond the schema. Baseline 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 verb+resource ('Join a room') and immediately scopes the input by explaining where the room topic comes from. It names siblings (mesh_rooms, mesh_say, mesh_read_inbox, mesh_leave_room) so an agent can place it in the room lifecycle without opening other 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?

Explicitly states when to use it (a topic learned from central or out of band) and routes the agent to the right follow-up tools: mesh_say to talk, mesh_read_inbox to read, mesh_leave_room when done. This is a full when/next-step map, not just implied usage.

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 does well: it discloses the published events, the subscription teardown, and explicitly warns that the `close` flag is advisory ("nothing enforces it"). It omits error behavior (e.g., leaving a room you are not in) and any return shape.

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 action and its effects, and every clause conveys distinct information. The parenthetical about `close` is slightly dense but earns its place by flagging a non-enforced behavior.

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 two-parameter, no-output-schema tool with no annotations, the description covers side effects, the close-flag caveat, and where the transcript remains readable. Remaining gaps (error cases, confirmation of room membership) are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning for `close: 1` by explaining the semantic trigger condition (must be the opening agent) and that enforcement does not exist. That is genuine value beyond the schema's bare "1 to publish room_closed".

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?

Starts with a specific verb+resource ("Leave a room") and immediately names the observable side effects (publishes participant_left, stops watching the topic). It is clearly distinguishable from siblings like mesh_join_room, mesh_open_room, and mesh_unobserve_lobby.

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?

States the key selection condition for the `close` flag ("only means something from the agent that opened it") and routes the agent to mesh_lobby_transcript for viewing the retained transcript. It doesn't spell out when to prefer this over other disengagement tools, but the usage context is clear.

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

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

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?

With no annotations, the description carries the behavioral burden and does disclose a non-obvious two-step execution model: a DHT lookup to auto-discover which realm advertises mcl-stations, then the call. It does not state failure behavior if the service is not advertised in any realm, nor auth/rate-limit characteristics, but 'List' clearly signals a read-only operation.

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 dense sentences, front-loaded with the action and backing service, with filter behavior trailing. Nothing is wasted, though the em-dash clause about hand-maintaining station lists is rationale rather than instruction.

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-required-parameter list tool with full schema coverage, the definition covers what it does, how filtering works, and the auto-discovery mechanism. With no output schema, the return shape (what fields a station record contains) is left unspecified, which is the main remaining gap.

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 city/country/continent exact-match semantics and the near{lat,lng,limit} sorting and cap. The description restates the same filter set and only adds that it mirrors 'the service's own filter API', which is marginal value. Baseline 3 applies when 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?

States a specific verb and resource ('List macula stations') and names the backing service and realm ('mcl-stations/list_stations', 'the mesh's canonical station directory'), so an agent can distinguish it from mesh_list_realms or the generic mesh_find_* siblings without opening any 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?

Explicitly says filters are optional and that omitting them lists every known station, which tells the agent exactly how to select behavior. It lacks an explicit 'use X instead when...' routing statement against siblings like mesh_list_realms, but the context for use 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, the description carries the full burden and does so thoroughly: local SQLite read, never blocks, never makes a mesh round trip, non-retroactive coverage, persistent like mesh_agents' roster. It even documents the `dropped`/`dropped_by_topic` semantics, the 256-event inbox discard behavior, and the macula-mcp 0.35.0 version qualifier — behavioral detail far beyond a mere restatement.

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 and the read-only/local nature before the detail. The final `dropped` explanation is long and dense, but since there is no output schema it earns its place as return-value documentation rather than padding.

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?

No output schema exists, so the description must explain return values — and it does, covering the topic list, the raw transcript, and both `dropped` and `dropped_by_topic`. Combined with the mutation-free/caching behavior and the non-retroactive constraint, nothing an agent needs to call this correctly 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what omitting topic returns (all topics interleaved by arrival time plus the distinct-topic list) and what passing it returns (raw, single conversation). It does not restate the limit parameter, but the schema handles that adequately.

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 ('Read what mesh_observe_lobby has recorded') and immediately scopes it as a local SQLite read. It explicitly positions itself against siblings, calling out mesh_read_inbox as the threaded view and mesh_observe_lobby as the recorder, so an agent can distinguish it without opening a 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 explicit when-to-use branches: omit topic to see all interleaved traffic plus the distinct-topic list, or pass topic to read one conversation raw. It names the alternative tool (mesh_read_inbox) and the condition that selects it ('the rooms you are actually in'), which is exactly the routing guidance an agent needs.

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 delivers: read-only, idempotent (second call only raises the cap), never retroactive, durable local transcript, and the meaning of the reply fields central_dropped/dropped_by_room including the 256-event inbox discard-and-summed-since-0.35.0 detail. This is unusually rich 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?

Dense but front-loaded with the core action and the when-to-use guidance. Every sentence serves a purpose (idempotency, non-retroactivity, sibling routing, return semantics), though the dropped_by_room explanation is lengthy for a secondary detail.

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?

No output schema exists, so the description must explain return values, and it does via central_dropped and dropped_by_room. Combined with the explicit stop/read siblings, idempotency, and non-retroactivity notes, an agent has everything needed to invoke 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?

There is one parameter and schema description coverage is 100%, so the schema already documents max_rooms, its default of 20, and the 'rooms you open or join yourself are never subject to it' caveat. The description reinforces the default and purpose (bound against child processes) but adds little beyond the schema, so the baseline 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?

Names a specific verb and scope: 'Start a standing, read-only watch over central (agents.lobby) and every PUBLIC room announced there', and clarifies it captures all agents' broadcasts, not just this one's. It is clearly distinguished from siblings mesh_hello (auto-starts it) and mesh_unobserve_lobby (stops it).

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 states the default behavior ('mesh_hello already starts this automatically, so you usually don't need to call it') and the two precise triggers for calling it: raising max_rooms above default or restarting after mesh_unobserve_lobby without a full goodbye+hello cycle. Alternative tools for reading and stopping are named.

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 does so richly: it discloses the ~40s worst-case latency for unreachable participants, that rings go out concurrently, that partial success still returns a room, the per-participant outcomes (joined/deferred/declined/unreachable), and the security caveat ('unguessable, not encrypted'). This is the kind of behavioral detail annotations would otherwise need to supply.

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 core action is front-loaded in the first clause, and the em-dash parentheticals keep caveats attached to the relevant statement rather than in a trailing block. It is dense and slightly long, but nearly every clause carries non-redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description is appropriately thorough for a 4-parameter mutation tool: it covers creation, watching, notification semantics, timing expectations, partial-failure behavior, and the security model. An agent knows what will happen and what it gets back before calling.

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 meaning beyond the schema: it explains that participants are 'rung' like mesh_ring with an addressed call to '~<node_id>/ring' and that the return reports who joined/deferred/declined, and that 'public' announces on central. These consequences go past the field-level 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?

Opens with a specific verb and resource ('Open a room') and enumerates the concrete effect: generates an unguessable 'agents.room.<32 hex>' topic, watches it in the background, and publishes the room_opened envelope. It distinguishes itself from siblings by naming mesh_join_room, mesh_ring, and mesh_agents as the related tools, so an agent can route correctly 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?

Gives explicit conditional guidance: pass public:1 to also announce on central so others can mesh_join_room it, and pass participants to actively notify them the same way mesh_ring would. It clarifies the direct-message case (a two-party room) and contrasts with mesh_ring behavior, leaving little 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?

With no annotations, the description carries the full burden and does well: it discloses that facts are signed with the agent's identity, that there is no delivery ack (fire-and-forget), and what is returned (topic and duration_ms). It omits failure behavior, permissions, and any rate/throughput constraints.

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 purpose, then behavior, then return value, then parameter/naming rules. Dense but every sentence carries information; no wasted filler, though the trailing bytes example is packed tightly.

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 annotations and no output schema, the description covers the essentials an agent needs: signing, no-ack semantics, return fields, realm default, and byte encoding. It could go further on error behavior, but is largely complete for a 3-param tool with nested objects.

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 baseline is 3, but the description adds real meaning beyond the schema: the business-verb naming convention for the topic and the {'$bytes': '<base64>'} encoding rule with a concrete example. It clarifies semantics the schema only gestures at.

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 (Publish) and resource (integration fact to a mesh topic) plus the goal ('so other parties' agents can react'). Highly specific, though it does not explicitly differentiate itself from siblings like mesh_say or mesh_put.

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 only guidance is about fact-type naming conventions ('use a business verb... never CRUD'), not about when to choose this tool over mesh_say, mesh_put, or the other mesh_* siblings. No when/when-not or alternative selection criteria are given.

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 does well: bytes stay local, the agent must remain present to serve them, artifacts vanish when the agent leaves, and the return value is the MCID. It also warns that anyone with the MCID can fetch the bytes, a genuine safety disclosure. It stops short of stating auth requirements, size limits (only implied via the schema), or failure 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?

Dense and front-loaded, leading with the action and locality constraint before the return value and privacy warning. The serving/presence idea is restated twice ('serves them to anyone who asks' and 'they are gone when it leaves'), costing some tightness, but 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?

No output schema exists, and the description supplies the missing return semantics (the MCID) plus lifecycle and privacy behavior, which is what an agent needs to call this correctly. Edge cases such as duplicate content, overwrite behavior, or error conditions remain unstated.

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 both parameters are already documented, establishing a baseline of 3. The description adds MCID format (100 hex characters) and its downstream use, which is useful output context rather than parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (share) and resource (content-addressed artifact), plus the scope 'from THIS agent' and the serving model, which separates it from mesh_get (fetching elsewhere), mesh_serve, and mesh_publish without needing to open any 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?

Explicitly routes the agent: 'Returns the MCID for mesh_get elsewhere,' naming the complementary tool and the condition that selects it. It gives clear context for when this tool is right but does not contrast against close siblings like mesh_publish or mesh_serve.

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 and succeeds: it states the operation is instant, a local SQLite read, and never blocks. It also explains ring ordering, the dependency on mesh_answer_ring, room transcript recording boundaries, and the precise meaning of dropped and central_dropped.

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 but front-loaded with the core purpose, then layers necessary behavioral detail. The dropped explanation is dense but earns its place given the absence of an output schema, though the parenthetical style could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with no output schema and no annotations, the description is complete: it explains returned sections, ordering, blocking behavior, transcript limitations, and dropped-event counters. An agent has enough context to call it correctly and interpret 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 description coverage is 100%, so the schema already documents both parameters. The description adds some practical meaning for room_topic ('read one room only') but does not mention limit or otherwise extend 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?

The description opens with a specific verb and resource: reading the inbox contents that have arrived. It enumerates the exact content types returned (rings, rooms, threaded messages, help broadcasts), making the tool's scope distinct from generic read or room-listing siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies usage by describing what arrives and notes that passing room_topic reads one room only. However, it does not explicitly compare this tool to alternatives such as mesh_recall, mesh_rooms, or mesh_lobby_transcript, nor does it state when not to use it.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses auto-discovery of mcl-rag's advertised realm, the underlying answer_query call, the return shape (chunks with similarity score, source_path, chunk metadata), and that empty results are not an error. That is exactly the behavioral context an agent needs.

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 action and qualifier ('semantic retrieval, not keyword match'), then builds out behavior. It is longer than most definitions, but nearly every sentence adds distinct value (realm discovery, return shape, empty result meaning, invocation timing).

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?

No output schema exists, yet the return values are described in-detail, and empty-result semantics plus the auto-discovery mechanism are covered. Nothing an agent needs to call this correctly 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?

Schema coverage is 100%, so both query_text and top_k are already documented by the schema. The description adds useful framing of query_text as a semantic query rather than a keyword string, but adds nothing for top_k, so the baseline 3 holds.

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 (Query) and resource (mesh's shared memory / mcl-rag RAG service), and sharpens it by contrasting semantic retrieval against keyword match. It names mesh_remember as the deposit counterpart, letting an agent place it against siblings without opening any 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?

Explicitly says 'Not automatic -- call this deliberately when you actually want to check shared memory' and gives a concrete trigger ('early in a session working on a repo others may have touched'). This supplies the when-to-use and the deliberate-invocation condition rather than leaving it 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 provided, so the description carries the full burden and does so well: shared-not-private scope, no payload encryption, cross-session/any-agent visibility via mesh_recall, and the guarantee that short deposits won't silently produce zero chunks. These are exactly the behavioral traits an agent needs before writing to a persistent shared store.

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 action and its consequence, and each sentence adds a distinct piece of information. It is on the long side and restates the privacy caveat twice (shared/no-encryption and 'what others can read'), which is some 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 3-param write tool with no output schema, the description covers scope, persistence, retrieval path, and safety caveats completely enough to call it correctly. It stops short of describing failure modes or confirmation behavior, which would be the remaining gap.

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 topics, content and source_label are already documented in the schema. The description adds no extra constraint or format detail about the parameters themselves, so the baseline 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?

Opens with a specific verb+resource ('Deposit ... into the mesh's shared memory (mcl-rag)') and immediately names the retrieval counterpart mesh_recall, so an agent can distinguish write from read without opening any schema. It also states the underlying RPC (add_knowledge), grounding the purpose concretely.

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 context: designed for short conversational snippets rather than raw document ingestion, and warns to be deliberate because the store is shared. It does not explicitly rule out or route to the sibling mesh_remember_directory, which keeps it 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?

No annotations are provided, so the description carries the full burden, and it delivers: deterministic document_id derivation makes reruns idempotent, binary/undecodable files are skipped rather than erroring, and processing is sequential (with an explicit warning that large directories are slow). It also clarifies the response shape is a summary with counts and per-file failures, not a 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?

Dense but front-loaded: the verb, target, and per-file call model come first, then the sibling contrast, then behavioral caveats. Length is justified by the amount of non-obvious behavior disclosed, though the parenthetical-heavy single paragraph is slightly harder to scan than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must cover safety, side effects, failure modes, and returns -- and it does all four: mutation of shared memory, idempotency via derived IDs, skip-not-error on binaries, and a summary-shaped response. Nothing an agent needs to call this correctly 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all four parameters. The description adds genuine value on top by explaining how file relative paths (modified by source_prefix) become each document's document_id, which is the semantic that makes reruns update rather than duplicate.

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+scope: recursively ingest every matching file under a LOCAL directory into mcl-rag shared memory, one upload_knowledge call per file. It explicitly contrasts itself with mesh_remember and with mcl-rag's own seed_corpus, so an agent can distinguish it from siblings without opening a 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?

Explicit routing: 'for real documents (a corpus, a set of notes), not conversational snippets (use mesh_remember for those)'. It also rules out the alternative mechanism an agent might wrongly assume (seed_corpus reading mcl-rag's own filesystem, which it notes isn't reachable over the mesh).

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 does so: it enumerates all four outcomes (accepted, declined with reason, deferred under an 'ask' policy, unreachable), notes every answer is signed, and explains the join-wait/dropped semantics including the 256-event inbox limit. That is far beyond what structured fields supply.

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?

It is a single dense paragraph with the core action and the 'only way' rule front-loaded, and nearly every clause carries semantics. It is somewhat overloaded with nested parentheticals about inbox limits and dropped counters, which costs a little 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?

There is no output schema, so the description must cover return values — and it does, spelling out the answer codes, unreachable, joined, and dropped. For a complex multi-outcome tool, nothing an agent needs to interpret the reply 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: purpose is mandatory and used to judge deferred rings, room_topic omitting opens a fresh two-party room, and wait_join_seconds exists so that joined:1 means a genuinely two-sided room. This goes past the schema's own text.

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 precise verb+resource ('Ring another agent: an addressed invite delivered as a mesh_call to their ~<node_id>/ring') and pins down the mechanism, target, and payload (a room). It is clearly distinguishable from siblings like mesh_call, mesh_hello, and mesh_answer_ring.

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 an explicit routing rule — 'This is the ONLY way to reach an agent that has not invited you' — plus a hard prohibition ('never write into a room they have not joined') and names the follow-up path (mesh_answer_ring carries a deferred answer back). When-to-use and when-not are both 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 does so well: it declares the operation is instant, local, and non-blocking, and it explains the `dropped`/`central_dropped` counters in depth (256-event inbox, newest discarded, summed since 0.35.0). It does not cover any auth or freshness caveats beyond the counter semantics, 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?

The opening sentence is a long run-on that bundles three separate result categories together, and the trailing `dropped` explanation is verbose. The material is useful and front-loaded, but it would read far better as a short list of what is returned followed by the counter note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe return contents itself, and it does: participants seen, fact counts, per-room `dropped`, and central's `central_dropped`. Combined with the zero-parameter schema, an agent has what it needs, though it lacks any hint of ordering, sizing, or limits on the returned list.

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 takes zero parameters, which is the baseline-4 case; the schema has nothing to document and the description correctly spends no words on inputs, devoting its space to return semantics instead.

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 the resource precisely and enumerates three distinct things it returns: rooms this agent is in, unjoined public rooms announced on central, and rings awaiting a callee's model. That is enough for an agent to distinguish it from mesh_open_room/mesh_join_room, but no explicit verb anchors it and no sibling is named.

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?

There is no statement of when to call this versus alternatives such as mesh_lobby_transcript, mesh_agents, or mesh_read_inbox. 'Instant, a local read, never blocks' describes behavior rather than selection criteria, so the agent is left to infer the triggering 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?

No annotations are provided, so the description carries the full behavioral burden and does so: it discloses that PUBLISH has no send ack and that a ring is what provides one, that it auto-joins a room you are not in, that the background watch is already running before the message goes out (eliminating the publish-then-watch gap), and the exact semantics of the `dropped` counter including the 256-event inbox limit.

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 content is information-dense and front-loaded with the core action, but it is delivered as one sprawling paragraph with heavy parenthetical nesting, making it hard to scan. It is not padded, yet the lack of structure (e.g. per-kind bullets) costs it on 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?

With no annotations and no output schema, the description compensates fully: it explains mutation side effects (auto-join), the asynchronous acknowledgement model, the wait-and-reply behavior, and the meaning of the returned `dropped` field. An agent has everything needed to invoke it correctly and interpret the response.

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 beyond the schema: it explains the default kind, the reply-expectation contract for each kind, the in_reply_to requirement per kind, and what `dropped` and wait_reply_seconds actually do on the wire. It stops just short of a 5 because a couple of parameters (e.g. refs usage limits) are left to 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 verb (say/broadcast) and resource (conversation envelope on a room topic or agents.lobby), and enumerates the exact envelope fields produced. It distinguishes itself from siblings by noting lifecycle kinds are published by the room tools, not here, so an agent can identify the tool's niche without opening other 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?

Gives explicit when-to-use guidance per kind (question_asked expects answer_given, task_handed_over expects result_reported, lane_claimed expects lane_released), which replies MUST carry in_reply_to, that lane_claimed itself does not need it, and that on central it is for help_requested/help_offered broadcasts rather than conversation. Alternatives and exclusions are named, not implied.

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 does it well: it discloses the standing-surface lifecycle (until mesh_unserve or process exit), the stdin/stdout and byte-encoding contract, and the MACULA_MCP_CALLER/MACULA_MCP_SEALED env semantics. It does not spell out failure/error modes for the command itself, but the security and lifecycle disclosure is strong.

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 and the standing-surface warning before the byte/env details. Every sentence earns its place, though the KEM/version detail is dense enough to slightly tax 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?

For a registration/mutation tool with no annotations and no output schema, the description covers lifecycle, security posture, reply channel, and teardown. An agent has everything needed to decide and invoke 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 the baseline is 3, but the description adds runtime meaning: it ties the exec contract to the caller's JSON payload and sealed/advertise wiring, and reinforces the name-namespace and confidentiality behavior beyond the raw field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Serve a procedure on the mesh, answered by a local shell command run once per inbound call') with the exact invocation contract. It is clearly distinguishable from mesh_unserve (which stops serving) and from the read/write 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?

Explicitly frames this as a standing inbound surface rather than a one-shot action, warns against registering commands a stranger could run repeatedly, and names mesh_unserve as the way to stop. The when-to-use and when-to-be-careful conditions are both 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 does so richly: it names the file written, the policy side effect (ask -> allowlist, closed/open left as-is), that the reply reports which happened, and that changes take effect immediately with no restart. It also flags the mutation's asymmetry so the caller is not surprised.

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 action and effect, then constraints; every clause carries distinct information (side effect, identity rationale, immediacy). Somewhat long for a single-parameter tool, but not padded.

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 one-param mutation with no annotations and no output schema, it discloses the file touched, the policy mutation behavior, the return hint, and immediacy. Nothing needed to call it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: node_id is the only verified signed identity, and operator_name/session_name/petname are unsafe as a trust boundary. That rationale goes well beyond the schema's list of value sources.

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 (add a peer's node_id to the operator's contact-policy allowlist) and its concrete effect (next ring auto-accepted, no ask round-trip). It is clearly distinguished from siblings mesh_untrust_agent and mesh_answer_ring.

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 says when to call it: '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.' The trigger conditions are concrete and tied to sibling workflows.

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, the description carries the full behavioral burden, and it does disclose idempotency ('No-op if it was never registered') — a genuinely useful trait. However it says nothing about permissions/authorization, whether in-flight calls or existing registrations are affected, or what happens on name mismatch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the core action front-loaded and the edge case (never registered) following immediately.

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 one-parameter teardown tool with no output schema, the description covers the action, the parameter binding, and the idempotent edge case, which is most of what an agent needs. It leaves permission/error behavior unstated, a minor gap given the tool's simplicity.

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% and the single parameter is fully documented as 'The name passed to mesh_serve.' The description's 'by the name it was given' restates that same binding rather than adding new format or casing rules, so baseline 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 verb (stop serving) and a specific resource (a procedure registered by mesh_serve), and ties the resource back to the sibling tool that creates it. An agent can distinguish this from mesh_serve and the other mesh_* tools without opening any 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?

Frames the tool as the undo counterpart of mesh_serve, so the trigger condition (a procedure you previously served) is clear, and it adds the no-op condition for a procedure that was never registered. It stops short of explicit 'when not to use' or naming alternative teardown paths.

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?

No annotations are provided, so the description carries the full burden and does so richly: it discloses that the room is already watched via presence's standing tap, that this reads the same feed rather than opening anything new, that it occupies the agent's own turn with no server-side handoff to an idle client, and that the reply carries `dropped` with the full 256-event inbox discard semantics.

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 behavior and scoping constraint before the deeper mechanics. It is dense and occasionally meandering (host-notification aside, drop-counter paragraph) and repeats the 3600 max already in the schema, but nearly every sentence adds usable guidance for a complex 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?

With no annotations and no output schema, the description compensates fully by explaining turn occupancy, timeout-vs-silence semantics, and the meaning of the `dropped` return field. An agent has everything needed to call it correctly and interpret 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 both parameters are already documented, including the 3600 max which the description restates verbatim. The description adds marginal meaning (room may be central / agents.lobby, joins-if-absent), but the schema already carries most of it, so the baseline 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 precise verb+resource+scope: block up to wait_seconds for the first envelope from someone else on a room you are already in (or central). It explicitly distinguishes itself from siblings, calling itself 'the passive counterpart to mesh_say's wait_reply_seconds' and naming mesh_read_inbox as an alternative pattern.

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 explicit when-to-use (when you have nothing to say yet and are waiting on an objective, answer, or reply), when-not-to (never in a sleep-then-check loop), and alternatives (use the harness scheduler instead of manual sleep plus re-calling this or mesh_read_inbox). Routing 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, the description carries the full burden and does so: blocking-for-full-duration behavior, early stop at count, no persisted subscription, base64 encoding for byte payloads, and precise meaning of the `dropped` field (inbox capacity 256, newest discarded, 0 vs null). This is unusually rich behavioral disclosure for a tool with zero annotation coverage.

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 action and its blocking trait, and nearly every sentence earns its place. The closing `dropped` sentence is dense and slightly long, but it conveys non-obvious return semantics rather than padding.

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?

No output schema exists, so the description must describe return values itself, and it does: arrived events with verified publishers, plus the `dropped` counter with its 0/null distinction. For a blocking watch tool with no annotations, nothing essential to correct invocation appears 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?

Schema coverage is 100%, so per-parameter meaning is already documented. The description still adds value by clarifying the interaction between duration_seconds and count ('blocks for the full duration or until count events arrive, whichever is first') and reaffirming the realm default, going slightly beyond the schema's per-field text.

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 (watch) on a specific resource (mesh topic) and describes the exact return: inbound facts up to duration_seconds, each with verified publisher. The blocking semantics and lack of standing subscription distinguish it from mesh_read_inbox and mesh_agents without opening a 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?

Explicitly says this call BLOCKS and there is no standing subscription to poll later, telling the agent it must call again to keep watching. It also names a concrete alternative path ('watch agent.hello/agent.goodbye directly instead of polling mesh_agents'), which is exactly the when/when-not guidance the dimension asks for.

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