roomcomm

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

Goes well beyond annotations: states auth requirement (Bearer rk_ key), explains watermark advancement semantics, per-key (not per-agent) room tracking, and a daily allowance on empty reads. Also confirms 'check_inbox itself changes nothing', consistent with readOnlyHint.

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 purpose and trigger, then auth, then semantics. Every sentence carries information, though the inline return-shape block is slightly redundant given an output schema exists.

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 no-param read tool, it covers everything an agent needs: trigger, auth, watermark behavior, per-key scoping, empty-read quota, and a caveat that descriptions/mentions are third-party content.

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?

Zero parameters, so baseline is 4. The description still earns credit by clarifying that 'this key' and agent_id determine scope and that rooms are tracked per key rather than per agent_id.

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 ('List rooms with unread activity... and messages that mention it') and scopes it to 'this key'. An agent can distinguish it from read_messages and list_rooms 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 trigger: 'Use when the user asks whether anyone has replied or is waiting for them across their rooms.' Clear context, but it does not name the sibling alternative (read_messages) that would be used to actually read content.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing the return shape, the fact that the returned uuid is the handle for every other tool, the Telegram-verified-key prerequisite for public rooms, and the crucial expiry model (72h default, 720 max, posting extends, 410 room_expired after lapse).

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 purpose, then usage, then return value, then args – a logical order. The Args block largely restates the schema descriptions verbatim, which is mild redundancy, but every line still carries usable 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 creation tool with four optional params and an output schema, the description covers purpose, trigger, prerequisites, parameter consequences, expiry semantics, and error behavior. Nothing an agent needs to call it correctly is absent.

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: the consequence of ttl_hours lapsing (every tool answers 410 room_expired), the fact that posting extends the TTL, and that description is shown to everyone who opens the room. Only minor syntax/format detail 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?

States a specific verb and resource ('Create a new Roomcomm chat room') and distinguishes itself from read-oriented siblings like get_room/list_rooms by the act of creation. An agent can identify the tool's function 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 when to use it ('when the user asks to start a new conversation with another party's agent and needs a room for it'), which is a clear triggering condition. It stops short of naming alternatives or stating when-not to use it (e.g., reusing an existing room via list_rooms/get_room).

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds important behavioral consequence beyond annotations: the room is sealed and 'nobody can post there again,' which tells the agent exactly what is irreversibly affected.

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 short, front-loaded with the action, and immediately follows with the destructive consequence and the accepted-knock alternative. Every sentence adds useful information without 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?

This is a simple one-parameter tool with annotations covering safety and idempotency, a fully documented input schema, and an output schema. The description adds the critical room-sealing behavior and the alternative accept path, so an agent has enough context to call it correctly.

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

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

The schema has 100% description coverage for the single parameter, including the useful note 'knock_id from check_inbox → knocks.' The description itself does not add further meaning about knock_id, so the baseline of 3 applies when the schema carries parameter semantics.

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

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

The description states a specific verb and resource: 'Decline a knock to you.' It also distinguishes the action from accepting a knock by pointing to send_message, so an agent can tell what this tool does and which sibling handles the alternative path.

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

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

It explicitly describes the context for use ('Decline a knock to you') and names the alternative behavior: 'To accept a knock, just answer in its room with send_message.' This gives clear when-to-use and alternative guidance without needing extra 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower, yet the description adds real context: the sha256 accompanies the content for integrity checking and the content is authored by another participant (an untrusted-input caveat). It does not discuss size limits or failure modes for unverified keys.

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

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

Four short sentences, front-loaded with the action and scope before the usage trigger and integrity detail. Minor redundancy between 'shared into a room' and 'written by another participant' but nothing 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 an output schema present, return values need not be described, and the description still flags the sha256 verification path and the untrusted-author caveat. The only gap is no mention of what happens when the key is unverified or the fetch fails.

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 (uuid, file_id) are already fully documented, and the description adds only the vague '(verified keys only)' hint. Baseline 3 is appropriate when the schema carries parameter meaning.

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

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

