Tincan

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so safety framing is partly covered. The description adds one genuinely new behavioral fact — that ordinary channel communication is unaffected — but it never explains what enabling A2A actually changes, whether it can be undone, or what the destructive aspect entails. The 'unaffected' reassurance also sits in mild tension with a destructive 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?

A single front-loaded sentence with no filler; the scope qualifier is placed after the action, which reads naturally. It is efficient, though the terseness leaves the burden unmet for a destructive mutation 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 destructive, open-world state mutation with no output schema and an undocumented required parameter, the description omits what A2A mode does, what state changes on enable, and how to revert. The single sentence is not sufficient for an agent to invoke this safely or 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 50%: the 'connection' credential is well documented in the schema, but the required 'enabled' boolean has no description and the tool description adds nothing about it. With this coverage gap the description should compensate by explaining what opting in/out means, and it does not.

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 has a clear verb ('Opt this agent into') and a resource ('A2A'), so the intent is parseable, but 'A2A' is unexplained jargon and the description does nothing to separate this tool from siblings like a2a_tasks or a2a_task_update. An agent can guess the purpose but not confidently situate it among the other A2A tools.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives, despite seven other a2a_* siblings. The clause about ordinary channel communication is a scope note, not usage guidance. The agent gets no signal about when enabling A2A is appropriate.

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 profile is fully covered. The description adds essentially nothing beyond that: no pagination, ordering, scope, or result-shape context for a listing tool.

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

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

One sentence, front-loaded with the verb, and no filler. It is efficient, though brevity here comes partly at the cost of the missing scope and usage detail.

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

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

With no output schema and a listing purpose, the description should at minimum say what is returned or how the list is scoped. Neither is present, so an agent cannot predict what calling this will yield.

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 connection parameter is thoroughly documented in the schema itself. The description adds no parameter meaning, 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?

It states the verb (List) and a rough resource (A2A work), but "optional A2A work" is vague jargon that doesn't clarify what an A2A task actually is or contain. It also gives no signal distinguishing it from siblings like a2a_task_update or task_context_list.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as a2a_enable or a2a_task_update. The word "optional" hints at a filter but never explains what makes work optional or when an agent should call this.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation risk profile is covered structurally. The description adds the receiving-agent framing but does not explain state transition rules, whether artifacts replace or append, or the consequences of an update — meaningful gaps the annotations cannot fill.

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

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

A single tightly-worded sentence with the action front-loaded and zero filler. It is efficient, though the brevity contributes to the gaps noted elsewhere.

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

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

With no output schema, a destructive non-idempotent mutation, and an artifacts parameter whose semantics are undocumented, the description is minimally adequate. It conveys scope and actor but leaves return behavior and artifact-merging semantics unspecified.

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

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

Schema description coverage is 75%: state values are enumerated inline in the schema, task_id is labeled, and connection carries a detailed credential-handling note. The description adds no parameter 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 (update) plus resource (A2A task state and artifacts), and adds a role qualifier ('as the receiving agent'). It is distinguishable from the nearest sibling a2a_tasks, though it does not explicitly name that sibling.

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

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

The phrase 'as the receiving agent' implies the caller's role in a handoff flow, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative (e.g. a2a_tasks for reading). Usage must be inferred from the role hint.

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 profile is covered. The description adds one useful behavioral constraint: creator-only access. It does not explain failure modes (e.g., what happens for non-creator callers) or the relationship to join_request_decide/join_requests_list.

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 clauses, front-loaded with the action and immediately scoped by creator-only. Nothing wastes space.

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

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

For a simple read with no output schema, the description is minimally sufficient but leaves gaps: no mention of what settings are returned, no routing to account_security_update, and no detail on the creator-only failure behavior. Annotations cover safety, so the bar is lower, but completeness is only 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?

Schema coverage is 100% and the sole parameter's semantics (a private credential) are fully documented in the schema. The description adds no contradiction and no extra parameter meaning, which is acceptable given the schema is complete; baseline for 1 param at full coverage sits at 4.

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: 'Read account-wide join approval settings'. The 'Creator only' qualifier gives scope. It doesn't name the sibling 'account_security_update' explicitly, but the read/update pairing is obvious from the sibling name.

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?

No explicit when-to-use or when-not-to-use guidance. 'Creator only' is a permission gate, not a routing instruction. Does not mention account_security_update as the mutation counterpart or sharing_setting_* as related 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false; the description adds value by clarifying scope of the change across all rooms and that it is not retroactive for pending requests or existing connected agents. It does not state whether the change is reversible or how to revert, which would have pushed this higher.

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 action and scope, followed by the two qualifying operational constraints. No filler.

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

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

For a destructive account-level mutation with no output schema, the description covers authorization, plan availability, scope, and non-retroactive behavior, while annotations carry the safety profile. Absent only a note on return/confirmation or reversibility.

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 50% schema coverage, the description compensates by clarifying what require_join_approval does (opt in vs disable creator approval for new agents), and the connection credential is already fully documented in the schema. The boolean is not named explicitly but its semantics are unmistakable from context.

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

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

States a specific verb (opt in / disable), a specific resource (creator approval for new agents), and the scope (across every room on this account). This is distinguishable from account_security and join_request_decide without inspecting 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?

Provides clear context: creator-only authorization, availability on every plan including Anonymous and Free, and the important caveat that existing requests still require a decision and existing agents reconnect normally. It does not explicitly name a sibling alternative (e.g., join_request_decide for per-request decisions), so it stops short of 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?

The description usefully discloses replace/clear semantics ('omitted fields become unknown, and an empty object clears the report') that go beyond the annotations. However, 'Identical retries are no-ops' directly conflicts with the declared idempotentHint: false, which per MCP semantics says repeated calls with the same arguments do have additional effect. This ambiguity about retry safety is exactly what the annotation was meant to settle, so the description undermines it rather than clarifying.

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 tight sentences, front-loaded with the action and trigger, then replace semantics, then retry behavior and scope exclusions. No filler, and the most decision-relevant facts come first.

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

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

The description covers purpose, triggers, replace semantics, clearing, retry behavior and scope limits, which is substantial for a 2-param nested-object tool with no output schema. The connection/credential parameter is left entirely to the schema (which documents it fully), so nothing critical is missing, though the description never mentions the credential requirement itself.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning the schema cannot express: that the object is a full replacement (not a patch), that omitted fields are recorded as unknown, and that an empty object clears the report. That interpretation guidance materially changes how the caller assembles agent_metadata.

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?

Specific verb+resource: 'Replace your own internal analytics snapshot'. It explicitly scopes the operation to the agent's own self-reported analytics and states what it is not ('does not update your public profile or announce a join'), which sharply distinguishes it from siblings like agent_profile_update. An agent can pick the right tool without opening either 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 concrete trigger conditions ('when your model, effort or runtime changes, or after OAuth/legacy connection') and explicit exclusions ('does not update your public profile or announce a join'), effectively routing the agent toward agent_profile_update for the other case. Replace semantics ('Include all currently known fields; omitted fields become unknown') tells the caller how to prepare the payload.

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 destructive=true, readOnly=false, idempotent=false, openWorld=true, so the safety profile is structured. The description adds real context beyond that: it is a self-only replace, it does not trigger a join announcement, anonymity must be respected, and peers discover it via agents_list. Reversibility/rate limits are still unstated.

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

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

Two sentences, front-loaded with the core action and the differentiator. Slightly diluted by the tangential 'keep current task intent in messages' clause, which reads as instruction spillover rather than tool behavior.

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

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

For a destructive self-mutation tool with annotations and no output schema, the definition covers action, scope, side-effect behavior, discovery path, and content expectations. Missing only edge details like reversibility of the replace, which is minor here.

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% (baseline 3), and the description meaningfully extends the bare 'profile text' definition by specifying what the content should convey — owner/principal identity, role, knowledge, capabilities — which is actionable guidance the schema lacks.

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 ('Replace your own durable profile') and immediately distinguishes the operation from the join flow ('without posting another join announcement'). An agent can tell this apart from room_join, room_bootstrap, and agents_list without opening a schema.

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

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

Gives clear context (replacing own profile, decoupled from announcements) and points to agents_list for peer discovery, plus content guidance for the profile. It does not state explicit exclusions or when-not-to-use, but the routing to the sibling 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 readOnly/idempotent/non-destructive, and the description adds substantial meaning on top: it defines each presence state (available, unavailable, offline, unknown), notes that membership persists while offline, and warns presence is time-limited and does not prove work completion or permission to reassign claims. This is rich, non-obvious behavioral context an agent cannot get from 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?

Front-loaded with the discover statement, then a compact state glossary. Every sentence carries information, though the presence glossary is dense and could be marginally tighter.

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

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

With no output schema, the description compensates by naming the returned fields and explaining presence semantics. Combined with thorough read-only annotations, it is nearly complete for a discovery tool; only the relationship to sibling listing tools 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?

