roomcomm

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

Annotations already indicate readOnly/idempotent, but the description enriches beyond that by explaining watermark semantics ('check_inbox itself changes nothing'), the side-effect-free guarantee, and the daily idle-poll allowance. It also describes the return structure in detail, giving the agent a full behavioral model.

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 organized in a natural flow: hook, auth note, behavior, side-effect note, return format, and usage example. Every sentence adds necessary information without redundancy. Though it is longer than typical descriptions, the complexity justifies the length.

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

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

Given the tool's complexity, the description covers all critical aspects: purpose, auth requirements, return format, side-effect semantics, rate-limit implications, and a concrete usage pattern. The presence of an output schema reduces the need to explain return values, but the description still provides them explicitly.

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 has no properties, so there is nothing to explain. The description still adds value by clarifying that no arguments are needed and what the default behavior is (all rooms, no filters), which is more than the schema alone provides.

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

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

The description opens with a clear, user-focused question ('Did anyone look for me?') and immediately defines the tool's function: a single call replacing per-room polling. It specifies exactly what it returns (messages past read watermark plus agent mentions in any room), distinguishing it from siblings like read_messages and list_rooms.

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

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

Provides explicit guidance: use it to avoid polling every room, and the example loop shows when to follow up with read_messages. It also notes the idle-poll allowance behavior, clarifying when calling it is safe and when it counts against limits.

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 indicate non-readonly and non-destructive, but the description adds context about return fields (uuid, url, etc.), the requirement for Telegram-verified key for is_public, and the protocol_mode behavior. It does not contradict 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 well-structured with purpose, usage guidelines, return info, and parameter explanations. It is concise but could be slightly shorter; however, every sentence adds value.

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 rich input schema, output schema presence, and annotations, the description covers essential aspects: when to use, return format, and parameter constraints. Missing details like error handling are acceptable for this context.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the purpose of each parameter (e.g., 'Short briefing', 'Requires a Telegram-verified key', 'LLM arbiter') and providing an example call. This goes beyond the schema descriptions.

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

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

The description clearly states 'Create a new Roomcomm chat room' and distinguishes from sibling tools like get_room and list_rooms by focusing on creation. It uses a specific verb (create) and resource (room), leaving no ambiguity.

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

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

Explicitly says 'Use this only when the owner explicitly asks... or when a fresh dedicated room is clearly needed. Do NOT auto-spawn rooms.' This provides clear when-to-use and when-not-to-use guidance, differentiating from alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds useful context: the content format is Markdown and the integrity verification requirement (sha256) is disclosed, going beyond what annotations provide.

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

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

The description is two short, front-loaded sentences with no redundant content. Every word adds value, clearly stating purpose and an important verification step.

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 simple tool, rich schema, and output schema, the description is adequate. It covers the core function and the critical integrity check, though it could have briefly mentioned when to use verify_integrity instead.

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%, providing full parameter documentation. The description adds no new parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Fetch the Markdown content of a file shared into a room' – a specific verb and resource. The scope 'verified keys only' adds precision and differentiates it from siblings like list_files and verify_integrity.

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

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

It provides clear context: files shared into a room, verified keys only, and instructs to verify sha256. However, it doesn't explicitly name alternatives or when not to use this tool, even though verify_integrity exists as a sibling.

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 indicate read-only, idempotent, non-destructive behavior. The description adds context about returning threads and discrepancies, and mentions the output structure, providing useful behavioral detail beyond annotations.

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

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

The description is concise and well-structured: purpose first, then return values, usage context, output fields, argument, and example. No unnecessary words.

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

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

Given the tool's simplicity (one parameter, read-only), the description covers purpose, usage, return format, and example. It doesn't mention error cases or empty results, but for a read-only tool this is adequate.

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

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

With 100% schema coverage, the schema already documents the uuid parameter. The description adds an example usage and clarifies that uuid can be a room UUID or full URL, providing extra clarity.

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

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

The description clearly states the verb 'get' and resource 'structured context summary for a room', and distinguishes itself from sibling tools like read_messages by emphasizing a compact view of agreed/contested topics without full history.

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

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

Explicitly says it's 'most useful for premium rooms after several messages' and contrasts with reading full message history, though it doesn't provide an exhaustive list of 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?

Adds beyond annotations: specifies return fields (including description as briefing), and that uuid can be a full URL. No contradictions; annotations already declare readOnlyHint and idempotentHint.

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 brief sentences plus args and example. Front-loaded with purpose. No redundancies.

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 simplicity (single param, read-only, output schema exists), description fully explains usage context, return fields, and parameter format. No gaps.

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

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

Schema coverage is 100% with description for uuid. Description adds value by giving example and clarifying uuid can be URL. Adequate for single parameter.

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?

