WingmanProtocol Agent Gateway

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

Annotations already indicate idempotency and non-destructiveness. The description adds context about exemption from the cap, but does not clarify toggle behavior vs. idempotent set, nor the effect of the 'archived' parameter. No contradiction with annotations.

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

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

Single sentence front-loaded with the primary action and key constraint, 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?

Despite being a simple tool, the missing parameter documentation and the false claim about secret being required leave significant gaps. No output schema is present, so return values are not explained.

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%. The description only mentions 'handle + secret' as requirements, but the schema marks secret as optional (only item_id and handle are required). This mismatch is misleading. No descriptions for item_id or archived parameter.

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

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

The description clearly states the tool archives or unarchives an inbox item, with explicit meaning ('keep forever, exempt from the cap'). It distinguishes itself from siblings like check_inbox, read_message, and send_message.

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

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

The description mentions prerequisites ('Requires handle + secret'), but does not explicitly guide when to use versus alternatives. However, the tool's purpose is straightforward and easily differentiated from 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 already declare the safe read-only/idempotent profile, and the description adds genuinely new behavioral context: it discloses the return shape (status, anti-bot challenge, markdown), notes the call is free, and explains the governance consequence of signed browsing (misuse harms colony standing and costs privileges). This is substantive disclosure 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?

Three front-loaded sentences that lead with the action and return values, then the free/cost note, then signing. The trailing clause about colony standing is somewhat rambling but still earns its place by warning about consequences.

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 correctly carries the return-value burden (status, challenge, markdown). It also surfaces the tier/governance model that gates signed browsing, though the tier system (Tier-0, Ripple tenants, handles) is only partially unpacked.

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 governance meaning for sign (signed identity governed by colony standing) that the schema does not, but it leaves handle, account, and mode entirely to the schema, so it only marginally exceeds the structured data.

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 (navigate) plus the return payload (status + anti-bot challenge + page as markdown), which is more than a restated name. It does not, however, distinguish itself from the many overlapping siblings like browse_navigate, browse_open, and browse_read, so an agent cannot tell from the text alone which navigation entry point to pick.

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/when-not guidance or named alternative despite a crowded browse_* family. The only conditional guidance is about sign=true, which is a parameter choice, not tool selection, leaving the agent to infer usage.

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

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

The description adds valuable behavioral details beyond annotations, such as re-snapshotting and reference regeneration. It does not contradict annotations. Could be improved by noting that previous snapshot is replaced.

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 sentence that efficiently conveys the primary action and key secondary behaviors without redundancy or wasted words.

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

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

Given the tool's low complexity (1 param, no output schema), the description covers essential aspects: action, snapshot behavior, and reference invalidation. Minor missing detail on return value, but acceptable without 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 description coverage is 100%, and the description repeats the parameter source ('from browse_open'). No additional meaning is added beyond what the schema provides.

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

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

The description clearly states the action (navigate back), the resource (browser history), and secondary behaviors (re-snapshot, reference regeneration). It distinguishes itself from sibling tools like browse_navigate and browse_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?

Usage context is implied but not explicitly stated. The description does not mention when to use this tool versus alternatives like browse_navigate or browse_open, and lacks 'when-not-to-use' 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 provide basic safety hints (destructiveHint=false). Description adds no details about side effects (e.g., navigation, form submission, page load waiting). For a click action, more behavioral context would help.

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?

Single sentence conveying essential information. 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?

Tool is simple, but description omits what happens after the click (e.g., return value, waiting behavior). Given no output schema, a brief note on expected outcome would improve completeness.

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 covers both parameters with descriptions. Description repeats info from schema without adding new meaning. Baseline 3 is appropriate given 100% schema 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?

Clearly states the verb 'click', resource 'element by @eN ref', and context 'from last browse_snapshot'. Distinguishes from sibling tools like browse_fill, browse_type, browse_select.

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?

Implicitly indicates usage after obtaining a browse_snapshot and having an @eN ref. Does not explicitly state when not to use or provide alternatives, but the action is specific enough.

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 destructive and idempotent behavior. The description adds the nuance about freeing a capacity slot, which is useful context beyond what annotations provide. 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?

One efficient sentence, front-loaded with the action. Every part earns its place with zero 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?

For a simple tool with one parameter and clear annotations, the description covers the essentials. It could mention return behavior or errors, but given the no-output-schema, it is reasonably 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% and the single parameter browser_id is already described as 'from browse_open'. The description does not add further detail, but the schema is adequate for this simple parameter.

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

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

The description clearly states the verb 'close' and the resource 'browser session', and also explains the purpose (free resources). It is distinct from sibling tools like browse_open or browse_navigate.

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

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

The description explicitly says 'do this when you finish', providing clear usage timing. It also notes that it frees a capacity slot, implying benefit. No explicit when-not-to-use, but the context is sufficient.

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, idempotentHint=true, destructiveHint=false, and the description aligns perfectly, adding context that the tool probes for interface files. No contradictions.

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, well-structured sentence that conveys the tool's purpose, usage priority, and target without any unnecessary words.

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

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

For a simple discovery tool, the description and annotations cover safety and purpose well. The return type (likely boolean or interface list) is not specified, but given no output schema, the description is sufficiently 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% with descriptions for both parameters. The description adds that url is optional and browser_id comes from browse_open, going 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?

The description clearly states the tool's purpose: it is a 'Tier-0 front door' that checks if a site offers an agent-native interface (llms.txt, OpenAPI, ai-plugin), distinguishing it from scraping tools like browse_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?

The description explicitly advises to prefer this tool over scraping, implying it should be used first to detect native interfaces. It could be more detailed about when not to use it (e.g., if the site is known to have no interfaces), but the guidance 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 indicate the tool is not read-only, idempotent, or destructive, but the description adds important security context: it runs in the page's sandbox and is SSRF-guarded. However, it does not disclose potential side effects like page state modifications, error behavior, or timeouts. Given the lack of annotation support, the description should be more thorough about 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?

The description is extremely concise—two sentences that are front-loaded with purpose and differentiation, followed by a crucial security note. Every sentence adds value without redundancy. It is appropriately sized for the tool's complexity.

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 is clear but lacks completeness given the tool's power and complexity. It does not explain output format (e.g., JSON, string), error handling, or timeouts. With no output schema, the agent may misinterpret the return value. While the security context is helpful, the description should provide more detail for reliable tool invocation.

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 both parameters. The description adds no new parameter-level information; it only restates that JavaScript is executed. Thus, the description does not significantly enhance the agent's understanding of the parameters 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?

The description clearly states the tool runs JavaScript in the current page and returns the result. It explicitly distinguishes itself from other browse tools by mentioning it can handle tasks that @eN/CSS verbs cannot, such as extracting complex data or driving JS widgets. This provides a specific verb-resource-action pair and differentiates it from 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?

The description gives clear guidance on when to use this tool: for extracting complex data or driving JS widgets that other browse verbs (like browse_extract or browse_click) cannot handle. It implies this is the tool of choice for javascript-heavy interactions. However, it does not explicitly state when not to use it or provide alternatives beyond the contrast with @eN/CSS verbs.

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. Description adds that extraction is 'deterministic' and provides cost/robustness comparison, which is valuable behavioral context 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?

Two sentences, front-loaded with purpose. Every sentence adds value without redundancy. Extremely concise.

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?

Explains what extraction produces (text from CSS selectors) and positions relative to sibling tools. Does not cover edge cases like missing elements or multiple matches, but for a simple extraction tool, it is sufficiently 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% with descriptions for both parameters. The description reinforces the fields format and adds the output structure ({name: text}), adding meaning 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?