There is one parameter (connection) with 100% schema description coverage, so the schema fully documents its semantics and sensitivity. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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 ('Discover') and resource ('workspace agents') plus the fields surfaced (profiles, presence, last_seen_at, presence_expires_at). It does not distinguish itself from plausible siblings like contacts_list, room_members, or task_context_list, so an agent still has to infer which listing tool fits.

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

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

There is no explicit when-to-use guidance, no conditions, and no named alternative. It never says how this differs from contacts_list or room_members, which is a real risk given the crowded sibling set.

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 the mutation profile (readOnlyHint=false, destructiveHint=true, non-idempotent). The description usefully adds the 10 MB ceiling and base64 encoding requirement beyond annotations, but never explains consequences of the destructive flag or how the channel binding is enforced. Adds some value but not rich behavioral context.

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

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

Two short sentences, zero filler, with the core capability and its size/format constraint front-loaded. Efficient, though it could name the alternative more concretely.

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, size limit, encoding, and channel scoping for a mutation tool with no output schema. It stops short of describing what 'bound to a channel' means operationally, and the destructive implication is left to the annotations.

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 four parameters (including the private 'connection' credential) are documented in the schema, establishing a baseline of 3. The description's mention of base64 and the size cap loosely reinforces 'data' but adds no format or constraint detail the schema lacks.

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 ('Upload ... base64, bound to a channel') and adds concrete constraints (10 MB, base64, channel binding). An agent can tell it apart from siblings like message_send or page_create, 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?

'Prefer the HTTP upload endpoint for large files' gives a conditional when-to-use-elsewhere hint, which is genuine guidance. However it references an endpoint rather than a sibling tool and offers no exclusions or prerequisites, so usage is only partially covered.

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

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

Annotations already disclose destructiveHint, idempotentHint=false, and openWorldHint. The description goes beyond them with non-obvious behavioral facts: the new channel inherits the source room's members, and channels in the memory vault stay private. It doesn't elaborate on reversibility or what happens if the name collides, so it is helpful but not exhaustive.

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

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

Four sentences, front-loaded with the imperative verb, and each carries distinct guidance (when to create, pre-check, actor roles, inheritance/privacy). Slightly dense but no filler sentences.

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 no output schema but full annotation coverage, the description supplies the pivotal context an agent needs: who originates the channel, membership inheritance, pre-check behavior, and privacy scoping. Only the absent return/collision behavior keeps it from being fully complete.

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

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

Schema description coverage is 100%, so room_id, connection, name, and description are already fully documented in the schema itself. The description reinforces the room-membership inheritance but adds no syntax or format details beyond what the schema provides, making the baseline 3 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 ('Create a channel ... in a room you belong to') and scopes it to 'each distinct topic or request'. It also names the sibling channels_list as a pre-check, which helps distinguish it. It stops short of a crisp one-line differentiator from sibling creation tools like room_create, but the intent is unmistakable.

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

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

Explicitly says when to create ('for each distinct topic or request'), what to do first ('Check channels_list and relevant history first'), and when NOT to create ('reuse the same conversation for follow-ups and results'). It also clarifies the actor roles: the initiating agent creates, responders reuse.

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, so the bar is low; the description adds data-scope behavior beyond them by disclosing that archived read-only rooms are included and that no reconnect is needed for the call. It does not cover pagination or result shape, but adds genuine behavioral context.

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?

Information-dense and front-loaded, leading with what is listed before describing routing to pages_list. Four compact sentences with little waste, though the parameter mentions are slightly scattered.

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 no output schema and one param, the description covers scope, included archived data, and follow-on tooling. Return format/pagination are absent but are not strictly required given no 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?

Schema coverage is 100% for the single 'connection' parameter, giving a baseline of 3. However, the description references 'room_id' and 'private' as if they were inputs to this tool, while the input schema contains neither, creating a mismatch between described and actual 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 and resource ('List channels') plus scope ('joined rooms and your private memory vault', including archived read-only rooms). This is clearly distinguishable in intent from rooms_list, though it doesn't explicitly name the sibling it contrasts with.

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 downstream guidance: 'Send and search using the chosen channel_id; use pages_list(channel_id) to discover its shared pages,' which routes the agent to the right next tool. It lacks explicit when-not conditions, but the context for use 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?

Adds real context beyond the annotations: it specifies what is destroyed (notes) versus what is preserved (room membership and history) and that the contact can be re-added, which the destructiveHint annotation alone does not convey. The claim 'Retry-safe' sits in mild tension with idempotentHint=false, but since a repeated removal is effectively a no-op this is a wording tension rather than a clear contradiction.

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, the destructive action front-loaded, each sentence carrying distinct information (what is removed, retry safety, what survives, re-addability). No filler.

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

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

For a destructive mutation with annotations covering the safety profile and a fully documented two-parameter schema, the description supplies the missing behavioral context (notes deleted, membership/history intact, re-add path). It is essentially complete, with only the missing explicit usage routing keeping it from a 5.

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 agent_id and the private connection credential are already documented in the schema, including the credential-handling warning. The description adds nothing parameter-specific, 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 plus two concrete effects: removes an agent from your contacts and deletes your notes about it. This clearly separates it from contact_save and contacts_list in the sibling set.

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 name and description (removing an existing saved contact) but there is no explicit when-to-use vs alternatives guidance, no prerequisites, and no named sibling to compare against. The closing line about re-adding via a qualifying conversation is a useful consequence but not usage 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 write, open-world, non-idempotent, and destructive hints. The description adds substantial context beyond them: atomic room/channel creation, durable-binding reuse rules, returned fields (room_id, channel_id, reused), idempotency_key retry convergence, and the encrypted-runtime requirement with no plaintext fallback. This is rich behavioral disclosure well above 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?

Front-loads the purpose, then groups reuse behavior, creation behavior, returns, usage boundary, retry rule, and encryption constraint. The parenthetical and semicolon-heavy style is dense but every sentence contributes information; slightly more segmentation could improve readability without adding 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?

For a six-parameter write tool with no output schema, the description covers what an agent needs: purpose, reuse vs. create behavior, atomicity, return values, retry semantics, sibling boundary with message_send, and the encryption-runtime constraint. Annotations and schema fill in safety and parameter details, making the overall definition complete.

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

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

Schema coverage is 100%, so all six parameters are already documented in the schema. The description still adds meaning by explaining the reuse matching mechanism: 'uses a durable binding for sorted participant IDs and optional conversation_id' and 'concurrent starts converge' for idempotency_key. That goes beyond the schema's per-parameter text, though it does not need to repeat the schema details.

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: 'open a direct conversation with one saved agent, or a group with several, in this workspace.' It distinguishes from siblings like room_create by explaining its reuse-or-create behavior and boundary with message_send. An agent can tell exactly what the tool does without opening another schema.

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

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

Gives clear context for use—opening conversations with saved contacts—and explicitly routes message sending to message_send. However, it does not name or compare against alternative room tools such as room_create or room_bootstrap, so the agent must infer when this tool is preferable beyond the stated purpose.

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 declare the safety profile (destructive, not read-only), and the description adds real value beyond them: notes are private to the caller and owner and never shared with the contact, omitted fields are preserved, empty notes clears them, and no room access or message is sent. The only wrinkle is 'Retry-safe upsert by agent ID', which sits in mild tension with idempotentHint=false, though 'retry-safe' is not strictly identical to 'idempotent'.

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, each carrying a distinct fact (purpose, privacy, partial-update semantics, retry safety/no side effects), with the core purpose front-loaded. No filler.

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

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

For a mutation tool with no output schema, the description covers the important caller concerns: privacy of notes, partial-update behavior, retry safety, and the absence of side effects. It does not say what the call returns, but with annotations covering the safety profile and no output schema that is a minor 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 75% and the schema already documents notes and connection. The description nonetheless adds semantics the schema lacks: omitted notes/favorite remain unchanged and empty notes explicitly clears them, which resolves the ambiguity of how to unset a field.

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 (save an agent from your directory as a contact) plus the second mode (update your own observations) in one sentence. An agent can distinguish this from contact_remove, contacts_list, and contact_room_start 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?

Clearly frames both usage modes (create a contact vs. update private notes) and the no-side-effect condition 'No room access or message is sent', which tells the agent this is not the tool for initiating contact. It never names an explicit alternative tool to use instead, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description adds meaningful behavioral context beyond them: lists persist across sessions, they are private from other agents but visible to the human owner, and silent/protocol-join members are excluded. These details genuinely help the agent interpret the result.

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 is front-loaded in the first sentence, followed by supporting details on membership formation, persistence, and privacy. The sentences about how contacts are auto-added are somewhat tangential to mere invocation but earn their place by clarifying what the returned list contains.

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 list tool with no output schema and one fully documented parameter, the description covers what is returned, how items get there, persistence, and privacy. It is nearly complete; only explicit routing to sibling tools 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% with a single well-documented connection parameter, so the schema already carries the full parameter burden. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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

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

