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

With no annotations, the description carries the full burden of behavioral disclosure. It adds context by explaining this is a recall signal that keeps ACC honest, but it does not detail persistence, side effects, or repeatability. It's not misleading, but more transparency about what 'logging' entails would be better.

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 only three sentences with the action front-loaded. Every sentence earns its place: the first states what it does, the second gives the usage trigger, and the third explains its purpose. There is no filler or redundancy.

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 logging tool with no output schema, the description fully covers purpose, trigger, and context. It explains the 'missed-conflict' concept and why the ACC monitor needs this signal. It doesn't mention return values, but that is unnecessary for a log action.

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 describes both parameters (domain and description) with clear explanations and examples, covering 100% of them. The tool description does not add extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action (log a missed-conflict) and the specific resource (ACC monitor). It distinguishes itself from automatic detectors by explicitly targeting conflicts they didn't flag. This makes its purpose unmistakable and differentiates it from sibling 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 explicitly provides a use condition: 'Use when you (or the user) catches a conflict type that the automatic detectors did not flag.' This gives clear situational guidance and implies not to use it for already-flagged conflicts, even though no alternative tool is named.

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

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

No annotations are provided, so the description carries the full transparency burden. It names the hook types (read, write, describe) but does not disclose side effects, return values, required permissions, or behavior when data is omitted for a write hook. This is a significant gap for a tool that can mutate via the 'write' hook.

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 with no filler. It efficiently conveys the core action and scope. It could optionally include a brief note about parameters or return behavior, but the current structure is appropriately concise for a simple tool.

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

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

There is no output schema and no annotations, so the description must compensate but does not explain what the tool returns, how errors are surfaced, or prerequisites like needing an existing app. The parameter schema covers 'what' but not 'what happens' or 'what you get back', leaving the description incomplete for effective agent 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?

The input schema has 100% description coverage with clear descriptions for all parameters, including 'Data payload for write hook' and the slug location. The description adds minimal semantic value beyond the schema, just listing hook names that already appear in the enum. Baseline 3 is appropriate when schema carries the load.

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

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

The description uses a specific verb ('invoke') and names the resource ('app hook') with targeting info ('dashboard app by slug'). It also enumerates the hook types (read, write, describe), making the action clear. However, it does not explicitly distinguish itself from sibling tool like dashboard_send, so it misses some differentiation.

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

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

The description implies usage context: you use this when you need to invoke a hook on a dashboard app. It gives no explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools. This is adequate but lacks exclusions or alternative recommendations.

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

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

With no annotations provided, the description must disclose behavioral traits, but it does not. It fails to mention behavior on missing selectors, waiting/retry logic, or potential side effects like navigation if the clicked element is a link.

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

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

The description is a single concise sentence that directly conveys the tool's purpose. There is no clutter or redundancy.

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

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

The tool is simple with one parameter and no output schema, so the basic description is arguably adequate. However, missing information about return values, error behavior, or potential navigation effects leaves a noticeable gap for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 100% for the single 'selector' parameter, and the tool description repeats the same information ('by CSS selector') without adding extra semantic detail. The schema already fully defines the parameter, 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?

The description clearly states the action (click), the target (element), and the method (CSS selector). This distinguishes it from sibling browser tools like browser_type and browser_evaluate, which have different 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?

No guidance is provided on when to use this tool versus alternatives such as browser_evaluate for programmatic clicks or browser_navigate for navigation. While the purpose implies clicking, there is no explicit context or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not specify whether 'text content' includes hidden text, how dynamic content is handled, or whether the result is the rendered or raw text, leaving important behavioral traits undisclosed.

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 only six words, front-loaded with the action and target. Every word is meaningful, with no redundant detail or filler, making it appropriately sized for the simplicity of the tool.

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

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

Although the tool is simple and parameterless, the description is minimal. It lacks any mention of return value format, edge cases, or relation to browser_snapshot, leaving some ambiguity. It is minimally viable but would benefit from clarifying what exactly 'text content' entails.

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

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

The tool has zero parameters, and the input schema has 100% coverage (empty properties). The baseline for zero-param tools is 4, and the description correctly implies the tool operates on the 'current page' without requiring additional configuration.

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

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

The description uses a clear verb 'Get' and specifies the resource 'the text content of the current page,' making the tool's purpose unambiguous. It distinguishes itself from sibling tools like browser_screenshot (visual capture) and browser_evaluate (JavaScript execution) by focusing on text extraction.

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

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

No guidance is provided about when to use this tool versus browser_snapshot or other browser sibling tools. The description only states the function, leaving the agent to infer when text content is preferred over alternative capture methods.

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?

There are no annotations, so the description must carry full behavioral disclosure. It only says 'execute JavaScript and return the result' but does not mention side effects, asynchronous behavior, page navigation, error handling, or what 'result' means. This leaves significant unknown behavior for an agent.

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 with no filler. Every word conveys necessary information, and it is structurally clear.

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

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

Given the potential complexity of a JavaScript evaluation tool (async, return types, side effects) and the absence of annotations or output schema, this description is incomplete. It does not explain what the result looks like, whether promises are resolved, or how errors are returned, which are critical for safe 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?

The schema already describes the sole parameter as 'JavaScript code to execute' with 100% coverage. The description adds no extra meaning beyond the schema, making this a baseline 3.

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

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

The description states a specific verb-resource pair: 'Execute JavaScript in the browser page and return the result.' It clearly distinguishes itself from browser_navigate, browser_click, browser_snapshot, etc., which do other operations. The purpose is unmistakable.

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

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

The description gives no guidance on when to use this tool versus alternatives like browser_content or browser_snapshot. It lacks any context about typical use cases, prerequisites, or scenarios where it is preferred over sibling tools.

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

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

With no annotations, the description must disclose behavior itself. It states the action (navigate) and outcome (returns page title and URL), which is a baseline level of transparency. However, it does not mention side effects like changing the current page state, whether it waits for page load, or failure 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 two sentences with no fluff. It front-loads the core action and then notes return values. Every word earns its place.

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

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

For a simple navigation tool with one parameter and no output schema, the description provides the essential information: what it does and what it returns. It is complete enough for an agent to invoke it correctly, though it could be enriched with usage guidance.

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 only parameter 'url' is described in the schema. The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Navigate the browser to a URL.' This is a specific verb + resource that distinguishes it from sibling browser tools like browser_snapshot or browser_click. It also specifies return values, further clarifying its function.

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 moving the browser to a new URL but provides no explicit guidance on when to use this tool versus alternatives such as browser_content or browser_evaluate. No exclusions or alternative tool references are given.

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

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

With no annotations provided, the description carries the full burden. It specifies the output format (base64-encoded PNG) and the subject ('current page'), but does not disclose whether it captures the full page or viewport, or what happens if no page is loaded. It also doesn't mention any waiting behavior or potential errors.

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

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

Two sentences, no filler, starts with the verb and object, and adds essential return information. 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 zero-parameter tool with no output schema, the description provides the core action and return type, which is largely sufficient. However, it could be more explicit about prerequisites (e.g., an active page) and output characteristics (viewport vs full page) to be fully complete.

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

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

The tool accepts no parameters, so the baseline is 4. The description appropriately omits parameter details, and the schema confirms zero parameters.

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

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

Description clearly states the action ('Take a screenshot') and the target resource ('the current page'), and distinguishes it from sibling browser tools like browser_navigate and browser_content. The return type is also specified, making its purpose unambiguous.

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

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

Provides clear context that this tool captures the visual state of the current page, implicitly indicating when it should be used. However, it does not explicitly mention alternatives or when-not-to-use scenarios compared to sibling tools like browser_snapshot or browser_content.

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?