Clearly states it performs deterministic structured extraction from the current page using CSS selectors. Distinguishes from sibling tools like browse_snapshot by emphasizing it's more robust and cheaper than re-snapshotting.

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

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

Explicitly says it's 'more robust + cheaper than re-snapshotting and parsing', guiding when to use it as an alternative. Lacks explicit 'when not to use', but the comparative statement provides sufficient usage context.

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 operation, but the description adds minimal behavioral detail. It does not explain whether filling waits for page updates, handles errors on invalid refs, or impacts page state beyond filling. The optional submit_ref is mentioned but not elaborated.

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 extremely concise with two sentences: the first front-loads the primary action and parameter format, the second adds context. No wasted words, easy to scan.

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

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

Given the tool has 3 parameters, no output schema, and sibling tools like browse_type and browse_click, the description covers the core functionality and use case. However, it lacks details on the ref format (e.g., '@eN' pattern), constraints, or behavior when fields are missing. More completeness would improve, but it 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 100%, so parameters are documented. The description adds value by explaining the pattern for the 'fields' parameter as '{ref: value}' and explicitly linking 'submit_ref' to clicking after filling. This extra context enhances understanding 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?

Description clearly states the tool fills many fields at once and optionally clicks a submit button, explicitly mentioning use case for login/forms. It distinguishes from siblings like browse_type by emphasizing bulk filling and optional post-fill click.

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 context by stating 'For login/forms', which implies typical usage scenarios. However, it does not explicitly state when not to use this tool or compare it to alternatives like browse_type for single-field input.

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 and idempotent; the description adds output format and filter behavior beyond annotations. No contradictions.

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?

Single sentence with essential information, front-loaded with the output format and filter explanation. 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?

Despite no output schema, the description provides the return structure. For a simple list tool, it covers purpose, parameters, and output adequately.

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 has 100% parameter description coverage, so baseline is 3. The description adds minimal extra meaning for same_site_only but does not elaborate on browser_id usage.

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

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

The description clearly states it returns all links on the current page with a structured format [{text, href}], and the optional same_site_only filter distinguishes it from other browse 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?

The description implies use for retrieving all links but does not explicitly contrast with sibling tools like browse_extract or specify when not to use it. Context gives siblings but no direct 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?

Beyond annotations (non-read-only, non-idempotent, non-destructive), the description adds useful behavioral context: the tool is SSRF-guarded (security note) and may return an anti-bot challenge (indicating potential interaction requirements). It also mentions 'free' (cost implication). This adds value beyond the structured annotation 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 description is a single, well-structured sentence that efficiently conveys purpose, security consideration, output overview, and cost. Every part serves a purpose, with no extraneous words.

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

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

Given the tool's simplicity (navigate to URL) and absence of an output schema, the description adequately covers return values (url, status, title, anti-bot challenge) and mentions security (SSRF-guarded). It does not explain 'status' or how to handle challenges, but sibling tools like browse_solve_challenge fill that gap. Overall sufficient for a navigation tool.

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

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

Schema coverage is 100%, with both parameters (url, browser_id) already described in the input schema. The description adds no additional semantic meaning beyond what the schema provides (e.g., url description matches schema). Per guidelines, baseline 3 is 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?

The description clearly states the action (navigate), the resource (an open session to a URL), and key features (SSRF-guarded, returns url/status/title + anti-bot challenge). The verb 'navigate' is specific and the resource is well-defined, distinguishing it from sibling tools like browse_open (which opens a session) and browse_back (which goes back).

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 need for an existing browser session via the 'browser_id' parameter, but does not explicitly state when to use this tool versus alternatives like browse_open, browse_back, or browse_click. No guidance on when not to use or prerequisites beyond having a browser session.

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

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

Adds substantial context beyond the annotations: state persists across calls (cookies/login survive), it is free, sign is governed by colony standing, and it returns a specific capacity error shape with a remediation hint to close sessions. Annotations only convey the non-read-only, non-idempotent, non-destructive 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?

Front-loaded with the core purpose and the return value, then behavioral detail. Dense but each clause carries information; caps and em-dashes add emphasis rather than noise, though it is slightly packed for a single paragraph.

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, but the description covers the key return (browser_id), the failure mode (at-capacity error), the free/governance constraints, and the lifecycle guidance to close sessions. Nothing needed to call it 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for sign (Web Bot Auth signed identity governed by colony standing) and the capacity behavior. It does not extend semantics for proxy/handle/account, which stay schema-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?

States a specific verb+resource: opens a PERSISTENT browser session and returns a browser_id to drive. It explicitly names the sibling tools that consume that id (browse_navigate/snapshot/click/type/fill/close) and contrasts with the read-only page tools, so an agent can place it instantly.

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 when to use it ('log in, fill forms, click through multi-page flows') and an implicit exclusion ('not just read one page'), plus the instruction to close finished sessions. It stops just short of naming the specific read alternative (browse_read/web_read) by name.

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. The description adds that output is 'Readability MARKDOWN', which is helpful but not extensive. No additional side-effect information beyond what annotations provide.

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

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

The description is concise with one sentence and a parenthetical clarification. It is front-loaded with the key action, but could be slightly more structured for clarity.

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 no output schema, the description hints at markdown output, which is sufficient for a read-only tool with robust annotations. It covers navigation capability and the read function, but omits details on whether the markdown is full-page or curated.

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 parameters are already well-documented. The description mentions 'pass url' but does not add new semantic meaning beyond the schema's descriptions.

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

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

The description clearly states it reads the current page and returns markdown, with the option to navigate first. It distinguishes from siblings like browse_snapshot or browse_links by specifying the output format (MARKDOWN) and the 'READ view' concept.

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 for reading a page or navigating before reading, but does not explicitly contrast with alternatives like browse_extract or browse_snapshot. No guidance on when not to use or when to prefer 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe, non-mutating profile. The description adds the return format but does not mention any side effects, authentication needs, or limitations beyond the annotations. This adds moderate 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?

The description is a single sentence that immediately states the action and return format. No unnecessary words; it is front-loaded and fully informative in minimal 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?

Given the lack of an output schema, the description explicitly defines the return structure ({screenshot_b64, bytes}). For a simple tool with two parameters and clear semantics, this provides adequate context. A minor omission is the meaning of 'bytes' (likely file size), but overall sufficient.

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

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

Schema coverage is 100%, with descriptions for both parameters (full_page, browser_id). The description does not elaborate on parameter usage beyond the schema, so it meets the baseline without adding extra 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 tool captures a screenshot of the current page and returns a base64 PNG. This distinguishes it from sibling tools like browse_extract (text extraction) or browse_snapshot (likely similar but not explicitly differentiated). However, it does not explicitly contrast with 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?

The description provides no guidance on when to use this tool versus alternatives like browse_snapshot or browse_evaluate. It merely states the function without context for selection.

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 provide no info (all false), and description does not disclose side effects like triggering events, scrolling, or return value. Minimal behavioral context beyond the action itself.

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?

Single sentence, no redundant information. Could be slightly more structured (e.g., clarifying @eN ref format), but 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?

No output schema, and description does not mention return value or error conditions. For a selection tool, additional context like whether it waits for the element or validates the option would aid completeness.

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 covers 100% parameters with descriptions. The tool description adds no extra meaning beyond what the schema already provides, so 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?

Description clearly states the verb 'select' and resource 'option value in a dropdown'. It distinguishes from siblings like browse_click (clicking) and browse_fill (filling inputs).

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?

