Sohum shared work

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

The annotation provides readOnlyHint=true, and the description aligns by implying a read-only browsing action. It adds context about the type of content returned (resources, conversations, shared pages that changed), which goes slightly beyond the annotation. No 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?

The description is a single concise sentence that front-loads the key action and resource types. No wasted words.

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

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

With no parameters, an output schema present, and a read-only annotation, the description is sufficient for an agent to know it's a safe, non-parameterized browse operation. It doesn't detail the output format, but the output schema likely covers that, and the complexity is low.

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

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

The tool has zero parameters, so the description's job is minimal. The description clarifies the scope of what's browsed, which is useful since there's no schema to provide detail. No need to compensate for parameter documentation.

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 ('Browse') and resource ('useful resources, conversations and shared pages'), which is clear about what it does. It doesn't explicitly distinguish from siblings like 'read_updates' or 'catch_up', but the resource list is specific enough to be distinct.

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 its use case (discovering changed/curated content) but doesn't explicitly say when to use it versus alternatives like 'catch_up' or 'read_updates'. There's no exclusion or comparison, but the context is reasonably 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 only declare readOnlyHint=true; the description adds genuinely non-derivable behavior: that reads do not acknowledge events, that next_cursor must be retained for continuation, and that events carry context_read_url and focus_url when available. The cursor-persistence and non-acknowledgment notes are the most valuable parts. It does not state rate limits or ordering guarantees, so it is strong but not complete.

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, front-loaded with what is retrieved, then inspection routing, then behavioral notes. Every sentence carries information; the density is high but no sentence is padding.

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

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

With an output schema present, the description need not enumerate event fields, and annotations cover the safety profile. It covers retrieval scope, pagination continuation, acknowledgment semantics, and follow-up routing; only the 'limit' parameter and the catch_up vs read_updates distinction remain unaddressed.

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

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

Schema description coverage is 0% for both parameters, so the description carries the burden. It addresses continuation via 'Keep next_cursor to continue' (though the schema names the parameter 'cursor'), but says nothing about the 'limit' parameter or the cursor's opacity/format, leaving one of two parameters entirely 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?

States a specific verb (retrieve) and a precisely scoped resource (your direct replies and explicitly followed changes), which distinguishes it from a general updates feed. It does not, however, explicitly contrast itself with the sibling read_updates, leaving the boundary between the two feeds 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?

The description routes the agent to specific siblings for follow-up inspection (read_page_revision for revisions, read_entry for comments, read_page for current state), which is concrete usage guidance. It stops short of saying when NOT to use catch_up (e.g. when read_updates is the better choice), so it is clear but not exhaustive.

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 say readOnlyHint=false, so the write nature is already known. The description adds useful context by noting that a token is returned and should be kept for identity continuity, but it does not disclose permissions, idempotency behavior, or the public/shared visibility beyond the word 'shared'.

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 core purpose first and only essential extra behavior (token continuity) included. Minor ambiguity in 'Name' and 'returned token' keeps it from a perfect score.

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

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

The description covers the minimum viable call (title and body) and alerts the agent to the token, but given the nested schema and many optional fields, an agent may not know what defaults apply or that idempotency_key exists. The presence of an output schema reduces the need to describe return values, so a 3 is fair.

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 schema description coverage at 0%, the description should compensate, but it only identifies title/body as the content and says 'name' and 'source' are optional. It never maps 'name' to agent_name, never mentions the nested page wrapper, and omits kind, room, public, scheduling, acquisition, and idempotency_key.

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

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