No annotations are present, so the description carries the transparency burden. It indicates a read operation but does not disclose whether a page must be loaded, error behavior, or the format of the returned tree. It offers minimal behavioral context beyond the fact that it retrieves the accessibility tree.

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, front-loaded with the verb and object, with no filler or redundant 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?

Given the tool's simplicity (no params, no output schema), the description covers the core function and scope, but omits details about return value structure or preconditions such as a loaded page. It is adequate for a straightforward read operation but leaves some ambiguity.

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

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

The tool has zero parameters, and the schema is empty. The baseline score of 4 applies since there is nothing to document; the description correctly makes no parameter claims.

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

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

The description uses the specific verb 'Get' and identifies the exact resource 'accessibility tree' scoped to 'the current page', clearly distinguishing it from sibling tools like browser_content or browser_screenshot.

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

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

No guidance is provided regarding when to use this tool versus alternatives such as browser_content for page text or browser_screenshot for visual rendering. The sentence only states what it does, leaving usage context entirely implied.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the basic action without addressing nuances like whether it focuses the element first, clears existing text, or waits for the element to be ready, which are critical for browser automation tools.

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 filler, making it highly concise and efficiently 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?

The tool is simple, but the description omits any behavioral context such as preconditions (e.g., page must be loaded) or effects (e.g., does it clear the field first). There is no output schema, so return behavior is also unclear, making it minimally adequate.

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

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

Schema coverage is 100%, so both parameters are already well-documented. The description reinforces the selector parameter but does not add significant new 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 uses a specific verb ('Type'), identifies the resource ('input element'), and specifies the method ('by CSS selector'), making it clear and distinct from sibling tools like browser_click and browser_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?

No explicit guidance on when to use this tool versus alternatives. The description implies usage for typing text, but there is no mention of when not to use it or references to sibling functions like browser_click or browser_evaluate.

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?

No annotations are provided, so the description carries the burden. It only restates the function and adds no behavioral context such as return format, timezone handling, or read-only guarantees.

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

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

A single, front-loaded sentence that states the action and the optional parameter with 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?

Adequate for a simple one-parameter read tool, but with no output schema or annotations, it leaves the agent without details about what the returned events contain or timezone behavior. Not fully complete.

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

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

The schema already fully describes the date parameter with format and default (100% coverage). The description's mention of the date format adds no new 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?

Clear verb and resource: retrieves today's calendar events, with optional date override. However, it does not distinguish from sibling get_events, so not a 5.

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

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

Provides clear default usage (today) and an optional date parameter for other days. Does not explicitly state when to prefer this over sibling calendar/event tools or mention 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?

With no annotations, the description carries the full burden for behavioral disclosure. It adds useful context about fuzzy matching and that it returns contact details, but omits limitations, response structure, or potential side effects. This is better than minimal but not comprehensive.

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 action, and every sentence adds value. The first sentence states purpose, the second adds behavioral detail. No redundant or filler content.

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 lacks an output schema, so 'Returns contact details' is vague about the exact fields or format. While the tool is simple with one parameter, the absence of annotations and output schema means the description should provide more detail about the returned data to be fully complete.

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

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

Schema description coverage is 100% for the query parameter, and the description essentially repeats the same information. The description adds no new semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb (Search) and resource (CRM contacts), and specifies searchable attributes (name, alias, tag, keyword). This distinguishes it from sibling search tools like memory_search or docs_search, making the purpose unambiguous.

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

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

The description implies usage context (searching CRM contacts) but does not explicitly mention alternatives or when not to use it. Given many sibling search tools, more explicit guidance would improve selection accuracy.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. However, it only states the basic action and does not disclose potential side effects, delivery behavior, authentication requirements, or limitations of the messaging operation.

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

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

The description is a single, concise sentence that is front-loaded with the verb and resource. Every word adds value with no redundancy or filler.

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

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

For a simple one-parameter tool, the description is minimally adequate but lacks context about the destination dashboard, expected outcomes, or nuances like message formatting or limits. Given its low complexity, a 3 reflects that it is functional but not fully comprehensive.

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 the single 'text' parameter fully (100% coverage) with 'Message text to send'. The description adds no additional semantic 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?

The description 'Send a message to the web dashboard chat' clearly states the action (send) and the specific resource (web dashboard chat), distinguishing it from sibling tools like telegram_send which target different channels.

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, nor any exclusions or prerequisites. It simply states the tool's function without context on appropriate usage scenarios.

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?

Without annotations, the description carries the burden of behavioral disclosure. It does state 'removing all indexed content', which indicates a destructive operation, but it does not mention irreversibility, permission requirements, or any side effects on related data.

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

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

The description is a single, concise sentence that effectively communicates the tool's purpose without unnecessary words. It is front-loaded 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?

For a simple one-parameter destructive operation, the description covers the core semantics but lacks details on success/failure behavior or consequences. Given the existence of the sibling tool docs_clear_compiled, some differentiation 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?

The schema description coverage is 100%, so the parameter 'domain' is fully documented. The description does not add additional meaning beyond the schema, which is acceptable given the high coverage.

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

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

The description clearly states the verb 'Clear' and the resource 'documentation domain', and specifies the effect 'removing all indexed content'. This distinguishes it from the sibling tool docs_clear_compiled, which likely clears a subset of content.

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 action but does not explicitly state when to use this tool versus alternatives like docs_clear_compiled. Usage context is implied by the description's meaning, but no exclusions or alternative guidance are provided.

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

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

Without annotations, the description carries the burden of explaining the destructive scope. It explicitly states that compiled/synthesized articles are removed while raw chunks remain intact, making the data impact clear. It does not mention reversibility or permissions, but the core behavioral trait is well disclosed.

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

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

The description is a single concise sentence that immediately identifies the action, scope, and what is preserved. It is front-loaded and contains no filler.

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

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

For a simple one-parameter destructive tool with no output schema, the description adequately covers what the tool does, what it affects, and what it does not. No additional return value or complex behavior needs explanation.

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 only parameter 'domain' is described in the schema as 'Domain name', and the description references it as 'from a domain' without additional details. Since schema coverage is 100%, the description does not need to add much, but it also does not enrich the meaning of the parameter 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 verb 'Clear' and the specific resource 'compiled/synthesized articles from a domain', and explicitly distinguishes from broader clearing operations by noting that raw chunks are kept intact. This differentiates it from sibling tools like docs_clear.

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

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

The description implies usage context by specifying that only compiled articles are cleared and raw chunks are preserved, but it does not explicitly name alternative tools or provide exclusion criteria. Thus it offers clear context but no direct comparative 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool uses LLM clustering by embedding similarity, generates markdown articles, and stores them back under compiled/ paths in the vector DB. This provides meaningful context, though it does not disclose overwrite behavior or prerequisites for existing raw chunks.

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, consisting of three sentences with the main action front-loaded. It avoids redundancy and every sentence adds value, making it well-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 three parameters, no output schema, and no annotations, the description covers the core behavior, purpose, and storage location sufficiently. It lacks explicit return value and prerequisites, but for a data processing tool of this complexity, it is mostly 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds minimal parameter-specific meaning, only lightly connecting clustering to the threshold parameter. It does not elaborate on how maxClusters or clusterThreshold affect output in detail.

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 compiles raw document chunks into synthesized concept articles with cross-references, specifying the verb, resource, and output. It distinguishes itself from sibling tools like docs_search and docs_ingest by focusing on the aggregation/compilation step rather than retrieval or ingestion.

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 suggests use for improving retrieval quality on complex queries, but does not explicitly state when to use this tool versus alternatives or when not to use it. There is no comparison with docs_search or docs_ingest, and no exclusions are provided.

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

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

With no annotations, the description carries the burden. It discloses that the tool does not synthesize (a key behavior) and that no API key is required. However, it doesn't mention side effects, errors, or return structure beyond 'cluster content', so transparency is adequate but not rich.

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

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