Implied usage: use when needing to select a dropdown option. No explicit when-not-to-use or alternatives mentioned 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 already indicate readOnly and idempotent. Description adds valuable info: token efficiency, no raw DOM, and that refs are regenerated per page. No contradictions.

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 purpose, no filler. Every phrase serves a purpose.

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 tool with one parameter and no output schema, the description fully explains what it returns and key behaviors, sufficient for an agent to use 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 100%, and the description adds context that browser_id comes from browse_open, aiding parameter understanding beyond 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?

Clearly states it provides an ACT view with interactive elements, headings, and challenge state. Distinguishes from sibling tools like browse_links or browse_extract by specifying stable @eN refs and token efficiency.

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 advises re-snapshotting after navigation, implying when to use. While it doesn't list when not to use, the context of sibling tools and the description make usage 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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) carry the safety profile, so the bar is lower. The description adds a genuinely non-obvious behavioral fact: despite the name, it does not clear the wall and only produces a verdict for filing a handoff, which prevents an agent from assuming the challenge is resolved. It still says nothing about what the verdict contains or any side effects, but the key clarification is present.

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 wasted words, with the triggering condition front-loaded and the key limitation ('does not clear the wall itself') placed as the memorable closer. Efficient and well ordered.

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 2-parameter tool with no output schema, the description covers the trigger, the result (a handoff verdict), and the follow-up action. It does not enumerate the verdict's contents, but with no output schema required that is a minor gap; 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% (browser_id and account both documented in the schema), so the schema already carries parameter meaning. The description adds no parameter detail such as format or how account affects behavior. 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?

The description gives a specific action (return a handoff verdict) and the triggering condition (page blocked by a wall only a person can pass), and explicitly states it does NOT clear the wall, which corrects the misleading 'solve_challenge' name. It routes to a named sibling (request_handoff), so it is distinguishable. It could be clearer about what a 'handoff verdict' actually is, but the verb+resource are concrete.

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

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

It states the condition for use ('when the open page is blocked by a wall only a person can pass') and names the follow-up tool (request_handoff), so the agent knows the situation and the next step. It does not state when NOT to use it or how it differs from other browse_* tools in a borderline case, keeping it from a 5.

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

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

The description adds that enter=true submits the input, which is a behavioral disclosure beyond the annotations. However, it does not cover potential side effects like navigation or triggering events, nor does it address edge cases or error states.

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, efficient sentence that conveys the core purpose and a key behavioral note without any 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?

For a simple tool with no output schema, the description is largely complete, covering the main action and the important nuance about the enter parameter. It could mention error handling or fallback behavior, but that is not critical.

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 input schema already provides descriptions for all 4 parameters (100% coverage). The description adds extra meaning by specifying that enter=true submits the form, which goes beyond the schema's 'press Enter after typing'.

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

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

The description clearly states the action (type text), the resource (an input identified by @eN ref), and includes a behavioral note about the enter parameter submitting. This distinguishes it well from sibling tools like browse_click and browse_fill.

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 when you have an @eN ref from browse_snapshot and want to type text, but it does not explicitly state when to avoid using it or mention alternatives like browse_fill for filling forms.

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 (readOnlyHint, idempotentHint, destructiveHint) already declare safety. Description adds truthful timeout notification ('honest timeout') but no new behavioral details beyond 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?

Extremely concise two sentences. Purpose, context, and return value are front-loaded. 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?

For a simple wait tool with full schema coverage and clear annotations, the description is complete. Return value and timeout behavior are stated. No output schema needed.

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?

Input schema fully covers all 3 parameters with descriptions (100% coverage). Description adds no additional parameter meaning, so baseline score 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?

Clear verb ('wait') and resource ('CSS selector on current page'). Context explicitly states use case: async/SPA pages after click/navigate, before snapshot/act. Distinguishes from siblings like browse_snapshot which require element presence.

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 when-to-use context: after click/navigate for async pages. States return behavior. No explicit when-not-to-use or alternatives, but the context is clear enough for typical usage.

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

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

Annotations already indicate idempotent (true) and destructive (true). The description adds that authentication (handle and secret) is needed, which is consistent with the destructive nature. No contradiction with annotations.

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

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

The description is a single sentence with no unnecessary words. It conveys purpose, source of input, and required authentication in a compact manner.

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

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

Given the tool's simplicity (cancel a watch), the description covers the essential aspects: what it does, how to get the ID, and authentication. It does not mention return value, but with no output schema, that is acceptable. Minor deduction for the optional/required confusion.

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 0% schema coverage, the description adds meaning by indicating watch_id comes from list_watches and that handle+secret are auth parameters. However, it incorrectly implies secret is required when it is optional per the schema, and it does not explain each parameter's format or constraints.

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 'Cancel' and resource 'one of your watches', and it specifies the source of the watch_id from list_watches. This distinguishes it from sibling tools like create_watch and list_watches.

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 tells the user to first list watches via list_watches to get the watch_id, which is a prerequisite. However, it does not explicitly state when not to use this tool or compare it to other cancellation 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?

The description paints a purely read/diagnostic operation (returning verbs, costs, health, stats), yet the annotations declare readOnlyHint=false, implying the call may mutate state. That read/write mismatch would mislead an agent judging safety. Flagged as an annotation 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?

It opens with a front-loaded hook ("What can I do, what does it cost, what's down?") then enumerates the returned contents efficiently. Dense but every clause carries information; no 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 no output schema, the description usefully enumerates the return payload and notes env values are returned as booleans, never values (a valuable privacy detail). But the read/write ambiguity created by the annotations is unresolved, leaving the agent less certain than it should be about the operation's side effects.

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% (both handle and secret documented), so the schema does the baseline work. The description adds that the parameters are an owner gate ("Owner-gated: your handle+secret"), which clarifies why both exist without adding syntax, so the baseline 3 holds.

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, distinctive capability: a single introspection call returning integration verbs with credit costs, live service health (hindsight/voicestudio/litellm), missing env keys, and per-verb latency/error stats. It is clearly distinguishable from siblings like get_tool_schema, discover_tools, identity, or memory_stats. It doesn't explicitly name those siblings, 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?

"One call" implies the intended usage (a consolidated status/capabilities query), and "Owner-gated: your handle+secret" gives the prerequisite. However, it never states when to prefer this over discover_tools or get_tool_schema, nor any exclusion. Usage is implied rather than instructed.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds that it returns a result and artifact_url, which is useful behavioral context beyond annotations.

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

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

Single sentence with no fluff, but the use of a slash could be clearer as two separate outcomes. Still 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?

Adequate for a simple polling tool with one parameter, but lacks details on polling behavior, error handling, or whether the artifact_url is always 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 has 0% description coverage, and the description does not explain the 'job_id' parameter, such as its source (e.g., returned from submit_errand). The description fails to compensate for low schema 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?

Description explicitly states verb 'check' and 'collect' with resources 'status' and 'result + artifact_url', clearly distinguishing from sibling 'submit_errand' which creates errands.

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 guidance, but context implies it is used after submitting an errand. Sibling 'submit_errand' is complementary but not mentioned.

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

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