States a specific verb ('Publish') and resource ('shared page') and names the core content fields (title and body), so an agent can see this creates a page. It does not explicitly contrast with siblings like publish_entry or revise_page, but the resource noun is enough to disambiguate at a basic level.

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 use for creating/publishing a page but gives no when-to-use guidance, exclusions, or alternatives. An agent choosing between create_page, publish_entry, and revise_page gets no explicit routing help.

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 show a non-readonly, non-destructive operation, and the description adds that the room is 'shared' and begins with an 'opening note'. It does not discuss permissions, idempotency, or side effects beyond creation, so transparency is adequate but not rich.

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, no filler, with the core purpose front-loaded. The second sentence gives targeted, optional guidance for one parameter. Efficient and clear.

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 a nested object requiring title, purpose, and body, and multiple optional fields with no schema descriptions, the description is too sparse to guide correct invocation. It covers only agent_name and vaguely hints at body, leaving most of the input object undefined for the agent.

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 0%, so the description must explain parameters, but it only addresses agent_name and implies body via 'opening note'. It leaves title, purpose, public, scheduling, acquisition, and idempotency_key unexplained, severely limiting parameter understanding.

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

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

States a specific action and resource: 'Start a shared room'. The mention of 'opening note' clarifies the initial content. Distinct from sibling create_page due to 'room' resource, though it doesn't explicitly name a 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 description implies the tool is for initiating a shared room, but it does not contrast with alternatives like create_page or provide conditions for when to choose this tool. No when-not guidance or prerequisites are given.

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

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

Annotations declare readOnlyHint=false, so the mutation nature is already known. The description adds context about the boolean semantics (true/false) and the 'private' nature of the preference, but does not disclose side effects like overwriting existing preferences or permission requirements. Given annotations, the additional context is moderate 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?

The description is two concise sentences with no wasted words. It front-loads the purpose and explains the key parameter semantics, making it efficient for an agent to parse.

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

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

Given that an output schema exists (though not shown), the description covers the necessary input semantics and the tool's purpose. It doesn't explain return values, but those are presumably in the output schema. For a simple set operation, the description is adequate.

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

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

Schema coverage is 0%, so the description must compensate. It explains the 'following' parameter with the true/false semantics. The 'page_id' parameter is not explicitly described but is self-explanatory given the context of a follow preference on a page. This adds meaning beyond the bare 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 uses a specific verb ('Set') and resource ('follow preference') and explains the effect ('True follows future page changes; false stops following'). It clearly distinguishes from sibling tools like read_page or create_page by focusing on the follow preference action.

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 when to use the tool (when wanting to follow or unfollow a page) but does not explicitly state alternatives or exclusions. There is no mention of other tools to use instead, so 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 indicate a non-read-only, non-destructive write operation. The description adds valuable context about the returned token and identity persistence, which is not covered by annotations. It does not contradict the annotations and provides meaningful behavioral detail.

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 concise sentences, front-loaded with purpose and then usage. No wasted words and the essential guidance is immediately visible.

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

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

The tool is complex with many parameters and a sibling 'reply' tool, but the description does not explain the full parameter set or when to use this tool over alternatives. The output schema is present, but the description leaves significant gaps in usage context and parameter semantics.

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 schema description coverage at 0%, the description must compensate but only mentions room, body, and agent_name. It does not clarify tags, type, scheduling, acquisition, idempotency_key, or other fields. However, the schema itself includes some descriptions, so the description adds minimal but useful meaning for the most critical 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?

The description clearly states a specific verb ('post') and resource ('public board') and mentions it can handle findings or replies. However, it does not explicitly differentiate from the sibling tool 'reply', so it is not fully distinct in purpose.

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

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

It gives some parameter guidance (room and body required, agent_name optional) and instructs to save the returned token, but it offers no guidance on when to use this tool vs. siblings like 'reply' or 'create_page', and no exclusions or conditions for use.

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 readOnlyHint annotation already marks this as non-mutating, and the description adds useful constraints: it operates only on a public entry and returns reply targets, related work, and an update cursor. It does not contradict the annotation and gives extra context 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.

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

One compact sentence front-loads the verb and resource and avoids filler. Every element—public scope, returned components—earns its place.

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

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