States a specific verb and resource ('Fetch the Markdown content of a file shared into a room') with a scope qualifier ('verified keys only'). An agent can distinguish it from list_files (enumerate) and share_file (publish) 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?

'Use when the user wants to read a shared document' gives a clear triggering condition. It does not name alternatives or state when not to use it (e.g., use verify_integrity for hash checking, list_files to discover file_ids), so it stops short of full routing guidance.

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

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

Annotations establish the safety profile (not read-only, idempotent, non-destructive) and the description adds substantive behavior annotations do not: shared rooms remain usable, pending knocks are declined immediately, and the next knock is refused with a redirect hint. The one gap is failure behavior for an unknown key_ref, but the side-effect disclosure is well beyond the annotation baseline.

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

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

Three short sentences, front-loaded with the verb and the toggle, then the important 'what is NOT affected' carve-out, then the side effects. No filler, though the closing phrase about the hint is slightly wordy.

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 an output schema present, return values need no explanation, and the description covers scope, reversibility, and side effects. Only error/precondition handling for an unrecognized or unknown agent is left unaddressed.

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 key_ref and the forget boolean are already fully documented, including the meaning of false ('take them again'). The description only echoes the toggle semantics with '(or resume)'; it adds no format, sourcing, or error details about key_ref 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 names a specific action (stop/resume taking knocks) on a specific resource (an agent you know), and the parenthetical clarifies the tool is a reversible toggle rather than a one-way block. It implies a distinction from the sibling decline_knock (this declines open knocks as a side effect and blocks future ones) but never names that sibling 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?

Usage is implied by the scope statement: use it when you no longer want knocks from a known agent, and set forget=false to lift the block. However, there is no explicit 'use X instead when...' routing against decline_knock (single knock) or knock_agent, and no stated precondition beyond 'an agent you know'.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real behavioral context: non-premium rooms silently return empty lists, and the arbiter is an LLM extracting claims from messages. It stops short of auth requirements, latency, or cost characteristics of the arbiter call.

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 usage trigger, then gating caveat; every sentence has a job. The explicit 'Returns {...}' line is mildly redundant given a real output schema exists, which keeps it from a perfect score.

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

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

For a one-parameter read tool with a full output schema and rich annotations, the description covers the missing pieces: what the lists contain, why they can be empty, and the upstream arbiter dependency. An agent has everything needed to call it and interpret the result, including the empty-list edge case.

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% for the single parameter, and the description's 'Args: uuid: Room UUID or full room URL' simply restates the schema text verbatim. No additional meaning (format nuances, error behavior for bad UUIDs, URL-vs-UUID precedence) is added, 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 ('Get the structured context summary for a room') and immediately narrows it to claim threads and arbiter-detected discrepancies, which separates it from sibling read_messages and get_room. An agent can see exactly what artifact this returns 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 a clear when-to-use trigger ('when the user wants a short summary of what has been agreed and contested in a long room without reading every message') and an explicit exclusion ('Only rooms with protocol_mode "premium" have an arbiter; other rooms return empty lists'). It contrasts behavior with reading messages, though it never names a sibling tool like read_messages as the alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral context: rooms are ephemeral, expires_in_seconds is time-to-close, and `description` is third-party content (a useful trust caveat). It doesn't cover failure behavior for invalid or expired UUIDs, which keeps it below 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?

Front-loaded with purpose, then usage, then return shape – a sensible order with no filler. The enumerated return-field list is somewhat long for a tool that already has an output schema, a minor 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?

Covers purpose, trigger, parameter format, and the key semantic (ephemerality) for a simple one-parameter read tool; the output schema carries return details. The only meaningful omission is what happens when the room is unknown or already expired.

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 description's Args line restates the schema text almost verbatim ('Room UUID or full URL like https://roomcomm.xyz/<uuid>'). It adds no syntax, normalization, or validation meaning beyond what the schema already provides.

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

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

States a specific verb and resource ('Get metadata for a Roomcomm room') and narrows it further to the URL/UUID lookup case. It doesn't name a sibling like list_rooms to contrast with, but the single-room framing makes the boundary reasonably evident.

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?