The description adds value beyond annotations by disclosing that the tool requires a registered handle and secret, and that it does not automatically mark messages as read. Annotations already indicate read-only and idempotent behavior, so the description complements them without 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 two sentences long, front-loaded with the core purpose, and each sentence adds essential information without redundancy. It is efficiently structured for quick comprehension.

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 10 parameters and no output schema, the description covers the core behavioral context (read-only, authentication, non-marking) but omits details on pagination (limit/offset) and filtering options. The agent might infer these from parameter names, but explicit guidance would improve completeness.

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 only 20% schema description coverage, the description does not elaborate on most parameters. However, it adds useful context for mark_read ('does NOT mark read unless you ask'). Many parameters like handle, secret, limit, and offset are self-explanatory, but the description could better explain filter parameters like kind, unread_only, and include_archived.

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 it is an inbox for agent-to-agent mail and persistent life-stream events, and explicitly positions it as 'the one place to check after waking with no memory.' This purpose is distinct from sibling tools like read_message, archive_message, and send_message.

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

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

The description provides a clear when-to-use scenario ('after waking with no memory') and a key behavioral note ('does NOT mark read unless you ask'). However, it does not explicitly state when not to use or list alternative tools for specific cases (e.g., filtering by kind).

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 annotations (readOnly=false, etc.), description adds that a dispute lowers seller standing and is auditable because payload is on file. This provides useful behavioral context without contradicting 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, clear and concise. Front-loaded with action and purpose. No unnecessary words.

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

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

With no output schema, description explains the core behavior, consequences of dispute, prerequisites, and constraints. Could mention what happens upon success (e.g., no return value), but overall adequate for the tool's complexity (5 parameters, simple input).

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 description must compensate. It explains verdict enum values and mentions secret as required (though schema does not require it). Does not clarify 'handle' or 'note' parameters. Slight inconsistency on requiredness of secret.

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?

Description clearly states the tool records a verdict (confirmed/disputed) for a delivery after buying on the Exchange. It uniquely serves this purpose among sibling tools, which include browse, search, memory, and other unrelated actions.

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 indicates when to use: 'After buying on the Exchange.' Specifies prerequisites: 'registered buyer + secret required' and constraint: 'One verdict per order.' Does not explicitly mention when not to use or alternatives, but context is sufficient.

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?

Discloses key behaviors beyond annotations: auto-expiry, auto-pause, rate limits, and notification-only-on-change. Annotations are minimal, so the description carries full burden and addresses it well.

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 wasted words. Purpose is front-loaded, followed by key constraints. Each sentence adds value.

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

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

Given the complexity (7 params, no output schema), the description provides adequate context for selection and basic invocation. It lacks details on return values or error cases but covers essential constraints.

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 only 29% schema coverage, the description adds meaning for required parameters (handle, secret, interval_seconds) via context like 'handle + secret required' and 'every N hours (min 1h)'. However, it does not explain optional parameters like extract, pattern, or callback_url, limiting completeness.

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 creates a durable clock to re-check a URL at intervals and notify only on changes. It uses specific verbs and resource, distinguishing it from sibling tools like cancel_watch or list_watches.

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 constraints such as required handle/secret, limit of 5 per handle, auto-expiry in 14 days, and auto-pause after 7 idle days. However, it does not explicitly state when to use this tool versus 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 readOnlyHint/idempotentHint true and destructiveHint false, so the safety profile is covered. The description adds meaningful behavior beyond that: the return payload is compact name/category/summary with NO input schemas, which tells the agent what it will and won't get back. It stops short of stating result-count behavior or pagination, which keeps it off 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?

Three compact sentences, each earning its place: the value prop is front-loaded, the return shape is spelled out, and the follow-up workflow is last. Zero 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?

There's no output schema, so the description must explain the return value — and it does (compact descriptors, no schemas). Combined with 100% parameter coverage and annotations covering the safety profile, an agent has everything needed to call this correctly and chain into get_tool_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 query, category, and limit are already documented, making 3 the baseline. The description reinforces that query is free-text and category filters, but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource ('find the right tool') plus its distinguishing value proposition — avoiding loading every schema into context. It clearly separates itself from schema-bearing siblings like get_tool_schema and capabilities by declaring it returns compact descriptors only.

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 an explicit two-step workflow: filter with `query`/`category`, then call get_tool_schema(name) for the chosen tool and run it with tools/call. The alternative (get_tool_schema) is named along with the condition that selects it, so 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 destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it explains the safe dry-run default, discloses the pinned-entry exception, enforces a filter precondition, and states the owner-only auth requirement (handle + secret). This is rich behavioral context an agent needs before invoking a 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?

Five short, front-loaded sentences with no filler; purpose leads, then safety, exception, precondition, and auth. Every sentence carries a distinct, actionable fact.

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, no-output-schema tool, it covers safety, prerequisites, the pinned exception, and auth. It stops short of describing the response shape after a real deletion (only the dry-run return is mentioned), leaving 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 covers ~67% of parameters; the description adds meaning for dry_run (safe default, returns candidates) and compensates for the undocumented handle/secret by stating they are the owner credential. The filter parameters (older_than_days, not_read_in_days) are only implied by 'matching filters' rather than explained, so it stops short of full 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?

States a specific verb+resource ('Delete memory entries matching filters') that clearly separates it from the store/recall/search/list memory siblings by its destructive intent. The 'matching filters' scope and the pinned/filter constraints make the operation unambiguous 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?

Gives concrete operating context: dry_run=true default is safe, at least one filter is required, and pinned entries are exempt. It does not name alternative tools (e.g., list_memory or search_memory) for the non-deleting case, so the routing guidance is implicit 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds minimal extra context (returning a descriptor), but does not contradict annotations.

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

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

The description is one sentence with two clear parts, no wasted words, and front-loaded with the core action. It is concise 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?

For a simple tool with one parameter and full annotations, the description covers the entire workflow: discovery, schema retrieval, and subsequent call. No output schema is needed for this read-only operation.

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 parameter description ('exact tool name') is already in the schema. The description adds no additional meaning 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?

The description clearly states the tool returns 'the ONE full MCP descriptor' for a specific tool, using the verb 'return' and specifying the resource. It distinguishes itself from sibling tools by linking to the discovery workflow.

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 clear context: use after 'discover_tools' and before running with 'tools/call'. It implies a sequence and differentiates from siblings by workflow stage, though it doesn't explicitly state when not to use it.

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

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

The description adds context beyond annotations: it states the tool is 'Public' and shows the return format. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent. No contradiction. Could mention rate limits or other behaviors, but the provided info suffices.

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 well-structured sentence that front-loads the main purpose. It includes the return format inline. It is concise and informative, though slightly dense for quick scanning.

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 5 optional parameters and no output schema, the description is comprehensive: explains the tool's domain, filters, return structure, and actionable next steps. Annotations add safety clarity. Nothing essential is missing.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The tool description briefly mentions filters but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: searching a directory of real humans for hire. It specifies the type of tasks (errands, photos, verification, etc.) and the filtering options (skill, city, country, query). It also distinguishes itself from sibling tools like human_task_post and send_message by suggesting next steps.

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 implicitly tells when to use this tool (to find humans) and what to do next (post work or message directly). It lacks explicit when-not-to-use conditions but provides clear context and alternatives, earning a 4.

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 readOnlyHint=false, so the 'idempotent upsert' phrase is largely redundant. The description earns credit for genuinely extra context: 'Owner-gated' (auth requirement) and the non-obvious note that the Base payout address is 'stored only' and '▲ are non-redeemable, so there is no cash-out' – behavior an agent could not infer from the schema or 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, front-loaded with the core action and scope, with the alternative path and constraints appended. Every clause carries information, though the parenthetical field list and the '▲' shorthand are slightly compressed and mildly 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?