Two concise sentences, front-loaded with the core action. Every word adds value: the 'without synthesizing' caveat and the 'no API key needed' note are important. No fluff.

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, but the description gives a reasonable idea of the return ('cluster content') and usage context. It explains the workflow with docs_ingest_text. It doesn't elaborate on data structures or error cases, but for a moderately complex tool this is acceptable, though not exhaustive.

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 schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description doesn't add parameter-specific details beyond what the schema provides; it only mentions 'domain's raw chunks' which is redundant with the domain 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 'Get topic clusters from a domain's raw chunks WITHOUT synthesizing articles', giving a specific verb and resource. It explicitly distinguishes itself from synthesis tools by emphasizing it does NOT synthesize, and mentions pairing with docs_ingest_text, differentiating it from siblings like docs_compile.

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 explicitly instructs to 'Use with docs_ingest_text to store the synthesized articles', giving an actionable usage pattern. It implies this is for when you want to synthesize inline rather than using an automated compilation tool, though it doesn't name the alternative. There's clear context on when this fits in a workflow.

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?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It fails to mention what happens to existing index entries, whether ingestion is idempotent, how directories are traversed, or any side effects like merging or overwriting. The lack of such info makes behavior unpredictable for a write operation.

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

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

The description is two sentences long, front-loaded with the primary action, and contains no filler. Every sentence adds useful information (ingestion purpose, input form, supported extensions), making it 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 absence of annotations and output schema, the description should clarify post-ingestion behavior, error handling, and index update semantics. It only covers input restrictions without explaining what the agent should expect after calling the tool, leaving a significant gap for a tool that mutates an index.

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 'path' and 'domain' parameters adequately. The description adds no extra meaning beyond what the schema provides, such as examples of domain names or path formatting, so it meets the baseline but does not exceed 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?

The description clearly states the tool ingests files into a domain-specific documentation index, with a specific verb and resource. It also lists supported file extensions, which distinguishes it from sibling tools like docs_ingest_text (which handles raw text) and docs_search (which reads the index).

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 file ingestion by specifying acceptable file paths/directories and extensions, but it provides no explicit guidance on when to use this tool instead of docs_ingest_text or other siblings. No exclusions or alternatives are mentioned, so usage context is only implied.

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

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

With no annotations, the description carries the burden of disclosing behavior. It adds the key trait 'without saving to disk', which is beyond the name, but it does not disclose side effects on existing indexed content (e.g., whether the same key overwrites or fails). For a mutation tool, this is a moderate gap, so a mid score is appropriate.

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

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

A single, front-loaded sentence that states the action, target, and a critical constraint. Every word earns its place; no fluff.

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

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

The tool has no output schema and no annotations, so the description must cover key behaviors. It covers the primary action and the no-disk aspect, but does not clarify behavior on duplicate keys or domain existence. Sufficient for a basic understanding but not fully complete for complex 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?

The input schema provides descriptions for all three parameters (100% schema coverage). The description does not add parameter-level detail, so the baseline of 3 applies.

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

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

The description states a specific verb ('Ingest'), resource ('raw text content into a domain documentation index'), and a key qualifier ('without saving to disk'). This clearly differentiates it from the sibling tool docs_ingest, which likely handles file-based ingestion.

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 this for raw text content and when not saving to disk. It implicitly distinguishes from docs_ingest, though it does not explicitly name alternatives or state when not to use. Still, the constraints are clear enough for basic 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?

With no annotations, the description carries the full burden. 'List' implies a read-only operation, but the description does not clarify what 'stats' includes or whether the operation has any side effects. It gives a basic behavioral overview but lacks depth, such as return format or data scope.

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 is front-loaded with the action and resource. Every word is meaningful, and there is no extraneous information. It is perfectly concise for a simple listing tool.

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

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

Given the low complexity (0 params, no output schema) and the fact that it is a read-only list operation, the description is nearly complete. The only minor gap is the ambiguity of 'stats'—what specific metrics are returned—but for a tool of this simplicity, the description is adequate without over-specifying.

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

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

The tool takes zero parameters, and the schema is empty (100% coverage by default). The description adds no parameter details, but none are needed. Per the rubric, 0 params sets a baseline of 4, and the description does not detract from this.

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 'List all available documentation domains and their stats' uses a specific verb ('List'), specifies the resource ('documentation domains'), and adds the scope ('all') plus output detail ('stats'). This clearly distinguishes it from sibling tools like docs_search (search) and docs_ingest (ingest), making its purpose unambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The description implies usage for obtaining an overview of documentation domains, but it does not state exclusions like 'use docs_search to query specific content' or mention any prerequisites. This is adequate but not 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?

No annotations are present, so the description is the sole source of behavioral information. It adds the domain-specific vector DB context, but doesn't mention return format, how results are ranked, or any potential side effects. For a search tool, this is adequate but not deeply transparent.

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-loads the core purpose, and includes only useful information with zero waste. It is well-structured 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?

Despite the lack of an output schema and annotations, the description is sufficient for a simple search tool with fully documented parameters. It could mention result format or error behavior, but the simplicity of the operation makes this gap acceptable.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds a concrete domain example and points to docs_list for domain options, providing marginal extra value beyond the schema for the domain 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 searches a domain-specific documentation index, gives concrete examples (touchdesigner, openclaw), and points to docs_list for domain discovery, effectively distinguishing it from sibling tools like memory_search.

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 explicitly tells users to use docs_list to see available domains, which is a clear prerequisite and usage guideline. However, it doesn't explicitly contrast with alternative search tools, leaving some implicit differentiation.

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?

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only states that it gets recent events, without mentioning whether it is read-only, what events are included, or any side effects. This lack of context leaves the agent to assume safety and 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 a single, concise sentence that conveys the core function without any filler. It is front-loaded and every word earns its place.

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

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

The tool is simple with one optional parameter and no output schema, so the description is minimally viable. However, it lacks context about what events are included, the return format, or when this tool is appropriate. Given the simplicity, it is adequate but has clear gaps.

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

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

The input schema provides a clear description for the only parameter 'limit', including its default (20). The tool description adds no extra parameter semantics, so with 100% schema coverage, the 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?

The description clearly states the verb (Get) and resource (recent event history), making its purpose understandable. It does not explicitly distinguish from sibling tools like wait_for_event or calendar_today, but the phrase 'event history' implies a log retrieval, which is reasonably distinct.

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

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

The description offers no guidance on when to use this tool versus alternatives such as wait_for_event or acc_log_missed. There is no mention of typical use cases, prerequisites, or scenarios where this tool is preferable.

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?

Without annotations, the description carries the burden of behavioral disclosure. It conveys that this is a read operation ('Get') and hints at the type of data returned, but does not detail side effects, performance characteristics, or system dependencies. For a simple status tool, this is acceptable but not enriched.

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 lists key aspects of the status. Every word contributes meaning, with no redundancy or filler, making it highly 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?

Given the tool has no parameters and no output schema, the description provides sufficient context for a basic status check. It specifies the main categories of information returned, though it does not elaborate on what 'system' refers to or how the status is structured, which is a minor gap.

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

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

The tool has zero parameters, so the description need not explain parameter semantics. Per the rubric, a baseline of 4 is appropriate when there are no parameters, and the description does not need to compensate for schema gaps.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('system status'), listing relevant components (channels, memory, timers, queue). This distinguishes it from sibling tools like get_events or ha_states, which target different resources.

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 through its name and content but provides no explicit guidance on when to prefer this tool over alternatives, nor any exclusions or prerequisites. There is no mention of context in which the status is needed, leaving the agent to infer.

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?