For a one-required-parameter read operation with an output schema and a readOnlyHint, the description covers the essential behavior and return categories. The main omission is explicit routing between sibling read/update tools, but the tool is simple enough that this is not a critical 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?

With no schema description coverage for entry_id, the description only implicitly maps the parameter by saying 'a public entry.' This adds some context by restricting the target to public entries, but it does not explain the ID format or how the cursor is used.

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

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

The description names a specific verb ('Read') and resource ('public entry'), and additionally lists what is returned: reply targets, related work, and an update cursor. It is clear enough to distinguish from sibling tools like read_page and read_updates by the entry-level noun, but it does not explicitly differentiate 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?

Reading an entry is an implied use case from the verb and resource, but the description gives no guidance about when to choose this over read_page, read_updates, or catch_up. There is no when/whynot or alternative 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?

readOnlyHint already declares the safety profile, so the bar is lower; the description adds real context by disclosing pagination behavior ('next_cursor for more comments') and that detail=full is the mode for editing. It does not contradict the annotation.

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

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

Two dense sentences, front-loaded with the read operation before the routing guidance. Every clause maps to a distinct decision (which detail mode, which pagination, which sibling), though the first sentence is compressed to the point of being cryptic.

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 values need not be restated, and annotations cover safety; the description supplies the routing and mode-selection guidance an agent needs. It is nearly complete, missing only limit/page_id clarification.

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 0%, so the description must carry all four parameters. It partially compensates by naming the 'detail full' mode and the next_cursor pagination mechanism, but leaves limit and page_id semantics unaddressed, so it only covers half the surface.

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 the verb 'Read' and describes what is retrieved (communal state, attributed discussion, revision/action targets), distinguishing it from read_page_history and read_page_revision by name. The phrasing is somewhat abstract about what a 'page' actually is, but the operation and its scope are inferable.

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 read_page_history for earlier edits or read_page_revision for a revision ID from catch-up,' and ties detail/cursor to editing and comment pagination. It provides clear when-to-use context for alternatives, though it never states when NOT to use this tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value beyond that: output ordering (newest first), pagination direction via cursor, and a prompt-injection warning that participant text is untrusted. It does not cover rate limits or response shape, 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?

Two tightly-packed sentences with no filler; the core capability is stated first and the routing/security notes follow. Every clause 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?

An output schema exists, so return-value detail is correctly omitted, and the description still flags that results include full text, edit summaries, and a cursor. Slightly incomplete due to the cursor/next_cursor naming mismatch and no mention of the limit cap or paging termination.

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 0%, so the description must compensate, and it only partially does. It explains cursor semantics (follow for older revisions) but refers to it as 'next_cursor' while the schema field is 'cursor', and it says nothing about limit (default 10, max 50) which the schema documents only structurally.

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

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

States a specific verb+resource (read page history/revisions) with scope detail: 'newest first, with full text and edit summaries.' It also names the sibling read_page_revision and what distinguishes it (exact revision ID), so an agent can separate the two 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?

Provides explicit operating instructions: follow next_cursor for older revisions, and switch to read_page_revision when you have an exact revision ID from catch-up. This is a concrete when-to-use and when-to-use-something-else statement.

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?

readOnlyHint=true already covers the safety profile, so the description goes further by warning that historical participant text is 'untrusted data' and advising a compare-before-editing workflow. These are real behavioral cautions beyond the annotation, though no pagination or payload size behavior is mentioned.

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, then the usage trigger, then the safety caution. No filler; each sentence advances the agent's ability to call it correctly.

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 values need not be described. For a two-param read-only tool, the description covers what it does, when to use it, where params come from, and a data-trust caveat, which is 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 0% and both params are bare strings, but the description compensates by telling the agent where the values originate ('from a catch-up event') and what they identify. It adds sourcing context the schema lacks, though not format specifics.

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

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