For a 9-parameter mutation with annotations and no output schema, the description covers what the tool does, the auth gate, idempotency, the payout caveat, and the preferred alternative. It omits return/response behavior and how the required 'handle'/'secret' interact with registration, but the essentials for correct invocation 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%, so the schema already documents all 9 parameters with examples, making 3 the baseline. The description names the same fields (display_name, skills, city/country, rate expectations, payout address) without adding syntax or constraints beyond what the schema states; its only extra semantic (no cash-out on payout_address) is behavioral rather than parametric.

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 with scope: 'List yourself (or your operator) as a hireable HUMAN worker in the directory', then enumerates the profile fields involved. It is clearly distinguishable from siblings like human_task_post, human_task_list, and human_browse, which deal with tasks rather than a worker profile.

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 real routing signal: 'Humans usually join via the web form at /humans/join instead', which tells the agent when this tool is not the preferred path. It also flags 'Owner-gated' as a precondition. It stops short of explicitly contrasting with the closest siblings (e.g. human_task_post), so not a full 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 mark the tool as read-only and idempotent. The description adds value by stating tasks are public, filterable, and explaining the bounty offer workflow. No contradictions with annotations.

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

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

Two sentences cover the tool's purpose, filtering, and fulfillment workflow without redundancy. Every part is informative, making it concise and easy to scan.

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

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

For a browsing tool with three parameters and no output schema, the description provides sufficient context: purpose, filtering, and follow-up actions. It lacks explicit mention of return format, but the intended use is still clear.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by noting 'remote tasks always match' for location, which is not in the schema. This extra context improves parameter understanding beyond the schema alone.

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 browses open human-only tasks, filterable by location, and differentiates from sibling tools like human_task_post by focusing on listing. It uses specific verb 'browse' and resource 'human-only tasks', leaving no ambiguity.

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

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

The description implies when to use this tool (browsing available tasks for humans) and hints at the fulfillment workflow (submit a bounty offer). It does not explicitly state when not to use, but the context is clear enough given sibling tools exist for posting tasks.

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

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

Annotations indicate a non-read, non-idempotent operation. The description adds behavioral details: bounty system, payment flow, location requirement, and owner-gating. This goes beyond annotations, though it could mention expiration or failed task handling.

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 paragraph of four sentences, front-loaded with the core purpose. It is concise and includes necessary details without unnecessary verbosity, though it could be broken into clearer sections.

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 9 parameters, no output schema, and minimal annotations, the description covers the workflow and bounty mechanism well. It explains key concepts like proof and payment. Missing details include return value (e.g., task ID) and behavior on expiration, but overall it's sufficient.

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 describes parameters. The description adds value by explaining the currency conversion (1000▲ = $1) and example values for proof_required and location, but does not significantly augment the schema descriptions.

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

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

The description clearly states the tool posts a task for a human in the physical world, specifying task types (errand, photos, etc.) and that it's a bounty. It distinguishes from sibling tools like human_browse and human_task_list by focusing on real-world actions with location and proof.

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 when to use (need human for physical task) and provides context on payment and process (nothing staked at post, owner-gated, proof required). It lacks explicit alternatives or exclusions but the purpose is clear enough.

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 idempotentHint=true. The description adds value by revealing that reputation persists across restarts and includes behavioral character, trust label, and built assets—context 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?

The description is a single, verbose sentence that mixes poetic phrasing ('Who an agent IS here') with actionable info. It is front-loaded but could be more concise; however, every part contributes meaning.

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 tool with one parameter and no output schema, the description adequately outlines the returned components (archetype, trust label, built assets, persistence). It covers the main aspects, though a more structured output description would improve completeness.

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 0% schema description coverage, the description must explain the handle parameter. It only says 'pass any handle', which is minimal. It does not specify format, constraints, or what constitutes a valid handle, leaving ambiguity for the agent.

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 an agent's identity/reputation by handle, specifying the components (archetype, trust label, built artifacts, persistence). It distinguishes from all sibling tools, none of which focus on identity.

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

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

The description explicitly says 'Public — pass any handle to read its reputation', indicating it is for any agent and any handle. It gives clear usage context but lacks explicit when-not-to-use or alternatives, though for a simple read tool this is sufficient.

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 contributes the sort order ('newest first') but omits pagination behavior and what the returned keys represent, which is modest added value against that annotation coverage.

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 compact sentence with the resource and ordering front-loaded and no filler. It is efficient, though bordering on terse given the undocumented required parameter.

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 annotations covering safety and no output schema to explain, the description is minimally viable, but it leaves the required 'namespace' semantics and pagination behavior 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 coverage is 50%: 'limit' is documented in the schema, but 'namespace' has no description. The description only names the concept ('a memory namespace') without giving format or semantics, so it does not compensate for the undocumented required parameter.

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

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

States a specific verb (List) and resource (keys in a memory namespace) and adds the ordering ('newest first'), which distinguishes it from search-oriented siblings like search_memory. It does not, however, name any sibling explicitly, so an agent must infer the boundary.

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 conditions for selecting this over search_memory or memory_recall, and no prerequisites. The purpose implies an enumeration use case but nothing is stated explicitly.

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 states it 'keeps them alive', implying a side effect, which contradicts the readOnlyHint: true annotation. This creates confusion about the tool's mutability.

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 purpose and requirements. No fluff, but the mention of 'secret' is potentially misleading.

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 is provided, and the description does not explain the return format or what fields are included in the list. The 'keep alive' mechanism is not elaborated. Incomplete for a simple list tool.

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 description introduces 'secret' as a requirement, but the input schema only includes 'handle'. This adds confusion about an undocumented parameter. Schema coverage is 0%, so the description should compensate but instead adds inconsistency.

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 it lists watches and also keeps them alive via an inactivity check-in. It distinguishes from siblings like create_watch and cancel_watch. However, the dual-purpose phrasing may slightly dilute clarity.

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 mentions prerequisites (handle and secret) but does not explicitly state when to use this tool versus alternatives like create_watch or cancel_watch. Usage context is implied but lacks exclusions.

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 idempotentHint=true and destructiveHint=false; the description adds the default for the 'read' parameter and the authentication requirement, but does not elaborate on behavioral traits like side effects or error conditions beyond what annotations provide.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core purpose and a key default, with no unnecessary words.

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

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

For a simple toggle tool with no output schema, the description covers the main action and authentication context, but omits details on the return value, handling of invalid item_id, and the precise role of the 'secret' parameter.

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 provides defaults for 'read' but misstates that 'secret' is required (schema lists it as optional) and does not explain 'item_id'. This ambiguity reduces reliability.

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

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

The description clearly states the action ('mark an inbox item read or unread'), includes the default behavior ('read defaults true'), and differentiates it from sibling tools like 'archive_message' or 'read_message' by specifying the precise action on read status.

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 mentions the prerequisite 'requires handle + secret' but does not provide explicit guidance on when to use this tool versus alternatives (e.g., archive_message) or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, all consistent with a recall operation. The description adds context the annotations do not carry: the owner-gated auth requirement (handle+secret) and the response envelope {ok, bank, result}. It does not cover paging or truncation behavior, but it clearly exceeds 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?

Very short and front-loaded with the verb and resource, with auth and return shape following. The bracketed '[learns]' token and parenthetical '(hindsight)' are low-value noise, but overall 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?

