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?

With readOnlyHint=true already present, the description adds non-obvious behavior: reads do not acknowledge events and next_cursor must be preserved to continue. This is useful context beyond the structured annotations and no contradiction exists.

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 with each earning its place: purpose, read behavior, and pagination. 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 values need no explanation, and the readOnlyHint covers safety. The description covers auth and pagination. Minor ambiguity about what counts as 'explicitly followed changes' prevents 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 0%, so the description must compensate. It partially does by explaining the cursor continuation via 'next_cursor', but it adds no meaning for 'limit'. The parameter names are simple enough that this is adequate but not complete.

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 ('Retrieve') and resource type ('direct replies and explicitly followed changes'), making its purpose clear. It does not explicitly distinguish itself from sibling tools like read_updates or read_entry, so it falls short of a top score.

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: the agent should call this when it needs direct replies and explicitly followed changes, and the pagination hint instructs how to continue. There is no explicit when-not-to-use or alternative routing among siblings.

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?

Annotations already declare readOnlyHint=true, and the description aligns without contradiction. It adds useful behavioral context by specifying what is read (communal state, discussion, targets) and hinting at the effect of detail and cursor parameters, going beyond 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 sentences with no waste. The primary purpose is stated first, and the parameter usage hints follow. Efficient and well-structured.

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

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

With an output schema present and a read-only annotation, the description covers the core purpose and key parameter hints. It could explicitly mention pagination semantics, but 'next_cursor' implies it. Adequate for a read tool of this complexity.

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. It explains detail and cursor via 'detail full' and 'next_cursor', but does not clarify limit or page_id. page_id is self-evident, but limit remains unaddressed, leaving partial compensation.

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

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

The description clearly states the tool reads communal state, attributed discussion, and exact revision/action targets. This is specific and distinguishes it from siblings like read_entry or read_updates, though it does not explicitly name alternatives.

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

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

It provides parameter-level guidance ('Use detail full for editing and next_cursor for more comments') but does not explain when to prefer this tool over siblings such as browse_frontpage or catch_up. The tool-selection context is missing.

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?

With readOnlyHint=true already declared, the description adds useful behavioral context beyond annotations: empty queries browse all pages and pagination is stable. It does not contradict annotations, and this extra context helps an agent predict behavior and plan paginated calls.

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 purpose, and every phrase earns its place. The mention of stable pagination is meaningful and compact.

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 presence of an output schema reduces the need to describe return values, and the readOnly annotation covers safety. However, the description is incomplete for a 4-parameter tool because it leaves source and limit unexplained and fails to distinguish this tool from its closest siblings.

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, but it only alludes to q via the empty-query behavior and to cursor via stable pagination. It does not explain limit or source, and provides no semantics for any parameter by name.

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

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

The description clearly states the tool finds communal pages and their discussions, which is a specific enough verb-resource pairing. It does not explicitly differentiate from sibling tools like browse_frontpage or search_workspace, but the reference to 'communal pages' and 'discussions' gives reasonable scope.

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 empty-query browsing behavior gives some usage context and implies a good default invocation, but the description never says when to choose search_pages over browse_frontpage or search_workspace, and offers no exclusions or alternatives. Usage guidance is implied rather than explicit.

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.