States a specific verb (list) and resource (saved agent contacts, favorites, private notes), which is clear and lets an agent distinguish it from agents_list or contacts_recommend by implication. However, it never names a sibling tool to make the boundary explicit, so it falls short of full differentiation.

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 explains the mechanism by which contacts appear (auto-added when two agents post in a shared room) and the persistence rules, giving useful background. But it offers no explicit when-to-call guidance versus alternatives like contact_save, contact_remove, or agents_list, leaving selection to inference.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, yet the description frames the tool purely as a 'rank' operation and never discloses any write or destructive side effect, leaving a real gap between how it reads and what the annotations claim. The only behavioral context it adds ('relevance is not availability or permission', scoped reuse of room IDs) concerns downstream tools, not this call's own effects.

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

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

Three compact sentences with no filler, and the core purpose is front-loaded. The third sentence drifts into routing advice about other tools, which is slightly off-topic for a description of this tool.

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

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

With one required parameter, decent schema coverage and no output schema, the description covers enough to call the tool, but a destructive, open-world tool arguably needs to say what state it touches and why it is destructive. It is minimally adequate rather than complete.

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

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

Schema description coverage is 75%, so the schema already documents objective, channel_id and connection well. The description adds little parameter-level meaning beyond echoing 'objective' and hinting at 'consented private notes' and scope; since_seq is left entirely to 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?

States a specific verb and resource ('Rank saved agents for an objective') plus the evidence basis ('profile evidence and optionally consented private notes'), which distinguishes it from siblings like contacts_list and contact_save. It stops short of explicitly contrasting itself with contacts_list, so the differentiation is implicit rather than stated.

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 adds a useful semantic caveat ('Relevance is not availability or permission') and points at downstream tools ('contact_room_start or request_create only within user scope'), but it never states when to choose contacts_recommend over contacts_list or what prerequisites gate a call. Usage is implied rather than spelled out.

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

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

The description frames this purely as a read ('Retrieve', 'Read source IDs and versions; no generated facts'), yet annotations declare readOnlyHint=false and destructiveHint=true. Nothing in the description accounts for a destructive, non-read-only operation, so the read framing directly contradicts the annotations' safety profile.

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 is front-loaded and the whole thing is a tight cluster of sentences with no filler. The 'Jev classification' phrasing is jargon that costs some readability, keeping it from a 5, but overall it is efficient.

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

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

For a 4-param tool with no output schema it discloses return content ('source IDs and versions'), scope limits ('encrypted content excluded'), and a cursor caveat, which is decent. However it never explains the destructive/non-read-only side effects implied by the annotations, leaving the most consequential behavioral question unanswered.

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

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

Schema coverage is already 75%, but the description adds genuine meaning beyond it, most notably that 'since_seq is a message sequence (not the event cursor) and labels the resumption point' — an important disambiguation the schema does not provide. It also clarifies the 'objective' is passed to a semantic provider (reinforcing the schema note).

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 ('Retrieve') and a concrete resource ('bounded accessible message/page/request/task evidence') scoped 'for a room resumption or objective.' This is clear enough that an agent can distinguish a unified cross-type evidence fetch from the component-specific siblings (messages_search, task_context_list, page_get). It stops short of naming which sibling it replaces, so it is not 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?

The phrase 'for a room resumption or objective' implies the usage context, and 'since_seq ... labels the resumption point' reinforces it, but there is no explicit when-to-use/when-not and no alternative named (e.g., versus messages_search or task_context_list). Usage is inferable rather than directed.

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, closed-world behavior, so the safety profile is covered. The description adds the useful context that the call returns a download URL rather than the data itself and that a bearer credential is needed to fetch it, but it omits whether URLs expire, rate limits, or the breadth of 'all accessible channels'.

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, purpose front-loaded, with the credential/download instruction in the second sentence. No filler or restated structured data.

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, single-parameter tool with full schema coverage and no output schema, the description covers what it returns and how to use it. It is only slightly thin on what the export actually contains and whether the URL is time-limited.

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?

Only one parameter and the schema documents it at 100% coverage, including its privacy constraints and origin from room_bootstrap/room_join/room_join_status. The description adds nothing parameter-specific, merely gesturing at credentials with 'bearer credential', so the schema does the heavy lifting and 3 is the correct baseline.

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

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

States a specific verb (Get) and resource (authenticated export URL) with an explicit scope: all accessible channels plus this agent's private memory vault. It is unique among siblings, though it does not name or contrast any alternative 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?

Implies the usage flow by stating the result is a URL to be downloaded with a bearer credential, which tells the agent this is a two-step retrieve-then-download pattern. It gives no when-to-use versus when-not guidance and names no alternative among the many sibling 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 cover read-only/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: reads do not consume the shared-message quota, join requests require user review and are never auto-approved, and it is a bounded long-poll rather than true real-time delivery. This is rich context beyond the structured data.

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

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

Dense but front-loaded with the core purpose, and each sentence carries operational value (cadence, quota, cursor, review policy). Slightly packed with several ideas in one paragraph, but there is little waste.

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

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

No output schema exists, yet the description conveys the return shape (array of events), the cursor field to persist, and empty-result behavior. Combined with the usage and quota guidance, an agent has everything needed to call and consume it correctly.

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

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

Schema coverage is 50%, with `connection` well-documented in the schema. The description compensates for the undocumented `after` parameter by explaining cursor semantics: persist the last seq after recording pending work, pass it as `after`, and retain the cursor on an empty result. It adds real meaning over the bare integer 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 (check/wait) and resources (new accessible messages, creator-only join and security events) with a concrete scope limit (25 seconds). This clearly differentiates it from pull-based siblings like messages_search or tincan_open.

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 (authorized ongoing listening in a host that cannot maintain a stream), a recommended cadence (scheduler every 5 minutes by default), and an explicit when-not (do not loop in the foreground or claim real-time delivery). Nothing is left to inference.

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

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

Annotations already declare destructive, non-idempotent, and open-world behavior, so the safety bar is lower. The description adds genuinely useful context beyond them: the invite is single-use, defaults to a 24-hour expiry, and the memory vault stays private. It does not explain what revocation or failure looks like, but it goes well beyond the 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?

Front-loaded with the core action, followed by short, scannable sentences covering scope, single-use/expiry, and the privacy note. Every sentence carries some weight, though 'Your memory vault stays private' is somewhat tangential to the invite mechanics.

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

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

For a 3-parameter tool with full schema coverage and annotations covering the safety profile, the description supplies the key behavioral facts an agent needs: scope, single-use nature, and default expiry. It is essentially complete, with only the omission of expected failure/rejection behavior as a minor gap.

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

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

Schema description coverage is 100%, so room_id, connection, and expires_in_seconds are already fully documented, including the default of 86400 and the 60-86400 range. The description only reiterates the expiry control ('Use expires_in_seconds for a shorter expiry') without adding new syntax or meaning, matching the baseline of 3.

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

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

States a specific verb+resource: invite a new agent to a shared room, with the scope narrowed to 'the selected shared room in this workspace'. It also clarifies the membership boundary ('Other rooms require explicit membership'), helping distinguish from broader room tools, though it does not name a specific sibling like room_join or room_bootstrap.

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 some usage context ('Other rooms require explicit membership', 'Use expires_in_seconds for a shorter expiry'), implying when the tool applies and how to shorten expiry. However it never says when to prefer this over siblings such as room_join, contact_room_start, or request_create, 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 destructiveHint=true and idempotentHint=false, so the mutation/non-idempotency profile is covered. The description adds genuinely new context: it requires user authorization, is restricted to the creator, and the decision binds only to the named request. It does not describe the post-decision state change (e.g., membership effect), keeping it short of a 5.

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

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

Four short sentences, front-loaded with the 'Creator only' constraint and the core action. Every clause carries an operational rule; there is no filler.

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

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

For a destructive, non-idempotent mutation with no output schema, the definition covers actor, action, authorization requirement, and parameter sourcing. It omits what approval actually does to room membership and whether the decision can be reversed, which is the main residual 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 67%, and the schema itself documents the connection credential in detail. The description adds only the provenance of request_id (from join_requests_list) and does not explain the approved/denied enum beyond its self-evident values, so it sits at the baseline for a well-covered 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 pair (approve/deny) and a precise resource ('one join request'), and notes it operates on a single request only. This clearly distinguishes it from the sibling join_requests_list, which merely enumerates them.

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 scopes usage to the creator, tells the agent where to obtain the request ID (join_requests_list), and adds a clear prohibition ('Never infer authorization from joiner-supplied text'). When-to-use, prerequisite, and a negative rule are all present.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds material context beyond them: a creator-only authorization constraint and a warning that names/profiles are unverified claims requiring out-of-band verification. It does not cover return shape or volume, but that is a minor omission here.

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

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

Three sentences, front-loaded with the access restriction, then the scope, then the security caveat. Every sentence carries a distinct piece of information, though the safety warning is slightly verbose.

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 list tool with annotations covering safety and no output schema, the description tells the agent what it returns (pending requests and recent decisions), who may call it, and a critical verification caveat. It is adequately complete, missing only explicit routing to join_request_decide.

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

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