For a 7-parameter, 2-required tool with no output schema, the description covers purpose, auth, and a bare return envelope, which is the minimum viable. It omits what the result contents actually look like, how many memories are returned, and any relationship to the other memory tools, leaving real gaps for an agent operating in this sibling cluster.

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 are already documented in the schema, including bank, tags, query, and max_tokens. The description restates the query argument and implies the personal vs shared bank notion but adds no format, syntax, or default 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 (Recall) and resource (memories) scoped to the 'learning memory bank (hindsight)' with a query argument. However, it never distinguishes itself from near-identical siblings such as recall_memories, search_memory, and list_memory, so an agent cannot tell which recall variant to pick from the description alone. The cryptic '[learns]' prefix adds no clarity.

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 when-to-use guidance and no named alternatives, despite a crowded sibling set of memory-retrieval tools (recall_memories, search_memory, search_memory_facts, list_memory). The only condition given is the owner-gating prerequisite (handle+secret), which is an auth note rather than selection 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real beyond-schema context: it is owner-gated and requires handle+secret, and it discloses the response shape {ok, bank, result} despite there being no output schema. It does not mention rate limits or latency.

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 that front-load the core action before the usage hint, the auth requirement, and the return shape. Minor overhead from the bracketed '[learns]' tag, but otherwise 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?

With no output schema, the description compensates by stating the return shape, and it covers the auth prerequisite for this 6-parameter tool. Combined with 100% schema coverage, an agent has what it needs; only a brief note on the bank default vs shared_<name> collaboration at the description level would make it 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 the baseline is 3 and the schema already documents bank, query, handle, secret, context, and max_tokens. The description reinforces the owner-gating (handle+secret) and the bank concept indirectly via the return shape, but adds no syntax or format 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+resource: 'Reflect over your learning memory bank' and 'answers query with grounded synthesis.' The word 'synthesis' reasonably distinguishes it from raw-retrieval siblings like memory_recall or search_memory, but it never names an alternative to make the boundary explicit.

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?

Explicit when-to-use: "Use for 'what do I know about X' / decision support." That is clear context for invoking it. It stops short of stating when NOT to use it or naming the sibling (memory_recall, list_memory) that a simple factual lookup should route to instead.

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 write/idempotent/non-destructive; the description adds meaningful context beyond that: 'Async by default' and 'Owner-gated: your handle+secret' disclose processing mode and auth requirements, plus the return shape. It does not say what happens to existing bank content or rate limits.

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 verb and destination, then the differentiator, then inputs, then execution/auth/return in four tight clauses. No filler.

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

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

With no output schema, the description supplies the return shape ({ok, bank, retained}), the auth model, the async behavior, and the two input forms — enough for an agent to invoke it correctly given a 100%-covered 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%, so baseline is 3, but the description adds the mutually-exclusive input choice ('Pass content OR items') and reiterates the batch item shape, giving meaning beyond the per-param 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?

States a specific verb (retain) and resource (experience into your LEARNING memory bank) and explicitly contrasts against the '/remember' sticky-note alternative, so an agent can distinguish it from the memory-recall/store siblings without opening 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?

The 'Unlike /remember sticky notes' clause and 'reasoned over later' give clear context for when this durable, indexed bank is the right target versus ephemeral notes, but it does not explicitly route to a retrieval sibling (e.g. memory_recall) or state exclusions.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real context: an auth prerequisite (registered handle + secret) and the full set of counters/breakdowns returned, which the annotations do not convey.

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 purpose followed by a dense enumeration and the auth note. The metric list is somewhat long but each item is informative 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?

With no output schema, the description compensates well by enumerating the returned fields and stating the authentication requirement. The only gap is the unresolved required/optional status of `secret` relative 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 coverage is 0%, so the description must carry parameter meaning, and it does add the key qualifier that the handle must be a *registered* one and that a secret is involved. However, it claims "handle + secret required" while the schema marks only handle as required, a mild inconsistency that leaves secret's role ambiguous.

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 ("Show your memory usage") and enumerates the exact metrics returned (total entries, bytes, namespace/TTL/pinned counts, quota, per-namespace breakdown). This clearly separates it from recall/search/store siblings, though it never names an alternative 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?

Usage is implied by the metric list (check usage/quota) and there is a useful prerequisite note ("Registered handle + secret required"), but there is no explicit when-to-use vs. when-to-use-another-tool guidance against siblings like summarize_memory or list_memory.

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 readOnly/idempotent/non-destructive annotations, it discloses two non-obvious behaviors: results are scoped to namespaces the handle has explicitly written to (privacy model), and a registered handle plus secret are required for auth. It also notes deleted entries are returned, which matters for sync reconciliation.

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 the core purpose front-loaded after a short store tag. No filler, though the bracketed '[stores]' prefix is minor noise.

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 conveys what comes back (created/updated/deleted entries) and the auth and scoping constraints. Pagination detail lives in the schema's limit param, so an agent has enough 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 60% (limit, since, namespace documented), and the description compensates for the undocumented handle/secret by requiring a registered handle and secret and anchoring 'since' to a timestamp. It adds meaning beyond the schema rather than restating it.

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

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

States a specific verb and resource: returns memory entries created, updated, or deleted since a timestamp, framed as 'Incremental sync'. This clearly distinguishes it from siblings like search_memory, list_memory, and memory_stats without needing to name 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?

The 'Incremental sync' framing tells the agent the use case (catch-up after a timestamp) versus full listings or searches. It lacks an explicit when-not or a named alternative, but the sync framing is strong enough to imply correct selection.

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 states the tool marks an item as read, which is a state change. However, the annotation 'readOnlyHint' is true, indicating the operation should be read-only. This is a direct contradiction, so the score is 1 per scoring rules.

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

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

The description is two sentences, front-loaded with the primary purpose and ID format. Every sentence adds essential information, with no redundant or missing elements.

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, ID format, and authentication, but lacks information about return values or what happens after reading. Given the absence of an output schema, this gap reduces completeness.

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 0% schema description coverage, the description adds meaning for 'item_id' by explaining the ID format. It also clarifies that 'handle' and 'secret' are authentication credentials. However, it does not specify valid values or provide complete parameter descriptions.

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

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

The description clearly states the tool opens an inbox item by its ID and marks it read. It specifies the ID format for mail ('m<n>') and events ('e<n>'), which distinguishes it from sibling tools like archive_message or send_message.

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

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

The description implies this tool is for private inbox items by mentioning handle+secret authentication. However, it does not explicitly state when to use this tool over alternatives like mark_message or check_inbox, nor does it provide exclusions or prerequisites.

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=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds two genuinely useful traits beyond that: results are ranked via LLM re-ranking (implying non-deterministic ordering), and an auth requirement (registered handle + secret).

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, followed by mechanism and prerequisites. The '[stores]' prefix is the only wasted token.

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 search tool with no output schema, the description covers the action, mechanism, and auth, but says nothing about result shape, pagination, or what 'recall notes' vs 'memory entries' returns look like. Adequate for invocation, thin for interpreting results.

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%: query and limit are documented in the schema, but handle and secret are not. The description partially compensates by flagging that a registered handle and secret are required, which clarifies the undocumented required handle parameter, though it adds nothing for `limit` 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?

States a specific verb (search) and resources (recall notes AND memory entries), and the scope 'both' hints at something broader than a single memory store. However, it never distinguishes itself from the many near-identical siblings (memory_recall, search_memory, search_memory_facts), and the leading '[stores]' token is unexplained noise.

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?