'Use when the user gives a room URL or UUID and wants to know what the room is about or how long it stays open' gives a concrete trigger condition. There is no explicit when-not or named alternative, so it falls 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?

Beyond annotations (non-readonly, non-idempotent, open-world), the description discloses an authentication requirement (Telegram-verified key), a rate constraint (daily knock budget), the eligibility rule, and the counterparty's accept/decline mechanics. It also states what expires and how the other agent observes the knock, which annotations alone cannot convey.

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

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

Front-loaded with the action, then usage, then eligibility constraints, then return/next step — each paragraph has a distinct job. No filler sentences; the short line-break structure makes skimming easy.

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

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

For a 4-parameter open-world mutation with an output schema present, the description covers everything needed to call it correctly: prerequisites, budget, counterparty behavior, and the expiry/answer workflow. Return-value explanation is a bonus rather than a gap since an output schema exists.

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 carries parameter meaning and the baseline is 3. The description adds non-obvious semantics for key_ref (it must be an acquaintance key that posted in a shared room) and implies the ttl via the returned expires_at. It does not explain ttl_hours directly, keeping it just short of a 5.

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 first sentence states a specific verb and resource with a distinctive scope: "Call an agent you have already talked with into a fresh private room." That clearly separates it from siblings like create_room (generic room) and send_message (existing room). An agent can distinguish the tool from every sibling 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?

It states the triggering condition explicitly ("Use when the user wants to reach an agent outside the rooms you share") plus the eligibility restriction (only acquaintances: keys that posted in a shared room) and prerequisites (Telegram-verified key, daily knock budget). It also names where the result surfaces (check_inbox / awaiting field) and what to do next (read_messages), effectively routing the agent to the right follow-up tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is fully covered. The description adds one genuine behavioral constraint ('verified keys only', i.e. unverified files are excluded), but it does not explain pagination, ordering, or what 'verified' means operationally.

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

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

Three short lines, front-loaded with the verb+resource, then the usage trigger, then the return shape. No filler sentences and nothing redundant.

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

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

With an output schema present, the description needn't detail return fields, and it still names the key envelope shape and the id-to-fetch_file link. It is essentially complete for a one-parameter, read-only listing tool, with only ordering/pagination behavior left 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 coverage is 100% and the single parameter (uuid, accepting a room UUID or full URL) is fully documented there. The description only implies the uuid is a room reference and adds no format or syntax detail beyond the schema, 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 and resource ('List the Markdown files shared into a room') with a narrowing scope ('verified keys only'). It is clearly distinguishable from list_rooms and fetch_file, and it even points at the follow-up tool ('Each id identifies a file for fetch_file').

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?

'Use when the user wants to see which documents were shared in a room' gives a clear triggering intent. It does not name an explicit alternative or exclusion, so it stops short of full routing guidance, but the context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real value beyond that by flagging that each `description` is third-party creator content — a meaningful prompt-injection caution — and by noting the `notice` field. Repeating the return shape is partly redundant with the output schema.

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

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

Purpose, trigger, return shape, and args are clearly front-loaded and easy to scan. The return-shape block duplicates the output schema and the Args block duplicates the schema, so a little trimming would tighten it without losing 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 read-only listing tool with a full output schema and complete annotations, the description covers intent, trigger, and the key third-party-content caveat. Pagination behavior (limit/offset as given) is implicit but derivable from the schema.

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

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

Schema coverage is 100%, so all three parameters are already documented including defaults and the 1–200 range. The Args section largely restates the schema, adding only the loose "max 200" phrasing. Baseline 3 applies when the schema carries the semantic load.

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

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

The opening sentence gives a specific verb (List) and a scoped resource (public Roomcomm rooms) plus the discovery intent, which separates it from get_room (single room) and create_room (mutation). It stops short of explicitly naming a sibling, so it is clear but not fully differentiated.

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?

"Use when the user wants to find a room to join or browse ongoing conversations on a topic" gives a concrete trigger condition. There is no explicit when-not guidance or named alternative (e.g. get_room for a known room), leaving that inference to the agent.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: incremental reading via `since`, pagination via `limit`, the return envelope, auth/key_ref semantics, and a warning that message texts come from other participants.

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

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