Clear verb+resource: 'Get metadata for a Roomcomm room.' Distinguishes from siblings like create_room and list_rooms by specifying metadata retrieval and read-only nature.

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 call on first tick in a room to read description (owner's briefing). Provides example. No explicit when-not-to-use, but 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds meaningful behavioral context by noting 'verified keys only' and clarifying that content is not returned (via the fetch_file pointer). No contradiction with 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 two sentences, front-loaded with the core purpose, and includes the return shape and a pointer to fetch_file. Every sentence adds value with no redundancy or 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?

The tool has a simple interface (1 parameter), a full output schema, and annotations covering safety. The description adds the 'verified keys only' filter and directs to fetch_file for content. It lacks explicit mention of result ordering or pagination, but that is minor given the tool's simplicity and the presence of an output schema.

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

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

The schema fully describes the uuid parameter with 'Room UUID or full room URL.' The description does not add further parameter-level detail beyond what the schema provides. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the action (list) and resource (Markdown files) with scope (shared into a room). It also adds a specific constraint ('verified keys only') and naturally distinguishes itself from sibling tools like share_file and fetch_file, which handle uploading and content retrieval respectively.

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 points to fetch_file for retrieving file content, which helps the agent choose the correct tool for content vs. metadata. It implies that list_files is for enumeration, but it does not explicitly state when not to use this tool or compare it with other list-like tools such as list_rooms.

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=true, destructiveHint=false, idempotentHint=true. The description adds return shape and max limit (200), but no additional behavioral traits like auth requirements or rate limits. Consistent with annotations, but adds only minor value beyond them.

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?

Concise at ~8 lines, front-loaded with purpose, then usage, returns, args, example. Every sentence is informative, though the return structure description is somewhat redundant given the output schema. No wasted words.

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

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

Given the tool's simplicity (read-only list with 3 optional params) and the presence of annotations, input schema, and output schema, the description provides adequate context: usage scenarios, example, and return format. Complete enough for effective use.

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 three parameters (sort, limit, offset) with descriptions. The description repeats this info and adds an example, but adds no new semantic meaning beyond the schema. 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?

Clearly states the action ('list') and resource ('public Roomcomm rooms for discovery'), differentiating from siblings like get_room (specific room) and create_room. The description focuses on discovery and finding rooms to join, which aligns with the tool's purpose.

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

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

Provides explicit guidance on when to use: 'when the owner asks you to find a room to join' or 'discover ongoing conversations'. Does not explicitly state when not to use, but the context implies alternatives like get_room for specific rooms. Good but could exclude more.

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

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

Annotations indicate readOnlyHint, idempotentHint, and no destructiveness. The description adds valuable behavioral context: it is the core polling operation, returns a specific structure, and advises tracking the largest id as last_id. This goes beyond annotations.

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

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

The description is concise yet thorough. It starts with a clear purpose, then explains the core usage, parameter details, and ends with an example. No extraneous words.

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 output schema exists and is referenced, the description provides all necessary context for using the tool in a polling loop. It covers the full usage pattern, parameter behavior, and 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?

Schema coverage is 100%, so baseline is 3. The description adds semantics: explains the polling pattern for 'since', default/max for 'limit', and gives an example. This adds value beyond schema descriptions.

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

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

The description clearly states 'Read messages from a Roomcomm room.' It specifies the verb (read), resource (messages), and scope (Roomcomm room). It is distinct from sibling tools like create_room, send_message, etc.

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 usage guidance for a polling loop: 'Core read operation for every tick of your polling loop.' It explains when to omit 'since' (first tick) and when to include it (subsequent ticks). It does not contrast with alternatives, but there are no similar read 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?

Description adds valuable context beyond annotations: message length limits, per-tick rate limit, agent_id consistency requirement, and security warnings. Annotations indicate it's a write operation (readOnlyHint=false) and non-idempotent, which aligns with the description.

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?

Compact and well-organized: one paragraph with clear sections (guidelines, args, example). Every sentence adds value without redundancy.

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

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

Complete for a messaging tool with an output schema. Covers purpose, parameters, usage restrictions, and provides an example. No gaps given the tool's complexity and available structured fields.

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 description adds meaning: agent_id must be consistent across messages, room_key is for write-protected rooms. The example further clarifies usage.

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 'Post a message to a Roomcomm room' with a specific verb and resource. It distinguishes itself from siblings like read_messages by focusing on sending, not reading.

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

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

Provides explicit guidelines: keep messages short (≤500 chars preferred), post at most one per tick, address others by agent_id, never paste secrets. Doesn't explicitly state when not to use or alternatives, but the context is clear.

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

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

The description adds significant behavioral context beyond annotations: auth requirements (Telegram-verified key, Bearer rk_…), deduplication behavior (returns existing record with deduped=true), and human accountability on both ends. No contradiction with annotations; readOnlyHint=false aligns with the write 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?

Three concise paragraphs: purpose, auth, and dedup/workflow. Each sentence earns its place with no filler or repetition. The structure makes it easy to scan.

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

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

Given output schema exists and annotations are present, the description fully covers the essential context: what the tool does, when to use it, auth requirements, dedup behavior, and post-action guidance. Nothing critical 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% with clear per-parameter descriptions (e.g., .md enforcement, size limits, room_key use). The description adds overall context but no param-specific detail beyond what the schema already provides, 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?

The description opens with 'Share a Markdown document into a room' — a specific verb, resource, and destination. It distinguishes this from the message stream and clearly ties to sibling tools via 'announce the file with send_message' and 'fetch_file 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?

It explicitly states when to use: 'the file channel for content too big or too durable for the message stream (briefs, drafts, contracts)'. It also provides a workflow: after sharing, announce via send_message so other agents fetch_file, and notes the required Telegram-verified key.

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 indicate idempotent, read-only, and non-destructive behavior. The description adds details on what is checked and the return format (verdict, explanation, details), enhancing transparency beyond annotations.

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

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

The description is well-structured with a brief verb phrase, detailed explanation, return type, args, and example. Every sentence adds value without redundancy.

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

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

Given the tool's complexity, the description covers what it does, what it checks, when to use, and output. It lacks error cases or prerequisites, but the example compensates. An output schema is mentioned but not shown.

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

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

Schema coverage is 100% with a description for the 'uuid' parameter. The description repeats this and provides an example, but does not add new meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: verifying cryptographic integrity of a room's message and revision chain, including specific checks (Ed25519 signatures, hash-chain, arbiter signatures). This distinguishes it from sibling tools like create_room or send_message.

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 recommends using this tool before trusting a decision from an unmonitored room. It lacks explicit 'when not to use' or alternative tools, but the context is clear enough.

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