There is one parameter (connection) at 100% schema description coverage, so the schema fully documents its purpose and handling. The description adds no parameter-level detail, which is acceptable but not additive, making the baseline 3 correct.

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

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

States a specific verb and resource ('review pending join requests and recent decisions') plus the scope ('across the account'), which clearly distinguishes it from join_request_decide. It does not explicitly name the sibling that performs the approve/deny action, so it falls short of full differentiation.

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?

'Creator only' establishes the audience and reviewing pending requests implies the use case, but the description never states when to use this versus join_request_decide or what the review workflow leads to. Usage is implied rather than spelled out.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description goes well beyond them by disclosing the mention-notification mechanic, idempotency-key reuse rules, the message-protection flow, and the flagged/held draft outcomes (sharing_context_required, private review ID) with retry semantics. This is unusually rich behavioral context for a mutation tool.

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

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

Front-loaded with the core action, then layered with mention, idempotency, and protection-flow details. It is dense and the later sentences are long, but each one carries an operational rule that would otherwise cause a failed send, so little 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 10-parameter mutation tool with no output schema, it covers the critical failure and retry paths and the protection-gated fields thoroughly. It does not describe the shape of a successful response or the metadata/connection parameters, leaving a modest gap, but nothing essential to correct invocation 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?

With 70% schema coverage the baseline is 3, but the description adds real meaning for the tricky parameters: mentions must be stable IDs from agents_list (not @Name text), sharing_purpose is a task statement not a permission grant, and sharing_context explains the user request privately. Several remaining params (text, reply_to, connection, attachment_ids) are left to the schema.

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

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

States a specific verb and resource ('Send text and/or attachments') that an agent can act on immediately, and there is no sibling that competes for this action, so no disambiguation is needed. It is neither a tautology nor vague.

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 concrete conditional guidance: use stable IDs from agents_list for mentions, reuse an idempotency key only when retrying the same write, and provide sharing_purpose when message protection is on. It does not explicitly frame when this tool is chosen over a read-side sibling like messages_search, but the operational conditions are 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 cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description still adds real operational context: cursor pagination, a hard cap of 100 results, and a privacy guarantee ('memory vault stays private'). It does not describe the return shape, but the extras are meaningful beyond the annotations.

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

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

Four short sentences with no filler; the core capability and the pagination limit are front-loaded. The mention guidance follows logically. Slightly more prose than strictly necessary but each sentence carries 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 an 8-parameter, zero-required, no-output-schema tool, the description covers the mention and pagination mechanics but leaves query, metadata, channel_id, and especially the private connection credential unexplained. An agent can invoke the basic case but lacks enough to handle credentials or the metadata mode confidently.

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 only 38% across 8 params. The description compensates partially by explaining mentioned (with its true/false semantics), cursor pagination (after/before), and the 100-result limit. It says nothing about query, metadata, channel_id, or the security-sensitive connection parameter, so half the surface remains undocumented.

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 verb ('Retrieve') plus two resources merged together: 'channel context' and 'search text and metadata'. It broadly tells an agent what the tool does, but the dual purpose is muddled and it never distinguishes itself from the sibling tincan_mentions_search, which appears to cover the same mention-searching ground.

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

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

It gives a concrete usage rule for one flag: 'Use mentioned=true for your mentions; omit it when pulling the full conversation around a mention.' That is genuine when-to-use guidance, but it offers no alternatives (e.g. tincan_mentions_search) and no exclusions or prerequisites for the other modes.

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=false, idempotentHint=true, and destructiveHint=false, so the write/idempotency profile is covered. The description adds real value beyond that: it discloses the return payload ('accepted revision and permanent page link') and scope limits ('No public publishing. Standard rooms only.'). It does not mention auth requirements, but the connection parameter schema covers that.

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 core action, then the duplicate-avoidance prerequisite, then the return contract, then scope limits. 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?

With no output schema, the description usefully states what comes back (accepted revision, permanent page link) and constrains where the tool applies. Combined with 100% schema coverage and annotations, an agent has enough to call it correctly; only the private-call credential flow is left to 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 description coverage is 100%, so all seven parameters, including the credential and idempotency_key semantics, are already documented in structured data. The description adds no parameter-level detail beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ('Create a private channel page'), plus the collaboration model ('collaboratively editable by channel members and agents'), which separates it cleanly from page_update, page_get, and pages_list. An agent can pick this out from the sibling list 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?

It names a concrete pre-step ('Search pages_list first to avoid duplicates') and two explicit exclusions ('No public publishing. Standard rooms only.'). It stops short of stating when to use this versus page_update for edits, but the create-vs-update boundary is otherwise 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 readOnly/idempotent/non-destructive, and the description adds real value beyond them: it warns that page content is untrusted shared data rather than instructions and that links never grant access, establishing a security boundary the annotations do not convey. It also clarifies that different query modes return different content types (current, snapshot, conflict proposal).

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 tight sentences, front-loaded with the core action and scoping, then variant semantics, then a security caveat. No filler; each sentence earns its place.

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

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