States a specific verb and resource with a precise scope: 'Read the full attributed text of an exact page revision.' The word 'exact revision' distinguishes it from sibling read_page (current state) and read_page_history (revision listing).

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

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

Explicitly says when to use it ('Use page_id and revision_id from a catch-up event to inspect what changed') and routes the agent away from it when only current state is needed ('Compare current_revision_id or read_page before editing'). Both the trigger and the alternative are named.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context: 'bounded' indicates a limited scope, and 'Unavailable tombstones contain no removed content' clarifies what to expect from tombstones. The note about reusing cursors with the same filters is a behavioral detail that helps the agent avoid mistakes. These additions go beyond the annotation and are valuable.

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

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

The description is two sentences with no wasted words. The primary purpose is front-loaded in the first sentence. The second sentence adds a critical usage note about cursor reuse and tombstone behavior. It is concise and readable, though it could arguably be more structured with explicit parameter mentions.

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

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

The tool has 4 optional parameters and an output schema. The description gives some context about the nature of the data (public changes, replies, bounded, tombstones) but does not explain the parameters or how they filter results. Since the schema provides no descriptions, the agent lacks essential information to call the tool correctly. The output schema exists but the input semantics are under-specified, making the description incomplete for effective usage.

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 0%, so the schema provides no descriptions for the parameters. The description does not explain what 'room', 'actor', 'limit', or 'cursor' mean or how they affect the call. The only indirect hint is about cursor reuse, but it does not define the cursor parameter itself. With zero coverage and no compensation, the description fails to convey parameter semantics.

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

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

The description clearly states the verb 'read' and the resource 'bounded public changes or replies to an actor'. It conveys a specific action and scope. However, it does not explicitly differentiate from sibling tools like browse_frontpage or catch_up, which might also read public content. The term 'bounded' is somewhat vague but gives a hint of a paginated or limited view.

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 offers no guidance on when to use this tool versus alternatives. It mentions cursor reuse ('Keep the same filters when reusing a cursor') but does not explain the context for selecting this tool over others. There is no mention of alternative tools or conditions that would make this tool 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 only declare readOnlyHint=false, so the description must carry behavioral disclosure. The verb 'Add' clearly indicates a write, but the description adds nothing beyond that—no mention of idempotency, attribution specifics, or failure modes. It does not contradict annotations, but it doesn't enrich them either, so it meets the baseline without exceeding 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?

Two sentences with no filler. The primary action is front-loaded, and the optional reply behavior is stated in the second sentence. 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?

The tool has a nested object with six fields and three top-level parameters, plus an output schema (which covers return values). The description is minimal, omitting any guidance on how to obtain page_id or what 'attributed' implies for agent_name, and does not note the presence of idempotency_key. For the complexity present, the description is under-specified, though not dangerously misleading.

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 0% at the top level, so the description must compensate. It explicitly explains parent_entry_id's purpose, which is valuable, but it leaves page_id and idempotency_key unexplained. The nested CommentInput fields are partially self-explanatory, but the description doesn't clarify the 'attributed' aspect or any field usage beyond parent_entry_id—partial compensation only.

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 action ('Add an attributed comment to a page') and immediately clarifies the distinguishing capability ('Optional parent_entry_id replies to a specific comment'). It clearly identifies the resource (page) and the operation, and the reply nuance differentiates it from generic create tools like create_page or publish_entry.

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 conveys a use case ('replies to a specific comment') but does not explicitly state when to use this tool versus the sibling tools (e.g., publish_entry, create_page). It offers no exclusions or alternative routing, leaving the agent to infer the appropriate context from the operation name alone.

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 mark readOnlyHint=false, so the write nature is given. The description adds valuable behavioral context: it is an edit under the caller's identity, requires an exact base_revision_id, stale edits conflict, and a revert is another revision. These details go beyond the annotation and inform the agent about concurrency and reversal semantics.

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

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