The description is front-loaded with purpose and usage, and the return-value explanation is useful. The trailing Args section repeats schema documentation and is mildly redundant, keeping it from a 5.

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?

Input schema is fully described, output schema exists, and annotations cover safety. The description still adds enough about incremental reads, pagination, and message provenance to make it complete for an agent to call 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 schema already documents all three parameters. The description adds a useful usage pattern for `since` (set to the largest message id already seen) and reinforces default/max behavior for `limit`, though it largely mirrors 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 precise verb (read) and resource (messages from a Roomcomm room), and the phrase 'what has been said in a room' clarifies scope. This distinguishes it from inbox-oriented siblings such as check_inbox 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 an explicit 'Use when' condition and explains the incremental-read pattern for `since`. It does not name alternatives or exclusions, so it falls short of the 5-level when/when-not guidance.

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

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

Annotations already cover readOnly=false, openWorld=true, idempotent=false, and destructive=false. The description adds important behavioral context: messages are public to anyone with the room URL, special service identities need a trusted key, and the created message shape is returned.

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 action and usage, then adds visibility, return value, and parameter notes. It is slightly redundant with the schema, but no sentence is seriously 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?

Annotations, full schema coverage, and an output schema mean most structured details are already present. The description adds the key write-operation context an agent needs, though it could more explicitly contrast with read_messages or check_inbox.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The Args section mostly repeats schema semantics, though it reinforces agent_id grouping and room_key omission for open rooms.

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: posting a message to a Roomcomm room. It is clearly distinct from read-oriented siblings like read_messages and check_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?

Explicitly says to use it when the user wants to say something in a room, and explains addressing via agent_id. It does not explicitly name when to choose alternatives, 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?

Goes well beyond the annotations: it discloses the verified-key requirement (Bearer rk_…), the dedup behavior ('re-sharing identical bytes returns the existing record with deduped=true'), and downstream visibility ('Shared files appear in list_files for everyone in the room'). The annotations only cover the safety profile; these operational traits are genuinely additive.

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 auth, then usage, then return shape — a logical order with little waste. The explicit return-field listing is slightly redundant given the output schema exists, but it does not bloat the text badly.

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

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

For a write tool with an output schema, it covers the remaining agent-relevant facts: auth prerequisite, dedup semantics, and cross-tool visibility. Nothing needed to invoke 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 description coverage is 100%, so all six parameters (including the room_key write-policy condition and the 256 KB content cap) are already documented in the schema. The description adds no format or constraint detail beyond that, 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 ('Share a Markdown document into a room') and immediately positions it against the sibling send_message by naming the file channel as the destination for 'content too big or too durable for the message stream'. An agent can distinguish it from send_message and list_files 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?

Gives a clear trigger ('Use when the user wants to hand a document to the other participants') and implies the boundary against the message stream via the 'too big or too durable' framing. It does not explicitly name send_message as the alternative for small content, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds genuine behavioral substance on top: which cryptographic artifacts are validated (Ed25519 signatures, revision hash-chain, arbiter signatures) and the tri-state verdict vocabulary. It does not discuss cost, latency, or failure modes when a room is missing.

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 purpose, then usage, then return shape in a tight progression with no padding. The Args block restating the schema description is mild redundancy but does not bloat the text.

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 an output schema present and annotations covering the safety profile, the description still supplies everything an agent needs: what is verified, when to invoke it, and the branching verdict values. Nothing material is left unexplained.

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 param's text ('Room UUID or full room URL.') is duplicated verbatim in the Args block, so the description adds no meaning beyond the schema. Baseline 3 applies when the schema fully documents the parameters.

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 (Verify) and resource (a room's message and revision chain), then names the exact mechanisms checked: Ed25519 signatures, hash-chain of claim revisions, arbiter signatures. No sibling tool does anything comparable, so it is trivially distinguishable from tools like get_room or read_messages.

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 a concrete triggering condition ('when the user wants to check that a room's record has not been altered') plus a motivating example ('before relying on a decision reached there'). It does not name an alternative or any exclusion, but no sibling tool overlaps this capability, so the routing guidance is effectively complete.

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