There are no annotations, so the description carries the full burden. It only states the action 'turn off' without disclosing side effects, idempotency, error behavior, or whether the tool waits for state confirmation. For a state-changing operation, more behavioral context is expected.

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, focused sentence with no wasted words. It is front-loaded and easily scanned.

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 one-parameter tool with no output schema, the description is minimally adequate. However, the lack of behavioral context (e.g., what happens if the entity doesn't exist or is already off) makes it less complete than it could be.

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 schema has 100% coverage for entity_id with a clear description. The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description 'Turn off a Home Assistant light' clearly states the verb (turn off) and resource (Home Assistant light), distinguishing it from the sibling ha_light_on. It is specific and unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives like ha_light_on or ha_service. The description does not mention exclusions, prerequisites, or fallback options.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and parameters; it does not mention side effects (e.g., updating entity state, requiring a connection to Home Assistant), potential errors, or any state-changing implications beyond the literal 'turn on'. This is minimal for a mutation tool.

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

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

The description is a single, front-loaded sentence that immediately communicates the tool's purpose. It includes only essential information about parameter options, with no redundant or filler content. Every word 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 simple tool with a clear schema and no output schema, the description is nearly complete. It specifies the action and available options, and the schema covers all parameter details. It does not explain return values or error behavior, which would be expected in the absence of an output schema, but given the low complexity, this is a minor gap.

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

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

The input schema already covers all four parameters with descriptions, so coverage is 100%. The description adds no additional meaning beyond what the schema provides; it merely restates the brightness range and color options. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action ('Turn on') and resource ('a Home Assistant light'), with a specific verb and target. It distinguishes itself from the sibling ha_light_off by its explicit on action, and from ha_service by focusing specifically on light turning on.

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

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

The description implies when to use the tool (when you want to turn on a light) but does not provide explicit guidance on alternatives or exclusions. It does not mention that ha_light_off should be used for turning off, or that ha_service might be a more general option. This is acceptable for a simple tool but below the explicit level expected for 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'call any service' without explaining potential side effects (e.g., turning devices on/off), error behavior, or permissions. Since this tool can trigger arbitrary actions, the lack of safety or consequence context is a significant 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?

The description is a single, front-loaded sentence that clearly communicates the tool's purpose. There is zero wasted text, making it exceptionally 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 annotations and no output schema, the description must provide substantial context. While the core purpose is clear, it lacks usage guidelines, behavioral transparency, and return-value information. In the context of sibling tools, it also does not clarify when to use this generic service caller versus the specialized ha_* tools.

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 three parameters. The description adds a bit of value by giving example domain/service pairs (switch/turn_on, climate/set_temperature), but it does not enhance understanding of the 'data' payload beyond what the schema states (must include entity_id). 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 states a specific verb (call) and resource (Home Assistant service) with relevant examples (switch/turn_on, climate/set_temperature). It clearly distinguishes itself from specialized siblings like ha_light_on and ha_light_off by being the generic catch-all for any service.

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

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

No guidance is given on when to use this tool versus alternatives. The phrase 'any service' implies broad usage, but it does not explicitly say to prefer specialized tools like ha_light_on for their respective domains, nor does it mention any exclusions or prerequisites. An agent would have to infer usage from sibling names.

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

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

With no annotations, the description carries the full burden. It only says 'List', which implies read-only, but does not disclose the return format (entity IDs vs. full states), potential large response sizes, or any connection requirements. This is a minimal disclosure.

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, no fluff, and front-loads the action. Every word 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?

The tool is simple with one optional param, but there is no output schema and no annotation. The description does not specify what exactly is returned (entity IDs, states, etc.) nor contrast with related tools, so it is minimally adequate but not 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% for the single 'domain' parameter, so the schema already documents it. The description adds a couple of extra examples ('climate') but otherwise repeats 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 lists Home Assistant entities, with an optional domain filter. This specific verb+resource combination distinguishes it from sibling control tools like ha_light_on and ha_light_off.

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

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

The description implies its use for discovering entities, but does not explicitly state when to use it over alternatives like ha_service or when to omit the domain filter. It gives no examples of scenarios or 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?

No annotations are provided, so the description carries the burden. It clearly indicates a read operation ('Fetch full content') and scopes input to paths from search results. It does not mention error handling or case sensitivity, but for a simple retrieval operation the key behavior is disclosed.

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

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

Two short sentences, no filler. The first states what it does; the second states when to use it. Every word earns its place.

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

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

For a simple one-parameter tool with no output schema, this description is complete enough. It explains the purpose, the workflow, and the input source. Minor gaps like return format are not critical since no output schema is expected.

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 explains that 'paths' is an array of strings (max 5). The description adds the context that paths come from search results, which is mildly useful but largely redundant given 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 uses a specific verb ('Fetch') with a clear resource ('full content of specific memory/vault files by path') and distinguishes itself from the sibling search tools by framing this as the drill-down step after memory_search.

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 states when to use: 'Use after memory_search to drill down into results.' This clearly ties it to a workflow and implies not to use it for searching, which differentiates it from memory_search and memory_search_multi.

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

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

With no annotations, the description carries the full burden. It discloses the hybrid search method and the default return format (2-3 sentences per result), and implies that full files are not returned here. However, it does not explicitly state that the tool is read-only or describe any side effects, rate limits, or error behaviors, making it minimally sufficient but not rich.

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

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

The description is a single, compact sentence that front-loads the core purpose and efficiently introduces key usage nuances. Every clause contributes value, and there is no wasted text or filler.

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

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

For a simple search tool with 3 parameters and no output schema, the description covers the essential points: what it searches, how results are formatted, how to adjust detail, and how to get full files. It lacks an explicit mention of limit default or read-only status, but those are either in the schema or implied, so the completeness 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 description coverage is 100%, so the baseline is 3. The description restates the detail levels ('index', 'summary', 'full') but adds no new information beyond what the schema already provides for these parameters. It does not elaborate on 'limit' or 'query' semantics, so it adds marginal value.

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: 'Search the memory index using hybrid vector + FTS search.' It uses a specific verb ('Search') and resource ('memory index'), and distinguishes itself from memory_get by noting that memory_get is for fetching specific files. This is a clear, differentiated purpose.

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

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

The description gives useful guidance on when to use this tool vs memory_get: 'use memory_get to fetch specific files.' It also explains how to adjust detail levels. However, it does not explicitly mention when not to use the tool or contrast it with memory_search_multi or other search siblings, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses deduplication by chunk, max-score sorting, and cost advantage. It lacks details on error behavior, but for a read-only search operation it offers solid 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?

Three concise sentences with no filler. The most critical information (what, why, how) is front-loaded, and each sentence contributes either purpose, usage guidance, or behavioral detail.

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

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

Given the absence of annotations and output schema, the description covers purpose, usage guidance, behavioral specifics (dedup, sorting), and cost considerations. It fully equips an agent to decide when to invoke and what to expect, especially with sibling memory_search as a frame of reference.

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 descriptions cover all three parameters (100% coverage), establishing a baseline. The description adds practical query-construction guidance (vary vocabulary, split compounds, drop prefixes) and notes that more than 2-5 queries is wasted work, enriching the queries parameter semantics 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 function: running multiple query variants through memory search in a single call. It distinguishes itself from the sibling memory_search by explaining the batching advantage and when it's appropriate.

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 explicitly specifies when to use this tool (when initial memory_search underperforms, with concrete failure indicators like weak top score or missing fragment) and how to construct queries. It also contrasts with multiple separate memory_search calls by highlighting cost efficiency.

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

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

With no annotations, the description carries the burden for behavioral disclosure. It adds the detail that content is indexed automatically, which is helpful, but it does not mention what happens on overwrite, whether permissions are needed, or any side effects beyond storing.

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, consisting of one sentence that front-loads the main action. It avoids unnecessary words and repetition of schema information, though it could be slightly more detailed without losing conciseness.

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 two-parameter tool with a fully described schema, the description is minimally viable. It covers the core action and mentions indexing, but lacks usage guidance and explicit behavioral details, making it incomplete for a standalone tool with no annotations.

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

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

The schema already fully describes both parameters (key as 'File path to store at' and content as 'Content to store'), covering 100% of parameter meaning. The description adds no extra parameter details, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with specific action verbs: 'Store content to memory and index it.' It distinguishes itself from sibling tools like memory_search and memory_get, which are retrieval-focused, by emphasizing the write and indexing behavior.

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 guidance on when to use this tool versus alternatives. The description only states what it does, without mentioning related tools like memory_search for retrieval or conditions for using this tool.

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

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

With no annotations provided, the description itself must convey behavioral traits. The verb 'Get' clearly implies a non-destructive read operation, and 'all files that link' indicates the scope of the result. However, it does not disclose edge-case behavior (e.g., nonexistent note) or output format details, leaving some burden unmet.

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 extraneous words, directly stating the tool's purpose. It is well-structured and front-loaded, making it easy for an agent to parse quickly.

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 (one parameter, no output schema or annotations), the description is minimally adequate. It tells what the tool does but does not explain the return format or handle edge cases, which an agent might need to know. The completeness is fair but not exceptional.

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

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

Schema description coverage is 100%, with the parameter 'file' described as 'File path to find backlinks for (relative to vault root)'. The description adds little beyond the schema—it repeats the concept of 'given note' without enriching parameter semantics. Per rubric, baseline 3 is appropriate when the schema already documents the parameter 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 the tool's function: 'Get all files that link to a given note' uses a specific verb ('Get') and resource ('files that link to a given note'), distinguishing it from sibling tools like obsidian_search or obsidian_orphans. The name 'obsidian_backlinks' aligns perfectly with the description.

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 use case (finding backlinks for a note) but provides no explicit guidance on when to use this tool versus alternatives such as obsidian_search or obsidian_orphans. It does not mention exclusions or provide context about prerequisites, but the single-sentence purpose is enough for a basic understanding.

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?

No annotations are provided, so the description must disclose behavioral traits. It mentions the prerequisite (CLI enabled) but omits potential side effects, safety risks, or that arbitrary code execution can modify the vault. This is a significant gap for an eval 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?

The description is a single, front-loaded sentence that directly states the tool's purpose and a key prerequisite. Every word earns its place with no redundancy or filler.

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

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

For a tool with one parameter and no output schema, the description covers the core functionality and runtime requirement. However, it does not explain what the tool returns (e.g., evaluation result) or error behavior, which is relevant for a code execution tool. It is minimally adequate but leaves 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?

The schema already covers the single parameter 'code' with an adequate description. The tool description adds no additional parameter semantics beyond restating that the code is JavaScript. With 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly identifies the action ('Execute JavaScript') and the target ('Obsidian API'), distinguishing it from sibling tools like obsidian_search or vault_reindex. It is a specific verb+resource construction with 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 provides a clear prerequisite context: requires Obsidian running with CLI enabled. This implies when to use the tool (when Obsidian is available) but does not explicitly list alternatives or when-not scenarios. It is clear context without 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?

No annotations are provided, so the description must carry the burden. It discloses the key side effect of 'automatically updating all wikilinks', which is useful. However, it does not mention other behavioral aspects such as overwrite behavior, permissions required, or failure scenarios, leaving some gap for a mutation tool.

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

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

The description is a single sentence that is front-loaded with the main action and includes the critical side effect. Every word earns its place, with no redundancy or extraneous 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 simple move tool with two well-documented parameters and no output schema, the description is largely complete. It covers the core operation and the notable side effect. It does not explicitly address edge cases like destination conflicts, but this is acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, with both 'file' (source) and 'to' (destination) parameters described in the schema. The description adds no additional parameter semantics beyond what the schema already states, so the 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?

The description clearly states the tool's action: 'Move or rename a file in the vault'. This is a specific verb+resource combination that distinguishes it from sibling tools like obsidian_search or obsidian_tags, which handle different operations. The additional detail about updating wikilinks further clarifies its unique 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 implies when to use this tool (when moving or renaming files) and no sibling tool overlaps with this functionality, so the context is clear. However, it lacks explicit when-not-to-use guidance or mentions of alternative tools, so it doesn't fully earn 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?

With no annotations, the description carries the full burden of behavioral disclosure. The phrase 'notes with no backlinks' precisely states the selection criterion and implies a read-only operation. It doesn't discuss edge cases (e.g., what counts as a backlink) or return format, but for a zero-parameter finder this is acceptable and transparent.

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: 'Find notes with no backlinks (orphan notes).' Every word earns its place, and the parenthetical adds value by using a well-known term. No redundancy or filler.

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

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

For such a simple tool with no parameters and no output schema, the description is nearly complete. It clearly states the functional outcome. It could optionally describe the return value (e.g., 'returns a list of note paths'), but the purpose is so unambiguous that this is a minor gap.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. The baseline for zero parameters is 4, and the description adds no unnecessary parameter details. There is nothing further to explain.

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

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

The description uses a specific verb ('Find') and resource ('notes with no backlinks'), clearly identifying the tool's action and target. The parenthetical '(orphan notes)' adds a familiar synonym that distinguishes it from siblings like obsidian_backlinks and obsidian_unresolved.

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 use case (find orphan notes) but does not explicitly state when to prefer this tool over alternatives, nor does it mention exclusions or prerequisites. There is no reference to the many sibling tools, so the agent must infer the intended context from the name and purpose alone.

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

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

With no annotations, the description must convey behavioral traits. The verb 'Read' clearly indicates a non-mutating operation, which provides appropriate transparency for a read-only tool. It does not mention error cases or return format, but these are not critical for a straightforward read operation.

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

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

The description is a single, concise sentence that is front-loaded with the action and object. Every word earns its place with no unnecessary detail.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides sufficient context for an agent to understand what the tool does. It does not explain return values, but the phrase 'Read frontmatter properties' adequately implies the result. Minor gaps around edge cases exist but are not significant for this simple 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 schema covers 100% of the parameter 'file' with a clear description ('File path (relative to vault root)'). The tool description adds no additional parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Read') and resource ('frontmatter properties from a note'). This distinguishes it from sibling tools like obsidian_property_set (which likely writes properties) and obsidian_search (which searches content).

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 but does not explicitly state when to use this tool over alternatives. No exclusions or alternative tool names are mentioned, which is acceptable for a simple read tool but lacks direct comparison.

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?

No annotations are provided, so the description carries full burden. It does not disclose whether setting an existing property overwrites it, whether the file must exist, or what happens if the note is missing. For a mutation tool, this lack of behavioral context is a 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?

The description is a single, direct sentence that immediately conveys the tool's purpose. It is front-loaded and contains no filler or redundant 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?

The tool is simple with 3 required parameters fully documented in the schema. However, because it is a mutation tool with no annotations and no mention of overwrite behavior or file existence requirements, the description is minimally viable but not fully complete.

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

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

Schema description coverage is 100%, with each parameter (file, key, value) individually described in the schema. The description adds no extra meaning beyond the schema, 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?

The description clearly identifies the action ('Set') and the resource ('a frontmatter property on a note'). It distinguishes from sibling tools like obsidian_properties (list properties) and obsidian_tags_rename (rename tags) by specifying the property-setting operation.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention when to prefer obsidian_property_set over obsidian_properties or other obsidian tools, nor any prerequisites or conditions.

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

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

With no annotations provided, the description's minimal text ('Search the vault using Obsidian's built-in search') does not disclose behavioral traits such as read-only nature, side effects, return format, or any limitations. For an unannotated tool, this is insufficient.

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

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