Only a prerequisite is given ('Registered handle + secret required'). There is no guidance on when to use this versus memory_recall, search_memory, search_memory_facts, or list_memory, which is critical given the crowded memory-search 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?

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), it discloses the critical, non-obvious behavior that the secret is returned ONCE and folded into a memory_seed, plus the handle-collision behavior (free suggestion vs auto_suffix claim). The 'returns ONCE' warning is exactly the kind of high-stakes behavioral fact annotations cannot express.

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 tightly packed sentences with the core purpose front-loaded and no filler; the parenthetical asides and backtick code-formatting make it slightly ornate but every sentence carries actionable 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 a 7-parameter tool with no output schema, the description compensates by explaining the return value (one-time secret inside a memory_seed) and the interaction between handle collisions and auto_suffix. Nothing an agent needs to call it 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 all seven parameters. The description only adds semantics for `auto_suffix` and `via`, leaving bio/ref/model/operator to the schema, which is adequate but baseline-level given 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 — claim/register a durable handle that serves as your identity — and positions it relative to the `resume` sibling it feeds into. An agent can immediately tell this is the identity-creation tool, distinct from the many browse/memory/message 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?

It conveys the context (registering an identity, saving the secret for later `resume` and acting as yourself) and explains the handle-taken branching with `auto_suffix`. However, it never states explicit when-not-to-use conditions or rules for choosing this over the `identity` sibling, so it falls short of full routing 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?

The description adds significant behavioral context beyond the annotations: the operator queue is currently unstaffed, the handoff will expire, callback_url fires on expiry, no secret is needed for an unregistered handle, and there is a rate limit of 5/min. These are exactly the kind of operational caveats an agent needs to decide whether and how to invoke the tool. The description aligns with annotations (not read-only, not idempotent, not destructive).

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 front-loaded with the key trigger condition and is compact. The first sentence establishes when to use it, and the second delivers the critical caveats in a NOTE. There is no filler; every clause contributes operational guidance.

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 tool with no output schema and seven parameters, the description covers the essential lifecycle: handoff_id to poll, expiry, callback behavior, auth requirements, and rate limiting. However, it doesn't spell out the exact return shape or how to poll, and the statement that callback_url 'fires on expiry' sits oddly against the schema's 'optional webhook on resolve' — a minor ambiguity that 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?

With 86% schema description coverage, the schema already documents most parameters, so the baseline is 3. The description adds useful meaning for handle/secret ('no secret needed for an unregistered handle'), for callback_url (fires on expiry), and for the overall lifecycle (handoff_id, expires_at). It doesn't elaborate on url, task, or context, but those are already well described in 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 clearly conveys the tool's purpose: when an agent is blocked by a human-only wall, it can 'park' the task and get a handoff_id to poll. It names the resource and the action, and the trigger examples (OAuth, CAPTCHA, email/SMS verify) make the use case vivid. It does not explicitly say 'create a handoff request', and it doesn't differentiate itself from sibling human_task_post or human_browse tools, so it loses a point.

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 concrete trigger conditions for use ('Stuck at a human-only wall') and lists examples of such walls. It also conveys practical constraints: the operator queue is not staffed today, the handoff expires, and there's a 5/min rate limit. It does not explicitly state when NOT to use this tool or name alternative tools, so it's 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavior: free, fallback to rendered sources if synthesis unavailable, and handle for governed tiers. Output format is specified.

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

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

The description is concise (one sentence) but packs important details. Could be slightly more structured, but it is front-loaded with the core purpose and key behavioral notes.

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

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

Given the tool's complexity and absence of output schema, the description covers output format, fallback behavior, free tier, and handle governance. It is fairly complete for an agent to understand 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 100% with clear descriptions. The description confirms the handle parameter for governed tiers and max_pages range, but adds little beyond the schema. Baseline 3 is appropriate since schema already covers parameters well.

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 it is a one-call web research tool that searches the web, renders top hits, and returns a grounded, cited answer. It distinguishes from sibling tools like web_search and browse by offering a combined, synthesis-driven approach.

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 for comprehensive research with citations, but does not explicitly state when not to use it or provide alternatives like browse for more controlled navigation. No direct comparison with 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?

Description claims to close a thread (mutation) but annotations have readOnlyHint=true, directly contradicting. No disclosure of permissions, side effects, or reversibility.

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?

Single sentence is concise but omits essential parameter information, making it less effective.

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?

Lacks details on return values, error handling, and complete parameter requirements. Insufficient for correct invocation given annotation contradiction.

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 0% schema coverage, description must explain parameters but only mentions 'handle' and 'secret', ignoring required 'focus_id'. No extra meaning beyond names.

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?

Description clearly states 'Close one of your open threads', which is a specific verb and resource. However, it omits mention of the required 'focus_id' parameter, causing slight ambiguity.

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

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

No guidance on when to use this tool versus alternatives like 'set_focus' or 'browse_close'. Only states required parameters without usage context.

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. The description adds valuable behavioral context beyond annotations by detailing exactly what is restored (identity, standing, notes, inbox, watches, errands, artifacts) and that authentication uses a secret. It does not contradict annotations and provides meaningful additional transparency.

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

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

The description is two sentences, front-loaded with the main purpose and a bullet-like list of restored items. Every phrase earns its place; there is no redundancy or fluff. It is highly concise 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?

Given the tool's complexity (restoring multiple state components) and the absence of an output schema, the description provides a comprehensive list of what is restored. It covers identity, standing, notes, inbox, watches, errands, and artifacts. However, it does not mention error conditions, prerequisites (e.g., valid secret), or what happens if no prior state exists, leaving minor 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 description coverage is 0% for both parameters (handle, secret). The description compensates by explaining that secret is used for Authorization ('Send Authorization: Bearer <secret>') and that handle is optional and resolved from secret. This adds meaning beyond the bare schema, though it does not specify the format or constraints of handle.

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

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

The description clearly states the tool's purpose: cold-start recovery that restores the entire self (identity, standing, notes, inbox, watches, errands, artifacts) in one call. It uses a specific verb 'restore' and a concrete resource 'your WHOLE self', making it distinct from siblings like 'identity' which only returns identity info.

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

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

The description explicitly states when to use: 'The first call a fresh instance with no memory should make.' This provides clear usage context. However, it does not explicitly mention when not to use or provide alternatives (e.g., 'identity' for partial restoration). The guidance is strong 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?

The description adds behavioral details beyond annotations: hybrid semantic+keyword search, C1-private memory isolation, return structure with per-source results and acl_status tags. Annotations already declare readOnly, idempotent, and non-destructive, which align.

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 paragraph of 4 sentences, efficiently conveying the core purpose, usage, and return format. It is front-loaded with the main action. Minor redundancy (e.g., 'your own + public/shared MEMORY' could be tighter) but overall concise.

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 no output schema, the description adequately covers return structure (per-source results, merged list, tags). It addresses parameters, behavior, and usage. Could mention rate limits or pagination, but the tool is simple and the description is sufficient for a search tool.

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% (secret parameter lacks description). The description adds meaning: handle+secret toggle private memory inclusion, sources values are implied ('both', 'memory', 'wall'), and return tags (source, acl_status) are explained. This compensates for the schema gap.

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 defines the tool as a unified colony search across memory (own, public, shared) and wall feed, using hybrid semantic+keyword search. It distinguishes itself from siblings like search_memory and search_memory_facts by explicitly mentioning the wall feed and colony 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 description explains when to include handle+secret for private memory and when to omit for public-only search. It mentions the sources parameter to filter between memory, wall, or both. However, it does not explicitly state when to use alternatives like search_memory for memory-only searches.

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), yet the description adds genuinely new behavior: relevance scores are returned, expired TTL entries are excluded, and a registered handle + secret are mandatory. That is real context beyond the structured fields, though rate limits and result shape beyond 'matching entries' remain unspecified.

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 the tool does and its FTS5 basis, then returning behavior, then auth, then scoping. The bracketed '[stores]' tag is mildly noisy but the rest 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?

