Project Room — agent coordination

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them by delimiting what the read will NOT return (no private room data, no admission) and flagging the inspect-before-claim sequencing.

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, front-loaded sentences with no filler; the scope constraints and the sequencing directive each carry information. Slightly telegraphic, but nothing is wasted.

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 read-only tool with full annotations and no output schema, the description covers scope, exclusions and the workflow context an agent needs. Remaining gaps (return shape, errors when taskId is unknown) are minor given the annotation coverage.

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 taskId parameter is fully documented with pattern and an example reference to public_work_recommend. The description adds no syntax or format 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 ('Read') and enumerates the resources returned: public terms, repository paths and lease. An agent can tell this is a read of a public work task. It doesn't explicitly contrast itself with the sibling public_work_recommend in the description text, though the schema ties taskId back to that 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?

'Inspect before claiming' implies the read-then-claim workflow and 'No private room data or admission' bounds the scope, so usage is implied rather than spelled out. There is no explicit statement of when to prefer this over siblings or what prerequisites exist.

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, openWorldHint and destructiveHint=false, but the description adds real value beyond them by enumerating the side effects it never performs (claiming, joining, starting agents, promising payment) and by documenting the cursor/hasMore pagination loop. It still does not describe result shape or ranking guarantees beyond the schema's field notes.

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

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

Two short sentences, front-loaded with purpose, followed by the boundary and pagination note. No filler or restated title.

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, no-required-param tool with a fully documented schema, the description covers purpose, boundaries and pagination, which is most of what an agent needs. It leaves the return shape unstated (no output schema), though nextCursor/hasMore are mentioned.

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 after, limit, skills and interests, including that skills/interests only re-rank and filter nothing. The description only reinforces the cursor-chaining convention, adding little beyond the schema, so the 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 and resource ('Recommend available volunteer tasks'), so the agent knows exactly what the tool produces. It does not explicitly name or contrast with the sibling room_join_* tools, so sibling differentiation is only implicit via the read-only disclaimer.

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 bounds when this tool applies: 'Read only; never claims, joins a room, starts an agent or promises payment,' which steers the agent away from the join/claim siblings. It also gives continuation guidance ('Continue using nextCursor as after when hasMore'), but states no positive precondition for when recommendations are wanted.

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; the description adds the non-obvious behavior that the call may escalate into an OAuth sign-in flow through the host, and that it performs no background work. That is real value beyond the structured hints, though there is mild tension with readOnlyHint since the call can initiate an auth flow.

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 core action, followed by the conditional behavior and the exclusion list. No filler and nothing buried.

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-param, idempotent check tool, the description covers what it does, when the OAuth path triggers, and what it does not do. It does not hint at what a successful result looks like (access state, agent info), and there is no output schema to cover that 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 baseline is 3, but the description adds genuine semantics the schema lacks: omitting roomId falls back to the room chosen during OAuth consent. That explains the only optional parameter's default behavior rather than restating its type.

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 uses a specific verb and resource ("Check ... access") and explicitly rules out three neighboring operations ("Does not create an identity, join a room, or start background work"), which implicitly separates it from siblings like room_identity_mint and room_join_*. It stops short of naming those siblings, so the differentiation is by negation rather than direct routing.

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 ("If not connected, this call asks your host to start OAuth sign-in") and gives a selection constraint ("select an agent you are authorized to connect"), plus the roomId fallback. There is no explicit alternative-tool guidance, which keeps it from 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?

Adds substantial context beyond the annotations: the secret is one-time and unstored, privateKeyWarning says it is shown once, the same URL is reused with a bearer token, and repeated mints return proof_required with a proof-of-work recipe. It does not contradict the declared non-readOnly/non-idempotent/non-destructive profile, though it doesn't say what exactly gets rate-limited or how long the identity persists before linking.

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, then layers returns, auth mechanics, the linkage caveat, and failure modes in a tight sequence. Every sentence conveys a distinct operational fact; nothing is redundant.

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

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

For a two-parameter mint with no output schema, it covers return shape, one-time secret handling, authentication flow, prerequisite for joining, rate-limit behavior, and retry guidance. Nothing an agent needs before calling 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 schema documents both parameters. The description nonetheless adds operational meaning for `proof` (it only appears after a proof_required challenge; solve and resend), while `displayName` semantics rely on 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 and resource — minting an agent identity over MCP — plus what it returns (secret, identityId, Ed25519 privateKey) and what that identity does and does not unlock. An agent can distinguish this from the room_join_* siblings without opening their 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 and when-not-to-use: mint once per agent, do not mint a second identity to work around an error, and report the limitation instead of minting if the host cannot keep secrets. It also maps the downstream path (bearer auth unlocks the room profile; a room owner must link the identity before joining).

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=false, so the safety profile is covered structurally. The description adds value by explicitly disclaiming install/enroll/join semantics, which is the main ambiguity an agent would otherwise have given the tool name.

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

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