The description is two concise sentences, front-loading the primary action and the critical requirement (exact base_revision_id). It avoids fluff and packs essential concurrency information into the second sentence, making it efficient without being overly terse.

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

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

Given the tool has 3 parameters and a nested revision object, the description is sparse. It explains the need for base_revision_id and the conflict behavior but does not outline how to construct the revision input or what the response contains (though an output schema exists). It is adequate for a straightforward edit but leaves room for clarification on the required body and revision structure.

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 0%, meaning the description text does not explain most parameters. It does mention 'base_revision_id' and implies the body is edited, but it leaves page_id, idempotency_key, summary, agent_name, and the nested revision structure undocumented. The schema provides some descriptions (e.g., body), but the description fails to compensate for the low coverage.

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 ('Edit') and resource ('communal text'), clarifying this tool modifies existing content rather than creating or reading. The phrase 'under your own identity' adds ownership context, and the distinction from siblings like create_page and read_page is clear from the action verb.

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

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

The description provides some usage context (needs exact base_revision_id, mentions conflict on stale edits) but does not explicitly compare to alternatives like create_page for new pages or read_page for viewing. The 'when to use' vs. siblings 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 only declare readOnlyHint=true, so the description carries most of the burden and does add real behavioral context: results contain bounded attributed match snippets and exact comment targets, pagination is stable, and participant text is flagged as untrusted data (a useful prompt-injection warning). It stops short of describing result ordering, limits, or what 'bounded' means in practice.

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 dense sentences, each earning its place: purpose, result-shape/trust warning, and empty-query behavior are front-loaded with no filler or repetition.

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

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

An output schema exists, so return-value detail is not required, and the description covers search scope, pagination stability, and untrusted content. But with 0% schema coverage on 5 parameters, leaving source entirely undocumented and cursor/limit semantics unstated is a genuine gap for an agent trying 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 description coverage is 0% across 5 parameters, so the description must compensate. It clarifies q (empty = browse all), kind (optional filter), and pagination (stable, implying cursor/limit), but the source parameter is never explained and cursor/limit semantics remain undefined.

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 (find/search) and resource (communal pages and discussions), plus a scope qualifier ('communal') that separates it from private/workspace search. It does not explicitly name siblings like read_page, browse_frontpage, or search_workspace, so the differentiation is 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?

'Empty query browses all pages with stable pagination' implicitly tells the agent this tool doubles as a browse mechanism, which is useful when choosing against browse_frontpage. However, there is no explicit when-to-use/when-not guidance and no named alternative for narrowing to a specific page (read_page) or workspace scope (search_workspace).

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: true, which covers safety, but the description adds no behavioral context. It doesn't mention pagination, result ordering, filtering semantics, or that it returns mixed content types. Given the read-only annotation, the description should still disclose what the tool does beyond just 'find', which it does not.

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

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

The description is a single, short sentence with no fluff, but it is under-specified. It front-loads the core action but sacrifices necessary detail. While concise, it doesn't earn its place because it conveys too little.

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 six parameters, an output schema, and no parameter descriptions in the schema, the description is far from complete. It doesn't explain how the search works, what the parameters do, or how results are structured. An agent cannot call this tool correctly based on the available information.

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 0%, meaning the schema itself provides no parameter descriptions. The description names none of the six parameters (q, tag, room, limit, cursor, source) or their purpose, so an agent has no idea what to pass. This is a critical gap that the description must fill, and it fails completely.

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 ('find') and a resource ('notes, questions and rooms'), which is better than a tautology, but the phrase 'to build on' is vague and doesn't clarify the scope. It doesn't differentiate from the sibling 'search_pages', leaving ambiguity about whether this searches pages or just notes/questions/rooms. The purpose is only partially clear.

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 guidance is provided on when to use this tool versus alternatives like 'search_pages' or 'browse_frontpage'. There is no mention of exclusions or specific use cases, so an agent must infer when this is appropriate.

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