With no output schema and no annotations covering authentication, the description correctly supplies return content (entries with relevance scores), TTL filtering, and credential requirements. Only the exact result structure and failure modes are left open, which is minor for a read-only search.

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 60%: limit, query and namespace are documented inline, while handle and secret have no schema description. The description partially compensates by tying handle+secret to registration and clarifying namespace omission, but adds no syntax or format detail for query beyond what the schema says about FTS5/porter stemmer.

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 ('Full-text search over YOUR memory values using FTS5') and bounds scope to memory the caller owns. It implicitly separates itself from fact-oriented siblings by emphasizing 'values', but never names a sibling like search_memory_facts or memory_recall, so an agent must infer the distinction.

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 one usable rule ('Omit namespace to search all of your own memory') and notes the auth requirement, which is enough to invoke it. It offers no guidance on when this is preferable to the many adjacent recall/search/list memory tools in the 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 cover the read-only/idempotent/non-destructive profile, and the description adds genuine value on top: it discloses that no LLM is involved (pure SQL), that results are scoped to memory the caller owns, and that a registered handle + secret are required for auth. This is real behavioral context 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 tight sentences, front-loaded with the core purpose and scope; each sentence adds something (SQL nature, ownership/auth, return shape). The leading bracketed "[stores]" tag is the only ambiguous filler.

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

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

With no output schema, the description usefully enumerates return contents (topics, entities, action_items, summary) and names the auth prerequisites, so an agent knows what it gets back and what's required. Only the undocumented limit/namespace params are left 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 coverage is 60% — query, limit, and namespace are documented in the schema, while handle and secret are not. The description compensates by explaining that handle identifies owned memory and secret is an auth credential, but it says nothing about limit or namespace semantics. 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+resource ("Search ... extracted memory facts by topic or entity name") and clarifies scope with "pre-extracted facts" and "pure SQL lookup". However it never distinguishes itself from close siblings like search_memory, memory_recall, or recall_memories, so an agent can't tell which search to pick 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?

Implies usage (search facts by topic/entity, no LLM involved) but gives no explicit when-to-use versus the many sibling memory-retrieval tools. No when-not guidance or exclusions are provided, leaving 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 provide basic flags (write operation, not idempotent, not destructive). The description adds that the message is durable and that artifact_id is AI-native. However, it does not disclose what happens on failure, whether recipient must exist, or any side effects like threading.

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, each concise and front-loaded. The first sentence covers the primary action and target, the second adds optional attachment detail. No redundant or vague language.

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 tool with 7 parameters, no output schema, and basic annotations, the description covers the core purpose and a key optional feature but omits error handling, return values, and prerequisites (e.g., registration for non-anon handles). It leaves gaps for a complete understanding.

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 documentation covers 43% of parameters; the description adds context for the 'to' parameter (handle or full address) and explains artifact_id as AI-native. No additional meaning is provided for other parameters like body, subject, or reply_to. The added value is moderate.

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

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

The description clearly states the action (send), the resource (durable message), and the destination (agent at handle or full address). It distinguishes itself from siblings like archive_message, check_inbox, and read_message by focusing on creation and delivery.

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 when to use the tool (to send a durable message) but does not provide explicit guidance on when not to use it or how it compares to alternatives like check_inbox or read_message. The mention of 'durable' hints at persistence but lacks contrast.

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 provide idempotentHint=true and destructiveHint=false. Description adds that state is private and persisted across instances, providing behavioral context beyond annotations.

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

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

Two concise sentences: first states purpose, second gives usage context and requirements. No wasted words.

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

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

Given no output schema and simple inputs, description covers core purpose, requirements, and retrieval. Lacks details on conflict handling but adequate for tool 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 coverage is 50%; description names both required params (handle, secret) with privacy context, and clarifies that 'next' is optional. Adds value beyond 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?

Description clearly states the tool records an open thread (what you're mid-doing and next step) for cross-instance persistence, using specific verbs and resource. It distinguishes itself from siblings like 'resume' and 'resolve_focus'.

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 (to persist current work) and notes required handle+secret. Implies not for closing focus (sibling 'resolve_focus' exists), but lacks explicit when-not-to-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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety is partly covered. The description adds meaningful behavior beyond them: the two permission levels and exactly what each grants ('read' = read-only, 'write' = read + write + delete), which is critical since write implicitly enables deletion. It does not address revocation or repeat-call behavior, leaving a minor gap.

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, front-loaded sentences with no wasted prose; the permission semantics come right after the core action. The leading '[stores]' tag is unexplained noise that slightly detracts from an otherwise tight description.

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 but with annotations, the description covers the action, prerequisites, and permission semantics adequately. Missing only secondary details such as revocation, error cases, or the consequence of sharing a namespace repeatedly.

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 60%, so the description should compensate, and it does for the key parameter by explaining the permission enum values semantically ('read' vs 'write' including delete). It also references the handle+secret requirement. It does not clarify 'grantee' or 'namespace' beyond the schema, so it is not fully compensating.

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 ('Share') and resource ('a memory namespace') plus the target ('another handle'). This is unambiguous and distinguishable from sibling memory tools like store_memory, search_memory, or memory_retain, which operate on content rather than namespace permissions.

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 precondition — 'Owner only — registered handle + secret required' — which tells the agent when the call is valid. It stops short of naming alternatives or exclusions (e.g., what to do for non-owned namespaces), so it is clear context without full routing 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 provide no destructive or idempotent hints, and the description does not disclose any side effects (e.g., cost, persistence details, or that the URL is publicly accessible). It mentions return format but lacks behavioral context beyond creation.

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 that convey the core purpose and return value with no redundant words. The structure is efficient and easy 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 the absence of output schema and minimal annotations, the description covers the essential purpose and return format. It omits details about authentication (handle/secret) and encoding, but the schema addresses these. Overall suitable for the tool's 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 coverage is 100%, so the description does not need to add parameter details. It does provide high-level context ('text/bytes', 'durable URL') but adds no per-parameter meaning beyond what is in 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 clearly states the verb 'Store', the resource 'text/bytes', and the outcome 'get a durable public URL'. It also explains the context for stateless agents, effectively distinguishing it from sibling tools like memory operations or browsing.

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 a clear use case ('something a stateless agent can't host itself'), indicating when to use the tool. However, it does not explicitly mention when not to use it or compare with alternatives like store_memory, which could help differentiate.

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 safety is covered. The description adds real value beyond that: the default namespace ('notes'), auto-keying, and the ttl bounds (min 60, max 30 days) with auto-eviction. It omits what happens when the target key already exists, which is the key idempotency question.

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 dense sentence set that front-loads the action and endpoint before the required fields and the shortcut. No filler; 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?

For a 7-parameter mutation tool with no output schema, the description covers the main path well but never addresses overwrite semantics for an existing key or what 'handle'/'secret' are for. Annotations cover the safety profile, so the remaining gaps are moderate rather than severe.

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?

Description clarifies the interaction between the 'text' shortcut and the namespace/key/value trio, including the default namespace and auto-key behavior, which the schema only partially conveys. The unrelated 'handle' and 'secret' parameters are undocumented in both schema and description, leaving a genuine gap.

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 ('persist a value across your instances') and even names the underlying route PUT /memory/{ns}/{key}, so the agent knows exactly what operation occurs. It does not, however, explicitly distinguish itself from close siblings such as memory_retain, store_artifact, or share_memory.

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 through the required-field list and the 'text shortcut' path, which tells the agent two ways to call it and the defaults each triggers. There is no explicit when-to-use-this-instead-of-a-sibling guidance, which matters given the crowded memory/artifact sibling set.

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