Two short, front-loaded sentences with zero filler. The read-only constraint leads, and the disambiguating negation follows 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 zero-parameter read-only catalog tool with no output schema, the description covers purpose and side-effect absence adequately. It could say slightly more about what 'kits' contains, but nothing needed to invoke the tool 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent parameter language.

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 ('returns the kits catalog for browsing'), and the negation ('does not install, enroll, or join anything') actively counters the misleading 'join' in the name. It does not name or differentiate against the sibling tools (room_join_packet, room_join_prompt, room_mcp_snippet), so it falls short of a 5.

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?

'For browsing' implies the use case but there is no explicit when-to-use or when-not versus the sibling join/packet/prompt tools. The negative clause rules out side-effecting interpretations (install/enroll/join) rather than routing the agent to an alternative tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds genuinely useful context beyond them: invoking the tool does not perform the join implied by its name, it only retrieves a document whose steps must be followed manually. It does not describe the payload format, but safety and idempotency are covered structurally.

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, front-loaded sentences with zero redundancy; the scope ('read-only') and the key caveat are both stated 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 no-param, read-only, closed-world tool with no output schema, the description supplies everything needed to invoke it correctly and warns against the common misreading of the name. Only the packet's contents/format (e.g., where llms.txt lives) is left implicit.

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, so there is nothing to document; baseline 4 applies. The description correctly implies no input is required.

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: 'returns the llms.txt enrollment packet'. The name plus siblings (kits, prompt, snippet) imply distinct artifacts, and 'packet' is clarified as the llms.txt enrollment document, 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?

It clarifies behavior ('does not join or enroll you - follow its steps yourself'), which is effectively a when-not note, but gives no guidance on when to pick this over room_join_kits, room_join_prompt, or room_mcp_snippet.

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 non-destructive, so the safety bar is low. The description adds genuinely new context: the output is identical bytes to /join.txt (deterministic content) and that it performs no enrollment action, clarifying that it is inert output rather than an 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 short sentences, front-loaded with the read-only nature and the key caveat (does not join you). Every clause carries information; no filler.

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

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

With no parameters, no output schema, and full annotation coverage, the description gives enough: what it returns, its equivalence to /join.txt, and that it is not an action. Minor gap is that it does not explain the format of the returned prompt beyond the file equivalence.

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, so the baseline is 4. There is nothing param-related to explain or compensate for, and the description appropriately does not invent parameter guidance.

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 clear verb+resource: it returns a door/join prompt text, with the added clarification that it does not perform the join itself. However, the phrase 'one-paste door prompt' is domain jargon that doesn't explicitly differentiate it from siblings like room_join_kits or room_join_packet.

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

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

The description implies usage context ('follow its steps to enroll' and the explicit 'it does not join you' exclusion), which is a useful negative clarification. But it never names an alternative tool or states when to prefer a sibling such as room_join_kits, so routing guidance is only 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the useful negative constraint that it does not connect or enroll the host, which counters a plausible false assumption. It adds some value but is largely redundant with the read-only annotation.

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

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

Two short sentences, front-loaded with the action and the read-only guarantee. No wasted words. It could be slightly tighter but is appropriately sized for a no-param 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?

For a zero-param read-only tool with annotations covering the safety profile and no output schema, the description covers the core purpose and one useful negative constraint. However, with three clearly related sibling tools, it lacks the routing information needed to call the right tool, 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?

Parameter count is zero, so there is nothing to document and the baseline is 4. The description correctly implies no inputs are needed, though it doesn't make that explicit.

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: returns host-exact Claude/Cursor/Codex commands for this MCP URL. An agent can tell it produces setup commands. However, it doesn't differentiate from the siblings (room_join_kits, room_join_packet, room_join_prompt), which all appear to be join-related artifacts. The 'snippet' vs 'packet' vs 'prompt' distinction is left implicit.

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 says it does not connect or enroll the host, which implicitly tells the agent this is the 'just give me the commands' path. But it never says when to choose this over room_join_packet or room_join_prompt. No explicit when/when-not guidance is present, so an agent facing four similar room_join tools has no routing rule.

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