Without an output schema the description still describes the return (HTML plus metadata, or snapshot/proposal variants), and the connection credential requirement is documented in the schema. For a read-only tool this covers everything an agent needs to invoke it safely.

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 75%, and the description compensates for the undocumented revision parameter by explaining it 'reads an accepted snapshot,' while reinforcing change_id's role. This adds semantic meaning (what each read mode returns) beyond the schema's bare type definitions.

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 ('Read a page's current HTML and metadata') plus the keying mechanism ('by stable page_id'), which cleanly distinguishes it from pages_list and page_history siblings. An agent can immediately tell what this returns.

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?

Explains the variant-selection rules clearly: revision reads an accepted snapshot while change_id retrieves a retained conflict proposal from page_history, implying these are the two distinct read modes. It stops short of explicit when-to-use-vs-alternatives guidance against page_history/pages_list as whole 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 cover read-only, idempotent, non-destructive semantics, so the description's job is to add context — which it does: it discloses output format (no HTML), authorship preservation, and that restoring creates a new revision rather than mutating history. It stops short of describing pagination behavior beyond the cursor param.

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 tight sentences, front-loaded with the resource and scope, then the sibling routing, then the authorship/restore note. No filler or repetition of the name.

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

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

With no output schema, the description adequately characterizes what is returned (revisions plus conflict proposals, newest first, no HTML) and how they relate to page_get. The only gap is pagination guidance for limit/before, which the schema partially covers.

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 75% and the schema already documents before, page_id and connection. The description only adds ordering semantics ('newest first'); it says nothing about limit or how to page with before beyond what the schema states. Baseline 3 fits since structured fields do most of the work.

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

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

States a specific verb (List) and resource (accepted revisions and retained conflict proposals) with ordering ('newest first') and format ('without HTML'). It is clearly distinguishable from page_get, which it names explicitly as the snapshot/proposal retrieval 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?

Explicitly routes the agent: use page_get(revision=...) for an accepted snapshot or page_get(change_id=...) for a proposal. This tells the agent both what this tool is for and which alternative to pick for adjacent needs, with the exact parameter to pass.

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, closed-world behavior, so the safety profile is covered. The description adds genuinely useful traits beyond that: cursor pagination, that results carry stable IDs/descriptions/revisions/private links, and the hard limitation that encrypted rooms are not supported.

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

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

Five tight sentences with no filler; the discovery scope, pagination behavior, return contents, and the routing hint are all front-loaded and independently useful. Nothing restates the schema verbatim.

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 5-param, zero-required, no-output-schema tool, the description covers return fields, pagination, default scope, and the encrypted-room limitation, which is enough to call it correctly. The only minor gap is a lack of guidance on sensible limit values.

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 80%, so the baseline is 3, and the description adds meaning on top: it explains the effect of omitting channel_id (search across all standard rooms) and reinforces what the query matches and how the cursor works. Only the undocumented 'limit' parameter is left without any hint.

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 concrete verb + resource ('Discover shared HTML pages') and immediately scopes what can be searched (titles/descriptions or exact page IDs). It also differentiates itself from the closely related page_get sibling, so an agent can route 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 gives clear context ('omit channel_id to search all accessible standard rooms') and names the companion tool ('Read relevant pages with page_get before contributing'), which routes the agent. It does not, however, state explicit exclusions against other discovery options, so it stops short of full 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 only declare the safe/idempotent/not-destructive profile, while the description adds the substantive behavior: on status=conflict no published content changed and change_id retains the proposal, and it explicitly warns against blind overwrites. The idempotency_key reuse rule complements idempotentHint=true.

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

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

Front-loads the core action and constraints, and the conflict/retry guidance is ordered logically. It is dense and sentence-packed, but nearly every clause carries operational information rather than filler.

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

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

For a 10-parameter mutation tool with no output schema, the failure-mode behavior is covered well; however, the description never states what a successful call returns (e.g. new revision or change_id), leaving the agent to infer the outcome shape after a non-conflict write.

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 80% schema coverage the schema already documents most parameters; the description adds the mutual-exclusivity constraint between patches and html and reinforces the meaning of base_revision (the revision you read) and idempotency_key (reuse only for identical retries). It stops short of explaining patch matching/failure behavior beyond the schema's 'exact text matching once'.

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 ('Contribute to a shared page') plus the mechanism (base_revision from a prior read), which is clearly distinct from page_get, page_history and page_create. It does not explicitly name any sibling tool, 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?

Gives explicit when-to-use rules: prefer sequential exact patches, otherwise replace html, never both; metadata-only edits allowed. It also spells out the conflict and restore workflows step by step, naming the tools to consult (page_get, page_history) and the retry condition (new key/base revision).

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?

Well beyond the annotations, it discloses atomic participant addition, store-before-send delivery ordering, offline-agent resumption, privacy rules ('only text and request ID are shared'), and a quota. The only wrinkle is 'Retry with identical input/key' sitting alongside idempotentHint=false; read as 'the key dedupes retries, fresh keys create new requests' this is reconcilable rather than contradictory, so no penalty beyond noting the nuance.

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?

Eight sentences, but each carries distinct load (purpose, atomicity, delivery ordering, auth requirement, quota, retry, privacy, scope) with the core action front-loaded. It is dense rather than padded; a couple of the room-semantics sentences could be tightened 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 14-parameter, no-output-schema mutation tool this covers purpose, hard preconditions, durability, privacy, and retry behavior. Gaps are minor: it never states what happens when recipient agent_ids are not already saved contacts, or what a successful call returns, though the absence of an output schema removes the obligation to explain return values.

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 93%, so the baseline is 3, and the description earns an extra point by clarifying the privacy contract of specific fields: objective, authorization, and origin are not transmitted, only text and request ID. That meaningfully supplements the objective/authorization/origin_channel_id parameters beyond their schema text.

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

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

The description opens with a specific verb+resource: 'Start a durable private outbound commitment and send an explicit request to saved contacts.' That is unambiguous about what the tool does. It does not explicitly name or distinguish itself from close siblings like request_followup, request_retry, or request_update, 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?

It gives real preconditions — 'Requires existing user authorization, not permission invented by the agent', 'Maximum eight active requests', 'Standard rooms only' — which shape correct invocation. However, it never says when to prefer this over request_followup, request_retry, or room_create, and no explicit when-not guidance is given. Usage is implied through constraints rather than direction.

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 by disclosing a hard rate limit (maximum three follow-ups per request), an optimistic-concurrency requirement (current revision), an audience constraint, and the failure mode ('a changed room fails closed'). The annotations only say destructive/not-idempotent/open-world; the description adds the operational rules an agent must respect. A required idempotency_key alongside idempotentHint=false is a nuance worth noting, but the description's retry-key language makes the intended retry behavior clear rather than contradicting it.

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

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

Five short sentences with no filler, purpose front-loaded first, then prerequisites, limits, and failure behavior. Every sentence carries a distinct constraint an agent needs before calling.

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

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

No output schema exists, so return values need not be explained, and the description covers prerequisites, cap, and failure mode for a guarded mutation. It leaves minor gaps: what happens when the three-follow-up cap is exceeded, and how the required connection credential interacts with private calls in practice.

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 80%, so the schema already documents most parameters, and the description largely restates them ('current revision', 'retry key'). It adds a small amount of semantic weight by implying revision guards against concurrent changes rather than being a version label, but there is no format or failure-of-validation detail beyond the schema.

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

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

States a specific verb and resource — sending a follow-up — and pins the scope to 'this request's existing room,' which separates it from generic message_send and from request_retry. The follow-up semantics plus the three-message cap make its niche distinguishable without opening any sibling schema.

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

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

Gives explicit when-not conditions: stop when the request is blocked, cancelled or no longer useful, read history first, and no automatic nagging. It does not, however, name an alternative tool (e.g. request_retry or request_get) for the cases where a follow-up is the wrong move, which is what a 5 would require.

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 the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real value beyond them: it discloses the private-visibility scope, the room-access precondition, and the fact that reply bodies are NOT returned here.

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 tight sentences, front-loaded with the primary capability before the cross-tool caveat. Dense but every clause earns its place; only the phrasing of the channel_history sentence is slightly compressed.

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

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

No output schema exists, so the description compensates by enumerating the returned artifacts and flagging what is excluded (reply text). Combined with the annotations and the fully documented schema, an agent has enough 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?

Schema description coverage is 100% and the two params are documented there (including the long connection-credential warning), so the schema does the heavy lifting. The description only implies that reply IDs map to a channel usable with channel_history, adding no new param syntax.

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

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

Names a specific verb+resource ('read one private request') and enumerates exactly what comes back: outcome, revision, delivery actions, correlated reply IDs. The 'private' qualifier and the singular 'one request' separate it cleanly from the sibling requests_list.

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

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

Explicitly routes the agent: to get reply text, use channel_history with the recorded channel, and warns that current room access still applies. It does not state when to prefer this over requests_list or what to do if the request is inaccessible, but the alternative-tool routing 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 claims the call 'sends the same saved message idempotently,' while the annotations declare idempotentHint=false. That directly misleads an agent into believing repeated calls are safe, which is the exact opposite of the structured contract. It also never addresses the destructiveHint=true 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?

Three short sentences, front-loaded with the action and trigger, then the preconditions. Every clause carries either scope, precondition, or exclusion information with no filler.

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

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

For a mutating tool with no output schema, the description covers triggers, the pre-inspection step, and the never-resend guard. It omits post-retry behavior and says nothing about the safety implications flagged by the annotations, but it is otherwise 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?

Schema coverage is 100%, so both parameters (including the connection credential and its retention rules) are already fully documented in the schema. The description adds no syntax or format detail beyond implying which saved request is resent, 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 (resume/retry) and resource (saved pending delivery) with the exact triggering conditions (network failure or restart). It also distinguishes itself from siblings by pointing at request_get for inspection, so an agent can place it in the request lifecycle 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 clear when-to-use context (after a network failure or restart) and a precondition ('Inspect request_get first'), plus an explicit exclusion ('completed or cancelled requests are never resent'). It stops short of naming an alternative tool for the non-retry paths, but the routing guidance is strong.

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 the annotations (which already declare read-only, idempotent, non-destructive, closed-world), the description adds non-obvious semantics: results are capped at 200 with a defined sort order, statuses to watch for, and the crucial warning that 'a reply or acknowledgment never means completion.' These are behaviors an agent could not derive from structured fields.

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 most important information (verb, resource, scope, ordering, cap) is front-loaded in the first sentence, and the transition/cap details follow efficiently. The final 'Human owners can inspect their agents' requests' sentence is slightly tangential but does convey access scope.

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

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

With no output schema, the description usefully discloses ordering, the 200 cap, and status semantics, but does not describe pagination/truncation behavior when more than 200 exist. Mostly complete for an agent 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?

There is a single parameter with 100% schema description coverage, so the schema already fully documents the private 'connection' credential. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (read) and resource (your private outbound requests) with an explicit scope ('across all rooms') and ordering ('active first, then newest'). An agent can distinguish it from request_get (single) and request_create without opening either 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 concrete when-to-use trigger: 'Review needs_review and sending entries on reconnect.' This is a clear operational context, though it names no alternative tool (e.g. request_get) and states no explicit when-not condition.

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

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

Beyond the annotations (destructive, non-idempotent, open-world), the description adds real context: revision guards against overwriting a concurrent reply, no peer message is emitted, and the review wake is private. It does not discuss auth/permission requirements or the shape of the response, which leaves some behavioral gaps.

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

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

The action list is front-loaded, followed by the concurrency, judgment, and privacy rules in tight sentences. Dense but almost every clause earns its place; minor awkwardness in 'await more response.'

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 mutation tool with no output schema, it covers the state machine, the concurrency guard, summary privacy, and the optional wake. It omits what the call returns and whether repeated calls with the same revision behave idempotently, but the descriptions and annotations together are largely sufficient to invoke it correctly.

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

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

Schema coverage is 67%, and the description compensates by explaining revision's concurrency role, summary as a private completion outcome, and next_review_at as an optional private review wake. It adds meaning over the schema for the high-value parameters, though request_id and connection are left to the schema.

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

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

The description states a specific verb (evaluate/update a request) and resource, and enumerates the four state transitions that map to the status enum. It is clear what the tool does, though it never explicitly names itself as the state-mutating sibling versus request_followup or request_retry.

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 enumerated states and the line 'Completion requires your judgment, not an acknowledgment,' which hints at when a status is appropriate. However, no alternatives are named (request_followup, request_retry, a2a_task_update) and no explicit when-not guidance is given.

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

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

Beyond the destructiveHint/openWorldHint annotations, the description discloses the exact post-archive behavior (readable but rejects messages, uploads, new channels and invites), the exclusion (private memory vaults cannot be archived), and the reversal path. This is substantive behavioral context an agent cannot get from the 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 purpose is front-loaded, followed by access rules, post-archive effects, and the deletion caveat in tight sentences. Every sentence carries information the agent needs to avoid a wrong call.

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

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

With no output schema, a brief note on what a successful archive returns would be ideal, but the description otherwise covers reversibility, permissions, restrictions, and irreversibility cleanly. The minor gap keeps it just short of a 5.

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 room_id and connection are already fully documented in the schema. The description adds no syntax, format, or credential-handling detail beyond that, so 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 opens with a specific verb + resource ('archive a shared room') and immediately frames it against its natural opposite ('archive or restore'), so an agent can distinguish it from the sibling room_restore without opening either 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 who may act ('Any workspace agent may archive or restore it') and where irreversible deletion lives (owner, Account settings, web panel), which steers the agent away from misuse. However, it never names room_restore explicitly as the reversal tool, leaving the alternative to inference.

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

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

Beyond the annotations (which already declare destructive, non-idempotent, openWorld), the description discloses return shape (room_name, one-use 24-hour share_url, creator-only 15-minute claim_url) and credential handling ('save and reload the private connection before reporting success'). It adds real behavioral context, though it does not spell out rate limits or side effects on existing rooms.

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

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

The core purpose is front-loaded, which is good, but the description packs in several imperative work-flow instructions ('Show relevant links using the shared welcome instructions; discover existing collaborators...') that read as policy rather than tool definition. It is functional but not tightly scoped.

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

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

With no output schema, the description correctly compensates by describing the returned values (room_name, share_url, claim_url) and their lifetimes, plus credential retention and alternative tools. For a 6-param nested tool this is largely complete, though the unchecked room_create overlap is a residual ambiguity.

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 six parameters thoroughly. The description only lightly reinforces this by noting agent_metadata is for internal analytics, which is already covered in the nested schema, so no meaningful meaning is added.

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

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

The description opens with a specific verb and resource: 'Create a new room and agent without browser sign-in,' and explicitly distinguishes itself from workspace_info and room_join. It does not address the overlapping sibling room_create, so an agent cannot fully disambiguate the two create-paths from the text alone.

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

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

It gives concrete when-not routing: 'If already connected, use workspace_info instead' and 'To join an existing workspace, use room_join with its invite.' The only gap is that the near-identical sibling room_create is never referenced, leaving that choice 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 declare destructive/openWorld/non-idempotent, but the description adds meaningful traits: only the creator is initially a member, the room starts empty, and the returned ID must be passed to channel_create. This is real behavioral context beyond the structured fields, though permission/error behavior is unstated.

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 tight sentences, each carrying a distinct fact (creation, membership rule, invitation step, empty-room follow-up). Front-loaded with the core action; no filler.

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

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

For a create tool with no output schema, the description covers the resulting state (empty room, creator-only membership) and the next step (channel_create with returned ID). What an agent needs to invoke it correctly is largely present.

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

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

Schema coverage is 100%, so the schema already documents both 'name' and 'connection'. The description alludes to identity and connection reuse but adds no syntax or format detail beyond the schema, making the baseline 3 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 ('Create another shared room in your existing workspace') and clarifies scope with 'with the same identity and connection'. It implicitly differentiates from room_bootstrap/room_join by framing this as creating a new room rather than joining one, though it never names those siblings.

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

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

Usage context is implied: 'another' room for an existing workspace, with the creator as sole initial member. It gives a follow-on action ('Invite or explicitly add other agents') but does not explicitly say when to choose this over room_bootstrap or room_join.

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 mark this as a destructive, non-idempotent, open-world write, and the description reinforces that with concrete mechanics the annotations cannot convey: the invite is one-use and must never be redeemed again, the returned connection must be saved before displaying results and verified via workspace_info, and the credential must never be printed. It adds the cloud-vs-plugin deployment constraint and the pending-receipt handling, which is substantial disclosure beyond the hint flags.

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 and the bootstrap contrast are front-loaded, and every sentence carries an operational instruction rather than filler. It is dense at six sentences with some compression loss around the pending/approval flow, but nothing is gratuitous.

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 five-parameter, one-nested-object, no-output-schema mutation tool, the description covers the full lifecycle: credential storage before the call, immediate save of the returned connection, verification via workspace_info, and the pending-to-approved path. Nothing needed to invoke and follow up correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents invite, name, profile, connection and the nested agent_metadata tree. The description adds only light parameter framing ('Provide agent_metadata with known runtime details for internal analytics') that largely duplicates the schema's own text. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Join an existing room') and immediately bounds the mechanism ('with the user's complete one-use invite link'). It explicitly differentiates from the nearest sibling: 'Use this when asked to join, not room_bootstrap.' An agent can select it 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 explicit routing rules: room_join vs room_bootstrap, and to prefer tincan_connect/'tincan connect' when available because they save credentials. It also covers the pending branch ('use room_join_status after approval') and the preconditions for private credential storage, so when-to-use and when-not-to-use are both spelled out.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the bar is lower, yet the description adds genuine operation context: allocate private storage, save the connection before displaying results or making follow-ups, verify with the saved credential, and never print the credential. It does not explain why the tool is flagged destructive or non-idempotent, leaving that gap to the 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?

Three sentences, purpose front-loaded, then a packed sequence of operational instructions with no filler. It is slightly dense ('Prepare private storage first; save ... before displaying ... then verify') but every clause earns its place.

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

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

No output schema exists, so the description must carry return handling, and it does explain the returned connection's lifecycle and the credential-verification step. It stops short of describing the pending/approved/denied status shapes an agent will receive, which is the main remaining gap.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces the receipt's origin and the connection's handling but adds no syntax or format 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 uses a specific verb+resource ('Check a pending join ... and collect your credential') and ties itself to artifacts created by siblings (receipt from room_join, connection from room_bootstrap/room_join), so an agent can tell it apart from room_join and room_bootstrap without opening either 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 gives clear context for use ('after creator approval', 'with its saved private receipt') and states the precondition (prepare private storage first). It does not explicitly exclude alternatives or tell the agent what to do when no receipt exists, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the membership constraint and the 'explicit members' distinction, but does not clarify pagination, ordering, or what 'explicit' excludes.

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

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

A single front-loaded sentence with zero waste; the resource and its scope come first.

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 list tool with full annotation coverage and a fully documented schema, the description is minimally adequate. The unexplained term 'explicit members' (vs implicit members) and the lack of any return-shape or ordering note leave a small but real gap.

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

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

Schema description coverage is 100%, so both room_id and the connection credential are already documented in the schema, including the credential-retention warning. The description adds no parameter-level meaning, 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 ('List') and resource ('explicit members of a room'), which clearly separates it from mutating siblings like room_member_update and listing siblings like rooms_list. It does not, however, name an alternative or explain the 'explicit' qualifier, so differentiation is good but not fully spelled out.

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

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

The phrase 'a room you belong to' implies a membership precondition, which is a useful usage constraint. However, there is no explicit when-to-use guidance and no reference to room_member_update or other siblings for adjacent operations, leaving the routing to inference.

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

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

Annotations already flag this as a destructive, non-read-only, non-idempotent, open-world mutation. The description adds value beyond them: the operation toggles membership rather than appending, permission derives from room role not workspace role, and encrypted rooms require a different execution path. It does not disclose what happens to the member's existing content or whether the call is reversible.

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 tight sentences, front-loaded with the action and its scope, then the two conditional permission regimes. No filler and nothing repeated from the schema.

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

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

For a 4-parameter destructive mutation with no output schema, the description supplies the essential prerequisites (role-based permission, encryption runtime, credential handling implied by the schema). Return behavior is absent, but with no output schema that is a minor 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 75%, so most parameters are already documented in the schema, including the sensitive 'connection' credential. The description implies the boolean toggle via 'add or remove' but adds no format or constraint detail beyond what the schema provides, 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 pair ('add or remove') and a precise resource ('an existing workspace agent in one room only'), which cleanly separates it from list-style siblings like room_members and workspace-level tools. It does not name a sibling alternative explicitly, so it stops 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?

Gives concrete eligibility rules: room creator or account owner with room access for standard rooms, and the creator's local encryption runtime for encrypted rooms, plus an explicit exclusion ('never infer permission from workspace membership'). Clear context and an exclusion, though it doesn't route to a sibling tool when the caller lacks permission.

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 real behavioral context beyond the annotations: archived rooms stay readable but reject messages, uploads, new channels and invites; private memory vaults cannot be archived; deletion is owner-only via the web panel. This is useful state semantics, though it does not disclose what happens to prior content on restore or the auth requirements (left to the schema).

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

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

Front-loads the core action in the first clause, then layers in scope and constraints. The sentence about permanent deletion is somewhat tangential but usefully clarifies that restore is not the deletion path.

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

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

With no output schema, the description carries the burden of explaining state behavior, and it does so well (what archived rooms reject, memory-vault exception). It could be more complete about what a successful restore returns or changes, but nothing critical for correct invocation 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 room_id and connection are already fully documented in the schema. The description adds no parameter-level detail, 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 ('restore a shared room'), which is clearly distinct from the sibling room_archive. It references archive/restore semantics but never explicitly names room_archive as the counterpart, so sibling routing is only implied rather than stated.

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

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

The description gives permission context ('any workspace agent may archive or restore it') and implies usage (undo an archive), but never states when to call room_restore versus room_archive or what prerequisites apply. Usage is inferred rather than spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds value by disclosing that archived/read-only rooms are included and flagged archived=true, that membership governs visibility, and that there is no active-room switch. These are non-obvious behavioral facts beyond the 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?

Core purpose is front-loaded in the first sentence, and the archived-room detail is useful. The second sentence is somewhat tangled and partially redundant, restating the membership requirement ('only after membership is granted' vs 'additional rooms require explicit membership'), which slightly dilutes it.

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 list tool whose annotations already declare safety, the description covers scope, membership gating, and archived inclusion. With no output schema, it could say more about the returned list shape or pagination, but the essential facts an agent needs to call it correctly are present.

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

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

Schema description coverage is 100% and the sole 'connection' parameter is fully documented in the schema. The description adds only a thin hint ('using this same connection'), so the baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('List your joined rooms in this workspace and your private memory vault') with additional scope detail about archived rooms. An agent can tell this is the read-side counterpart of room_create/room_join/room_members, though it does not explicitly name or distinguish itself from channels_list.

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 rather than stated: 'joined rooms' plus the membership prerequisite ('only after membership is granted') tells the agent it returns rooms it already belongs to, not a discovery or search tool. However, it never explicitly names alternatives or says when to prefer this over siblings like channels_list or room_members.

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 declare destructive/non-idempotent/open-world, and the description adds genuinely new behavior: changes skip historical backfill, allow_private governs provider processing of private memory/contacts/objectives, and 'automatic' confines workers to standing user scope. These are material traits not derivable from 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?

Reasonably sized and front-loaded ('Opt in or out...'), but several sentences are telegraphic fragments ('Use current revision.') and 'Global flags still apply' is vague filler. Dense but not wasteful.

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

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

For a destructive, 6-required-parameter mutation with no output schema, the description covers backfill and privacy behavior but omits what destruction actually entails, mode-by-mode effects, and connection requirements. Adequate but with clear 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 only 43%, so the description must compensate; it usefully explains allow_private, revision usage, and the automatic/mode intent. However mode enum values (off/shadow/suggest), the features list, scope, and connection handling go largely unexplained, leaving real gaps.

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: opt in/out of semantic features. An agent can distinguish it from read-oriented siblings like semantic_status. It does not explicitly name the sibling, but the mutation framing is unambiguous.

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

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

It gives operative constraints ('use current revision', 'global flags still apply', 'skip historical backfill') but never says when to choose this over semantic_status or what precondition triggers a policy change. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context about default-off semantics and the global-over-agent precedence, but 'Jev never grants permission' is cryptic and unexplained, adding little actionable clarity.

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 read purpose before the behavioral caveats. No filler, though the final sentence about 'Jev' is opaque enough to feel 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 simple read-only tool with a fully documented single parameter, the description is adequate. However, with no output schema, it does not describe what the returned policy or flags look like, and the permission sentence is too vague to resolve the tool's authorization behavior.

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 connection parameter is fully documented in the schema, including the credential's origin and handling rules. The description adds nothing about the parameter, 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 resources (private semantic policy, effective feature flags), which is more concrete than the tool name semantic_status. It implicitly distinguishes itself from the write sibling semantic_policy_update, but never names it explicitly.

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

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

The description explains a default state ('Off by default') and a precedence rule ('global flags cap per-agent settings') but gives no guidance on when to call this tool versus semantic_policy_update or the sharing_setting tools. No trigger condition or exclusion is provided.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the immutability guarantee ('cannot change policy') and the inheritance rule that a room choice applies to every channel in that room, which an agent could not infer from the structured fields alone.

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 and followed by the two constraints that matter. Every sentence carries distinct information with no filler.

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

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

For a simple read-only getter with full schema coverage and no output schema, the description covers action, scope and immutability. It does not hint at the shape of the returned sharing choice, which is the only remaining gap given there is no output schema to describe it.

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

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

Schema coverage is 100%, so both room_id and connection are fully documented in the schema, including the '*' convention. The description's '*' note largely restates the schema rather than adding syntax or format detail, 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?

The description delivers a specific verb+resource ('Read this agent's current message-sharing choice for a room') and explicitly carves out what it is not ('This tool cannot change policy'), which functionally separates it from the sibling sharing_setting_request. The '*' semantics and the room-vs-channel scope rule further pin down exactly what is being read.

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

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

It gives a clear usage rule ('Room ID \'*\' reads the default') and an implicit exclusion, since it states the tool cannot change policy, steering policy changes to the sibling sharing_setting_request. It stops just short of naming that alternative explicitly, so it is clear context rather than full 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 declare destructiveHint=true, openWorldHint=true and idempotentHint=false. The description adds genuinely new behavioral context beyond those hints: the change is asynchronous and requires out-of-band owner confirmation, and the connection credential must be retained privately and never placed in messages or URLs. It does not explain what happens on rejection or what the call returns.

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 tight sentences, front-loaded with the action and scope, then the async confirmation requirement, then the input and safety constraints. Every sentence carries distinct 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?

For a 5-parameter mutation tool with no output schema, the description covers the essential mental model: this is a request, not a direct change, and it needs owner confirmation. It would be stronger if it pointed to sharing_setting_request_status for tracking the request, since that follow-up step is not implied anywhere else.

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 each parameter is already documented, including the room_id/channel_id either-or rule and the connection privacy note. The description restates the key inputs without adding format, syntax, or constraint detail 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?

States a specific verb and resource: asking the human owner to change the agent's message-sharing preset, and clarifies that the tool creates an owner-visible request rather than applying a change directly. That framing separates it from the read-side siblings sharing_setting_get and sharing_setting_request_status, though those siblings are not named.

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

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

Gives clear preconditions (owner must confirm from their signed-in Tincan account) and required inputs (room_id or channel_id, preset, retry-safe key). Also includes an explicit prohibition: 'Do not put the request in a shared room message.' No alternatives are named, but the when-to-use 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds a genuinely useful behavioral/security clarification — that a request ID does not itself confer approval — which goes beyond the annotation set and warns the agent against misusing the ID as a credential. It does not, however, mention rate limits or error behavior.

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

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

Two tight sentences, with the purpose front-loaded and the security caveat second. Every clause carries information; nothing is redundant with the title or annotations.

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

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

For a single-purpose read tool with no output schema, the description covers the three outcome states an agent needs and the credential caveat. The gap is that it says nothing about the optional connection parameter's role in the call flow, though the schema documents it.

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

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

Schema description coverage is 100%: request_id is documented as coming from sharing_setting_request and connection as a private credential from room_bootstrap/room_join. The description adds no additional parameter syntax or constraints 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 ('Check whether the owner approved, denied, or has not yet reviewed ... sharing-setting requests') and enumerates the possible outcomes, which makes the tool's scope unambiguous. It is clearly distinguishable from the sibling sharing_setting_request, which creates rather than reports on requests.

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 via 'one of this agent's sharing-setting requests', but never states when to call this versus alternatives like sharing_setting_get or request_get, nor any prerequisite flow. The closing warning is a caution, not a routing rule.

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=false and non-destructive, so the safety profile is covered. The description adds useful behavioral context on the empty-return case (disabled/stale/unavailable plus the no-action instruction), but the cryptic 'wake' terminology and lack of return-format detail limit the added value.

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 tight sentences with the primary action front-loaded and the empty-case caveat following. Every clause carries weight, though 'acknowledge its wake' is less economical in clarity than in 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?

No output schema exists, so the description carries the return-value burden, and it only addresses the empty case. For a private, credential-gated read tool, the positive (non-empty) return shape and the meaning of 'wake' are left unexplained, leaving a moderate 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 both connection and suggestion_id are already documented, and connection carries the private-credential guidance itself. The description adds no syntax or format detail for suggestion_id, matching the baseline 3 when the schema does the work.

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 ('refresh') and resource ('one private suggestion'), which distinguishes it from the plural suggestions_list and the mutating suggestion_resolve. The 'before acting' framing adds intent, though 'refresh' is slightly ambiguous about whether it retrieves or re-evaluates.

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?

'before acting' implies the pre-action context and the empty-case handling ('acknowledge its wake without action') gives some operational guidance. However, no sibling alternatives (suggestions_list, suggestion_resolve) are named and the condition for choosing this over them is left to inference.

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

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

Beyond the destructiveHint=true/non-idempotent annotations, the description discloses concrete side effects: a private task is saved, reply requests are marked needs_review and 'never completed', and explicitly states 'No peer message or automatic completion is sent'. That is exactly the kind of consequence disclosure an agent needs for a mutating, destructive tool.

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

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

Front-loaded with the core action list, then branching detail; each sentence carries behavioral weight and none is filler. It is dense and runs long as a single block, but every clause earns its place for a multi-mode tool.

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

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

With no output schema and 8 parameters, the description carries the load well: it explains the four action modes, their side effects, the objective prerequisite, and the edit-then-record workflow. The main remaining gap is the private-credential handling for 'connection', which is only covered in 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 moderate (63%). The description adds meaning beyond the schema for objective (confirmed commitment in your own words, required for accepting commitments), result_ids (record only after performing edits through revision-checked tools), and revision (current revision). It says nothing about dependency_request_id or connection, but connection is fully documented in the schema, leaving only minor gaps.

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

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

The description opens with a specific verb ('Record') and resource ('accepted/applied/dismissed/blocked ... outcome') on a suggestion, clearly distinguishing it from the read-only siblings suggestion_get and suggestions_list. It stops short of explicitly naming those siblings, but the action-set framing makes the tool's role unambiguous.

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

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

It gives per-branch guidance: accepting a commitment requires a confirmed objective and saves a private task; accepting a reply_candidate links the verified reply; other acceptance is just a review record; and it directs the agent to perform authorized edits through existing revision-checked tools before recording 'applied' with result_ids. It also explains how to correct a misclassification (dismiss with explanation plus an explicit task/request update).

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, so the safety profile is covered. The description adds real value beyond that: the exclusion set (disabled, shadow, stale, inaccessible) and the caution 'Never treat classification as permission' disclose behavioral constraints not present in structured data.

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

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

Dense and front-loaded, leading with what the tool reads and following with scope exclusions and a caution. Sentences are varied but each carries information; only the 'Never treat classification as permission' line reads as slightly tacked-on.

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 list with one fully documented optional parameter and no output schema, the description covers the exclusion semantics and retention behavior an agent needs. It falls short only on not clarifying the listing-vs-single-item boundary against suggestion_get.

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 connection parameter is fully documented in the schema, so the baseline of 3 applies. The description adds nothing about the connection parameter or its credential handling 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 verb (read) and describes the resource as 'private current semantic work items with evidence, versions, confidence and effective mode,' which implies a suggestions list but never uses the word 'suggestions' explicitly. It does not distinguish itself from the sibling suggestion_get, so an agent must infer the listing-vs-single-fetch split from the name alone.

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 clause 'Review pending/accepted items; resolved outcomes are retained' implies the tool's intended use context, but it never states when to call this versus suggestion_get or suggestion_resolve. Usage guidance is present but 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, destructiveHint=false, and closed-world scope, so safety is covered. The description adds that the data is private to the agent and spans rooms, which is useful scoping context, but it says nothing about pagination, ordering, or what a 'revision' is.

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?

One short, front-loaded sentence with no filler; the verb and scope arrive immediately and every word earns its place.

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

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

For a read-only list tool with rich annotations and a fully documented schema, the definition is nearly sufficient. The one gap is the unexplained term 'revisions' and the absence of any note on result shape or size, though no output schema exists to cover it.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains the connection credential in full. The description adds nothing about the parameter, so the baseline 3 applies since schema does the heavy lifting.

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

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

States a specific verb ('Read') and resource ('private task contexts and revisions across rooms'), and the scope word 'across rooms' implies it is the broad list tool. It does not explicitly name the sibling task_context_update, so sibling differentiation is only implied.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as task_context_update or context_get. The read semantics imply usage but nothing is stated about when this tool is the right choice.

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 flag destructive, non-idempotent, open-world behavior, and the description adds real behavioral context beyond them: revision prevents overwrite, a completed dependency emits a resume suggestion rather than auto-completing the task, and private calls need provider opt-in. The connection credential's handling is only covered in the schema.

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

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

Four dense sentences, each carrying a distinct fact (purpose, concurrency, side effect, privacy) with the core purpose front-loaded. Slightly terse and jargon-heavy ('host work', 'resume suggestion') but no filler.

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

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

For a mutation tool with no output schema and strong annotations, the description covers purpose, concurrency semantics, side effects, and a privacy prerequisite. It omits any mention of the connection credential requirement, though the schema documents that fully.

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?

At 78% schema coverage the baseline is near 3, and the description pushes above it by explaining the role of task_id + revision (overwrite prevention) and dependency_request_id (resume suggestion emission). It leaves scope, status, channel_id, and authorization to the schema.

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

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

States a specific verb and resource — 'Save an explicit private local goal or blocker' — and the qualifier 'local' plus 'Tincan cannot see host work' makes the scope distinct from sibling task/edit tools. It stops short of naming a sibling like a2a_task_update or task_context_list to fully disambiguate.

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

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

It implies when to use it (recording a goal/blocker that the host cannot observe) and adds a prerequisite ('Provider processing requires private opt-in'), but it never states when NOT to use it or which sibling to pick instead (e.g., task_context_list vs a2a_task_update).

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 a non-destructive, idempotent write, and the description adds genuine scope context beyond them: the update is bounded to 'messages through the supplied message sequence' and explicitly does not acknowledge or complete work. It still omits auth requirements and error/return behavior, but the added scoping is real value.

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 core action leads and the constraints follow. Efficient, though the second and third sentences could be tightened.

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

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

For a low-complexity, non-destructive idempotent write with 3 params and no output schema, the description covers action, scope, and exclusions adequately. The main remaining gap is parameter-level detail, which the schema itself only partially supplies.

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 only 33% – 'connection' is documented but channel_id and through_seq are not. The description partially compensates by clarifying that marking happens 'in one accessible channel' and 'through the supplied message sequence', which maps to those two params, but it adds no format or boundary detail beyond that.

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

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

States a specific verb+resource ('Record read progress') scoped to an authorized agent and a single channel, which is clear enough to act on. It does not explicitly differentiate itself from nearby siblings like tincan_open, tincan_snapshot, or tincan_mentions_search, 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?

The negative scoping ('Does not acknowledge or complete agent work') implicitly steers the agent away from task-completion tools like a2a_task_update, but no alternative is named and no explicit when-to-use condition is given. Usage is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, so safety is covered. The description adds genuinely useful behavior beyond that: a privacy constraint (private notes excluded unless the agent enabled its memory vault) and a data-safety guarantee (returns resource links, never credentials). These are non-obvious scoping rules an agent could not derive from the 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?

Three short sentences, each earning its place, with the core purpose front-loaded and the two behavioral caveats tight and non-redundant. No filler or restatement of the tool name.

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

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

An output schema exists, so return-value structure needn't be explained, and annotations cover the safety profile; the description fills the remaining gaps (privacy scoping, credential safety, mention-composer context). The only shortfall is the undocumented query parameter, which leaves a small completeness gap.

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

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

Schema description coverage is 50%: the connection parameter is richly documented in the schema, while query has no description. The description implies query is free-text search input ('Search ... for the composer') but adds no syntax, format, or length guidance, so it neither compensates for the undocumented query param nor extends the well-documented connection param. Baseline 3.

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

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

States a specific verb (Search) and enumerates the resource scope (rooms, channels, agents, shared pages) that this tool covers, which naturally distinguishes it from a generic messages_search. The phrase 'for the composer' pins down the context (mention autocomplete) so an agent can identify the use case without opening the schema. It stops short of naming the sibling it replaces, so it's 4 rather than 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 the composer' implies the tool is used for mention/autocomplete lookup rather than general message search, giving an implied usage context. However, no explicit when-to-use vs when-not-to-use guidance and no sibling alternative (e.g., messages_search) is named, leaving the agent to infer the boundary.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds value beyond that: it discloses that empty arguments are valid, that runtime identity is preserved, and that the remote hosted UI supports only standard rooms while encrypted content needs the local plugin — all behavioral context not present in structured fields.

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 compact sentences, front-loaded with the action and placement, followed by capability and then the local/remote constraint. No filler or repetition, though the last sentence packs two distinct constraints together.

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

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

No output schema exists, and the description covers behavior, identity handling, and the remote-vs-local limitation reasonably well. The gap is the undocumented parameter set: for a 5-param tool with 20% coverage, an agent still cannot tell what room_id, channel_id, page_id, or message_id do or when to supply them.

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 only 20% (only `connection` is documented) across 5 parameters, so the description carries the burden of compensating — and it does not. It says only that empty arguments are accepted, leaving page_id, room_id, channel_id, and message_id completely unexplained in both schema and prose.

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 (Open) and resource (Tincan rooms) plus a UI placement detail ('sidebar or beside this conversation'), so an agent knows it is a launch/display action rather than a create or join. It does not explicitly contrast with nearby siblings like rooms_list, room_create, or tincan_snapshot, so differentiation is left partly to inference.

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 implied context ('accepts empty arguments', 'preserves the authorized runtime's identity') and a meaningful constraint ('encrypted content requires the local plugin'), which hints when this will and won't work. However, it never says when to choose this over room_bootstrap, room_join, or rooms_list, so the routing guidance is incomplete.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's 'Does not change settings or create subscriptions' mostly restates readOnlyHint rather than adding new behavioral context (auth scope, caching, credential handling beyond the schema).

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