The description is a single, concise sentence that front-loads the core action 'Search the vault' and adds one clarifying detail ('using Obsidian's built-in search'). No unnecessary words or repetition.

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

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

Given the tool's simplicity (one well-documented parameter, no output schema), the description is somewhat adequate but misses expected context such as what the search returns (file paths? snippets?) and how it differs from other search tools. It feels incomplete for an agent selecting among many search-related siblings.

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

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

The schema fully describes the single parameter 'query' with 'Search query (Obsidian search syntax),' giving 100% coverage. The description adds no additional semantic details, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search the vault using Obsidian's built-in search'—a specific verb and resource. While it doesn't explicitly distinguish from sibling tools like vault_search, the mention of 'Obsidian's built-in search' hints at a specific implementation.

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

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

No guidance is provided on when to use this tool versus alternatives such as vault_search, memory_search, or docs_search. The description lacks any context about appropriate use cases or 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?

No annotations are provided, so the description carries the burden. The verb 'List' implies a read-only, non-destructive operation, but the description does not add details about performance, ordering, or output format. While simple and safe, it lacks explicit behavioral context.

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

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

The description is a single, focused sentence that is front-loaded with the action and resource. Every word is essential, with no redundancy or 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?

Given the tool's simplicity (zero parameters, no annotations, no output schema), the description is adequately complete for its purpose. It clearly communicates the scope ('all tags') and the vault context, though it doesn't specify the exact return format, which is a minor gap.

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

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

The tool has zero parameters, and the schema is empty. Per the baseline for 0 params, a score of 4 is appropriate. The description correctly focuses on the result rather than parameters, adding no unnecessary clutter.

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 'List all tags used in the vault' clearly states the action (list) and the resource (all tags in the vault). It distinguishes itself from sibling tools like obsidian_tags_rename and obsidian_search by specifying the full set of tags without modification.

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 usage is implied: if you need an enumeration of all tags, this is the tool. However, there is no explicit mention of when to use it versus alternatives like obsidian_search or obsidian_properties, and no exclusions provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the operation is a bulk rename affecting all files, which is useful. However, it does not mention side effects, reversibility, or how the rename is applied (e.g., frontmatter, body text), leaving uncertainty for a mutation tool.

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

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

The description is a single, front-loaded sentence: 'Bulk rename a tag across all files in the vault'. It contains no filler words and communicates the core action and scope efficiently.

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 two-parameter tool with no output schema or nested objects, the description provides the essential purpose and scope. It lacks details on return values or confirmation, but the operation is straightforward enough that the current description is mostly 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?

The input schema provides descriptions for both parameters (oldTag and newTag) with 100% coverage, so the tool description adds no additional parameter semantics. The schema already gives the meaning, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'rename', the resource 'tag', and the scope 'across all files in the vault', which is specific and distinguishes it from sibling tools like obsidian_move (moving files) or obsidian_tags (likely listing tags). This is a strong, purpose-defining statement.

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 bulk, vault-wide tag renames but provides no explicit guidance on when to use this tool versus alternatives. It doesn't name sibling tools or give exclusion criteria, but the 'across all files' phrasing signals the intended bulk 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?

No annotations are present, so the description carries full responsibility for disclosing safety and side effects. 'Find' implies a read-only operation, but it does not explicitly state that the tool does not modify the vault, or describe any permissions, caching, or return behavior. This is a modest gap for a tool that appears non-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 a single, front-loaded sentence that immediately conveys the tool's purpose. Every word earns its place, with no unnecessary verbosity or 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?

Given the tool's simplicity (zero parameters, no output schema), the description is largely sufficient. It clearly identifies what the tool does and its scope ('in the vault'). However, it could be more complete by mentioning the output format (e.g., a list of links) or clarifying if 'broken' and 'unresolved' are synonymous, but overall it provides a reasonable understanding for an AI agent.

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

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

The tool has zero parameters, so the description need not elaborate on parameter meanings. The baseline for zero-parameter tools is 4, and the description does not introduce any confusion or missing information about inputs.

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

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

The description uses a specific action 'Find' with a clear resource 'broken/unresolved wikilinks in the vault'. This distinguishes it from sibling tools like obsidian_backlinks, which lists backlinks, and obsidian_orphans, which finds orphan notes. The purpose is unambiguous and directly stated.

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

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

The description implies usage: use this tool to find unresolved wikilinks. However, it does not explicitly contrast it with alternatives (e.g., obsidian_search, obsidian_backlinks) or provide when-not-to-use guidance. The specific naming provides some contextual signal, but there is no explicit direction on when to prefer this tool over others.

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

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

With no annotations provided, the description carries the full burden. It only says 'Execute any registered tool' without disclosing side effects, security implications (e.g., running arbitrary bash), error behavior, or return format. This is a significant gap for a tool that can invoke arbitrary functionality.

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

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

The description is a single, concise sentence that front-loads the main purpose and then lists examples. Every word earns its place; there is no redundancy or fluff.

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 generic tool with no output schema and no annotations, the description is too sparse. It fails to specify expected return values, error handling, or the security context of executing tools like bash. The complexity of a dispatcher warrants more guidance than this.

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 'name' and 'params' both described. The description adds a list of tool name examples, which gives some context, but it does not elaborate on how 'params' should be structured depending on the chosen tool. This is only a slight improvement over 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 that this tool executes any registered tool, with specific examples (bash, read, write, edit, glob, grep, git, web_fetch, web_search, memory_*). This distinguishes it from the many sibling tools that each perform a specific, dedicated action.

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

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

Usage guidance is implied rather than explicit. Saying 'Execute any registered tool' suggests it is a generic dispatcher, but the description does not explicitly say when to prefer this over dedicated siblings or mention any exclusions or 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?

With no annotations, the description carries full burden and does well: it states the tool reads session files, summarizes them, uses Haiku to extract specific insight types, and stores results in memory. It falls short of detailing potential side effects or exactly how memory storage behaves, but the core behaviors are transparent.

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 wasted words. The first sentence states what it does; the second adds process and usage context.

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

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

The description covers the main workflow and usage timing, but it does not specify what the tool returns (no output schema exists) or elaborate on the 'stores in memory' behavior (e.g., which memory store, overwrite policy). These gaps are notable but not severe given the tool's moderate 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?

The input schema already documents hours_back with 100% coverage ('How many hours back to look for transcripts (default 24)'). The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description clearly states a specific verb and resource: 'Extract insights from recent Claude Code session transcripts (JSONL logs).' It distinguishes itself from sibling tools like memory_search or docs_ingest by focusing on session transcripts and a specific pipeline (read, summarize, extract via Haiku).

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 context with 'Run during daily reflection,' telling the agent when to use it. However, it does not mention when not to use it or alternatives, so it misses the highest mark.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the action ('Add an item') without mentioning side effects, required permissions, failure modes, or what happens on success. Mutation behavior is implied 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 a single front-loaded sentence with no fluff. While extremely concise, it lacks any structure to convey the additional context needed for a tool with 8 parameters, but it is appropriately small in size.

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 annotations and no output schema, the description is severely incomplete. It does not explain return values, required setup, default behavior, or the meaning of fields like assignee and priority. An agent would struggle to use it correctly without additional information.

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

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

The input schema covers 100% of parameters with descriptions, so the description doesn't need to add parameter details. However, it doesn't highlight defaults or interdependencies (e.g., status defaults to the first bucket status). Baseline 3 applies.

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

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

The description uses 'Add' as a specific verb and identifies the resource as 'an item to a Spaces bucket', making the operation clear. It implicitly distinguishes from siblings like spaces_update_item and spaces_create_bucket, though it doesn't explicitly address the difference.

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

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

No guidance is given on when to use this tool versus alternatives such as spaces_update_item or spaces_create_bucket. There are no prerequisites, typical use cases, or exclusions 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?

No annotations are provided, so the description carries the full burden. It only states the creation action and optional nesting, but fails to disclose side effects, permissions, idempotency, or response format. This is a significant gap for a mutation tool.

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

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

Single sentence, 10 words, front-loaded with the verb and resource. Every word earns its place; zero redundancy.

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 annotations, no output schema, and only a one-sentence description, the tool is under-specified. The agent gets no information about return values, error conditions, or behavior on duplicate names. The schema covers inputs but not outcomes, leaving the description incomplete.

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 fully documented in the schema. The description adds no extra meaning beyond the schema, only reinforcing the parent nesting aspect already captured by parentId. 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 action (Create) and resource (Spaces bucket), with the optional nesting detail. It distinguishes from sibling tools like spaces_add_item (adding an item) and spaces_list_buckets/get_bucket (reading buckets).

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 (to create a bucket) but does not explicitly state when to use it vs alternatives like spaces_add_item or spaces_update_item. There is no mention of exclusions or conditions beyond optional nesting.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the output type ('details and items') and does not mention side effects (none expected), default behavior of 'recursive' (false), or output format. This is comparable to the 'update_drive' example that scored 2 for lacking such context.

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

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

The description is a single, front-loaded sentence: 'Get a Spaces bucket's details and items'. It contains no fluff and every word contributes to the 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?

This simple tool has no annotations and no output schema, so the description needs to provide more behavioral context. It leaves ambiguity about what 'details' includes, how items are returned, and the meaning of the 'recursive' parameter in practice, making it incomplete for an agent selecting and invoking the 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 description coverage is 100%: both bucketId and recursive have clear descriptions. The description adds no extra parameter semantics beyond the schema, so the 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?

The description uses the verb 'Get' with a specific resource 'Spaces bucket' and clarifies it returns 'details and items', distinguishing it from sibling tools like spaces_list_buckets (plural) and spaces_search. It is clear and specific enough for basic selection, though it could be more explicit about the scope (single bucket vs. all).

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 a retrieval use case (get bucket details) but provides no explicit when-to-use guidance or alternatives. It does not contrast with spaces_list_buckets or spaces_search, leaving the choice to the agent based on the tool name and schema.

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

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

With no annotations, the description carries full behavioral burden. It discloses that the operation lists buckets and returns item counts in a tree structure, but it does not explicitly state whether it is read-only, what permissions are required, or any side effects. The verb 'List' suggests a read operation, but additional context is limited.

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 concise sentence of 10 words, front-loading the action and resource, and adding relevant output detail without redundancy. Every word earns its place.

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

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

For a parameterless listing tool, the description is largely complete: it specifies the action, scope, and output format ('item counts (tree structure)'). The lack of an output schema means return structure is not fully specified, but the description provides sufficient expectation-setting for a simple list 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?

The tool has zero parameters, so the input schema is trivially complete with 100% coverage. The description does not need to add parameter details, and the baseline for 0 params is 4.

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

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

The description clearly states the verb 'List' and the resource 'all Spaces buckets', with additional detail on output ('item counts (tree structure)'). This distinguishes it from sibling tools like spaces_get_bucket, which likely retrieves a single bucket, and spaces_create_bucket for creation.

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 viewing an overview of all buckets via 'List all Spaces buckets', but it does not explicitly mention when to use it over alternatives like spaces_get_bucket or spaces_search. No alternatives are named, and no exclusions are given.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It only states 'Search' and gives scope, but does not mention that it is read-only, what it returns, or any limitations. The read-only nature is implied but not stated.

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 with no filler or redundant 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?

The tool is simple (1 param, no output schema), and the description states scope clearly. However, it lacks detail on result format or behavior, making it minimally sufficient but not 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% (the only parameter 'query' is described as 'Search query'). The description adds no additional meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description uses a specific verb ('Search') and resource ('items across all Spaces buckets'), clearly distinguishing it from sibling search tools (memory_search, docs_search) and Spaces bucket management tools (spaces_list_buckets, spaces_get_bucket).

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

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

The phrase 'across all Spaces buckets' provides clear context for when to use this tool. It does not explicitly mention alternatives or exclusions, but the scope is unambiguous.

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

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

With no annotations, the description must fully disclose behavioral traits, but it only says 'Update'. It does not explain whether unspecified fields are left unchanged or reset, whether the update is atomic, what happens on invalid input, or what the response contains. For a mutation tool, this is a significant 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?

The description is a single, concise sentence with no wasted words. It is front-loaded and easy to parse, though the extreme brevity may under-serve the tool's complexity. Nonetheless, it is structurally 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?

The tool has 8 parameters, no output schema, and no annotations. The description only states the basic function, omitting critical context such as merge vs. replace behavior, permissions required, response format, and error conditions. It is not complete enough for an agent to confidently invoke the 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 schema already documents all 8 parameters with meaningful descriptions (e.g., 'New title', 'New status'), so the description does not need to add parameter details. It provides no extra parameter semantics beyond the schema, but given the high coverage, the baseline 3 is appropriate.

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

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

The description clearly states the action ('Update') and the resource ('an existing Spaces item'), which directly distinguishes it from sibling tools like spaces_add_item (create) and spaces_search (query). It is specific and unambiguous.

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

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

The word 'existing' implies a key usage constraint—only for items already present—but the description does not explicitly contrast with alternatives or state when not to use it. The distinction from spaces_add_item is implicit rather than explicit, so it earns only a mid-range score.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It only states the primary action and intended use case, but does not discuss potential side effects (e.g., replacing existing reactions), error handling, or permission/rate-limit considerations. It is adequate for a simple tool but leaves these gaps.

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

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

The description is a single, front-loaded sentence that immediately states the action, followed by a short usage note. Every word earns its place with no redundancy or fluff.

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 fully described parameters and no output schema, the description provides sufficient context: what it does, when to use it, and how it differs from alternatives. The low complexity means no additional context is necessary.

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

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

Schema coverage is 100%, so the schema already documents all three parameters (chatId, messageId, emoji) with examples for the emoji. The description does not add additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('React to a Telegram message with an emoji') and resource, and explicitly distinguishes itself from sending a full reply, thus differentiating from sibling tools like telegram_send.

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 indicates when to use the tool ('Use for lightweight acknowledgment') and provides an alternative to avoid ('instead of sending a full reply'), guiding tool selection among Telegram 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?

With no annotations, the description carries full behavioral burden. It merely says 'Read recent incoming Telegram messages' with no mention of side effects (e.g., marking as read), ordering of messages, or return format. The agent has no information about potential mutating behavior or what to expect from the call.

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

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

The description is a single short sentence that is front-loaded with the action 'Read.' It is optimally concise with no wasted words, conveying the core purpose efficiently.

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 annotations and output schema, the description should provide more context about return values, message ordering, or whether messages are marked as read. It is too skeletal for an agent to confidently invoke the tool without additional assumptions.

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 schema already fully describes the single 'limit' parameter (number, default 20), giving 100% coverage. The description adds no additional parameter context, so it meets the baseline for high 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?

The description clearly states the verb 'Read' and the resource 'recent incoming Telegram messages,' which is specific and distinguishes it from sibling tools like telegram_send or telegram_react. No ambiguity about the tool's primary function.

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. It simply states what it does without any context about typical use cases, prerequisites, or exclusions. No indication of when to prefer this over telegram_send or other Telegram tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It simply states 'Send a message to a Telegram chat' without mentioning potential failures, rate limits, authentication requirements, or side effects (e.g., whether it triggers typing status). This is minimal and fails to inform the agent about important behavioral traits.

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

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

The description is a single concise sentence with no fluff. It front-loads the main action and resource. While it is short, it does earn its place by clarifying the tool's purpose. It could be slightly more informative without becoming verbose.

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

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

The tool is simple with only two required parameters and no output schema, so the description is adequate for basic understanding. However, it lacks any mention of prerequisites or edge cases (e.g., message length limits, error handling). The absence of usage guidelines and behavioral details makes it less complete in context.

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 covers 100% of parameter descriptions for chatId and text. The description adds no additional parameter meaning beyond what the schema already provides. Since the schema is self-explanatory, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Send a message') and the resource ('a Telegram chat'). It distinguishes from sibling tools like telegram_read and telegram_send_photo, implying it is the basic text-sending tool. However, it could be more explicit that it sends a plain text message, not a photo or other media.

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

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

No guidance is given on when to use this tool versus alternatives. It does not mention that telegram_send_photo should be used for images, or that telegram_read should be used for reading messages. The sibling context exists but the description itself provides no usage direction or 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?

No annotations are provided, and the description only states the action without disclosing any behavioral details such as side effects (message sent to chat), required permissions (e.g., bot token), error handling, or return values. This leaves the agent reliant on guesswork.

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, direct sentence that is front-loaded with the essential action. It is appropriately sized and avoids unnecessary detail.

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

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

The tool is simple with full parameter coverage, but the description lacks context about expected return values or failure modes. Since there is no output schema, the agent has no idea what the tool returns after sending. It is minimally complete for a basic operation but could benefit from mentioning confirmation behavior.

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

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

The input schema has 100% coverage, documenting chatId, filePath, and caption clearly. The description adds the phrase 'from a local file path' which clarifies filePath but does not substantially enhance parameter understanding 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 tool's function: 'Send a photo to a Telegram chat from a local file path.' This distinguishes it from sibling tools like telegram_send (likely for text), telegram_react, and telegram_typing by specifying the exact action and resource.

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 (when you need to send a photo from a local file), but there is no explicit guidance on when to choose this over telegram_send or other Telegram tools. No alternative tools are mentioned, so the guidance remains implicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It properly explains that the indicator lasts up to 5 seconds or until a message is sent, and that repeated calls are needed for long-running tasks. This adds important lifecycle information beyond the basic 'send typing indicator' statement, though it doesn't cover error cases or authentication.

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

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

The description is two concise sentences, front-loaded with the core purpose and immediately followed by essential behavior and usage guidance. Every sentence contributes value with no redundancy or 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?

This is a simple one-parameter tool with no output schema. The description provides all needed context: what it does, how long the indicator persists, and when to call repeatedly. It is sufficiently complete for correct selection and 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?

The sole parameter (chatId) is already described in the schema as 'Telegram chat ID' with 100% coverage. The description does not add any extra parameter-level detail, so it meets but does not exceed the baseline for a well-documented schema.

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

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

The description states the specific action (send a typing indicator) and the resource (a Telegram chat), making the tool's purpose immediately clear. It distinguishes this from sibling tools like telegram_send or telegram_react, which handle different message actions. The added timeout detail further clarifies its unique function.

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 'Call repeatedly for long-running tasks,' providing a clear usage scenario. It doesn't mention alternatives or exclusions, but the purpose itself implies when to use this tool versus sending an actual message. The guidance is sufficient for an agent to decide when to invoke 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?

No annotations are provided, so the description must carry full behavioral burden. It only states the action without disclosing side effects, idempotency, error behavior, or whether the timer is immediately removed or simply marked as cancelled.

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, and zero wasted words. It is appropriately sized for a simple tool with one parameter and no additional context needed.

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 low complexity, the tool performs a mutation with no annotations, no output schema, and no explanation of consequences or usage context. The description alone is insufficient for an agent to fully understand when and how to use it safely.

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

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

Schema coverage is 100%, with 'name' described as 'Timer ID or name to cancel'. The description adds no additional parameter meaning beyond the schema, 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?

The description 'Cancel a scheduled timer' uses a specific verb and resource, clearly distinguishing from the sibling tool 'timer_schedule'. It precisely communicates the tool's function without 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 provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It does not mention that it is the counterpart to timer_schedule or any specific context for cancellation.

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?

No annotations are provided, so the description must disclose behavioral details. It only states the action without covering side effects, persistence, return value, or overwrite behavior, making it insufficient for an agent to fully predict the tool's 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 a single concise sentence that front-loads the core purpose with no redundant words, perfectly sized for its content.

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 schema covers all parameters, but the description lacks any mention of return values or operational context such as how timers are managed after scheduling. Adequate for a simple tool but not highly informative.

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 tool description adds no additional parameter semantics beyond repeating the type values; the schema already explains each parameter adequately.

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 ('Schedule') and the resource ('a timer'), and explicitly lists the three supported time types (cron, interval, one-shot), distinguishing it from the sibling tool timer_cancel.

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

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

The description implies its use by listing timer types but does not explicitly state when to use it versus timer_cancel or other tools. No exclusions or alternative conditions are mentioned, so the guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond the bare minimum by explaining that default is incremental (only changed files) and full rebuilds from scratch, which gives useful insight into side effects. However, it does not mention potential performance impacts or whether the operation is reversible.

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

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

The description is two sentences, front-loaded with the primary action, and every word earns its place. It is concise and well-structured without redundancy.

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 trigger tool with one parameter and no output schema, the description is largely complete. It explains the purpose, the default behavior, and the effect of the parameter. It could mention potential consequences or prerequisites, but given the low complexity, 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?

The schema already documents the 'mode' parameter with an enum and a brief description (100% coverage), so the baseline is 3. The tool description adds meaningful semantic detail by explaining what each mode does ('only changed files' vs 'rebuild from scratch'), adding value 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 verb 'Trigger' and resource 'vault reindex', making the action unambiguous. However, it does not explicitly distinguish this tool from siblings like vault_search or docs_compile, though the name itself is fairly distinct.

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

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

The description implies usage when a reindex is needed and explains the two modes (incremental vs full), but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The context is clear but not prescriptive.

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

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

With no annotations, the description must carry the behavioral burden. It discloses the hybrid search mechanism and default compact results, but does not mention whether the tool is read-only, relies on a pre-built index (possible staleness), or returns any metadata. It adds some behavioral context but leaves important gaps for a tool with no 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, no fluff, front-loaded with the main action. Every clause adds value—the first states purpose and method, the second gives result defaults and a relevant alternative. 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?

The description covers the core functionality and some usage context, but lacks a full picture without an output schema or annotations. It doesn't explain the return structure beyond 'compact results', nor does it mention that the search relies on an index that may need reindexing (as suggested by the sibling vault_reindex). Adequate but with clear information gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds contextual semantics beyond the schema by explaining the default detail behavior and advising when to use detail='full' versus memory_get. This helps the agent choose parameter values more effectively than 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 specifies a clear action ('Search'), a specific resource ('Obsidian vault index'), and a distinguishing method ('hybrid vector + FTS search'). It immediately conveys the tool's purpose and differentiates it from plain text search or memory search, making it distinct from siblings like obsidian_search and memory_search.

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 explicit usage guidance on result detail levels ('use detail='full' for content') and names an alternative tool ('memory_get') for fetching specific files. While it doesn't explicitly exclude sibling tools like obsidian_search, it gives enough context for the agent to decide when to use this tool and when to use an alternative.

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

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

With no annotations, the description carries the full burden. It effectively discloses the blocking behavior and that it waits for specific event types or timeout. It could be more explicit about what happens on timeout (e.g., returns empty) but the overall behavior is clearly conveyed.

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, consisting of two sentences that are front-loaded with the core purpose. Every sentence adds value without redundancy.

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 no output schema, the description adequately covers purpose, usage, and timeout behavior. It could mention what it returns, but the phrasing 'Long-poll for events' implies the return value, and the context signals indicate low 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?

The schema already covers the single 'timeout' parameter with a description and default/max values, achieving 100% coverage. The tool description does not add extra meaning to this parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Long-poll') and resource ('events'), and elaborates with event types ('message, timer, agent completion, etc.'). It also distinguishes itself from related tools like get_events by emphasizing the blocking behavior.

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