Microsoft Onenote

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

Discloses default model (Workers AI) and optional Anthropic probing with BYO key, payment implications, and return structure. Complements annotations (readOnly, idempotent, openWorld) with rich operational detail.

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

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

Three concise sentences that front-load the primary purpose and add key details 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?

Despite no output schema, the description clearly defines the return structure (per-model object with score, confidence, signals, raw_response plus combined view). Covers all needed context for a 4-parameter tool.

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

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

Schema coverage is 100% with good descriptions. Description adds value by explaining the default model behavior and clarifying that _apiKey is only needed for Anthropic, going beyond the schema.

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

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

Clearly states the tool probes LLMs for brand visibility and returns a score 0-100 per model. Distinguishes itself from siblings like scan_competitor_ai_presence by focusing on visibility scoring.

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 lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring). Provides context for when to use, though does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it reveals the tool is an orchestrator that routes to sub-tools, fills arguments, returns citations, and works on every tier. No contradiction with annotations exists; the description complements them well.

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

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

The description is long, but every sentence earns its place: domain list, trigger phrases, examples, escalation path, and breaking-news note. The crucial 'PREFER OVER WEB SEARCH' directive is front-loaded. Slight redundancy exists ('START HERE' + 'default entry point') but it does not detract from the usefulness.

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

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

With no output schema, the description clearly states the return value: structured answer with pipeworx:// citation URIs. It covers the default use case, escalation alternatives, coverage domains, and even news/breaking-news handling. For a router tool with this many siblings and no output schema, the description is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema documents `question` and its aliases. The description adds semantic value by providing example questions ('current US unemployment rate', 'Apple's latest 10-K') and trigger phrases ('look up', 'find', 'get the latest') that clarify what constitutes an acceptable query. This goes beyond the schema's basic type/alias information.

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 clear verb and resource: routes a question to one of 5,706 tools across 1,493 sources and returns a structured answer with stable pipeworx:// citation URIs. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research by naming them and the conditions under which they should replace this tool. The purpose is unmistakable for an agent.

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 is explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also gives clear escalation rules: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is full conditional guidance with named alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: it's a beta with candidate routing improvements potentially active, none active currently, and it is a full working router that 'falls back to nothing' rather than a degraded stub.

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 bit dense but every sentence contributes: identity, current state, usage, comparison to stable router, and fallback behavior. It front-loads the core definition before experimental caveats.

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

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

Covers identity, current status, usage, and relationship to the stable router. With no output schema, it references ask_pipeworx's response shape, which is sufficient if that sibling is known; the router context reduces the need for more detail.

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

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

Schema coverage is 100% and the description adds no parameter-specific detail beyond saying it shares the same arguments as ask_pipeworx. The schema thoroughly documents the 'question' field and its aliases, so no compensation is needed.

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 tool as a universal router identical to ask_pipeworx, with the same 5,706 tools, arguments, and response shape. It distinguishes itself from the stable sibling by being the beta/experimental edge, and the verb 'ask' is implied by the title and routing role.

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 instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It conveys the experimental-vs-stable tradeoff, though it doesn't explicitly state when to prefer the stable 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?

Annotations already mark readOnly/idempotent/non-destructive, but description adds refusal behavior (refusal_reason enum), guaranteed extraction only from tool result, and return shape. This is meaningful behavioral context beyond annotations.

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

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

All sentences carry unique information: mode, routing, return/refusal contract, use-cases, cost tradeoff. It's front-loaded with the core purpose and doesn't repeat annotations.

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

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

Even without output schema, the description specifies the success and refusal return shapes, use conditions, sibling differentiation, and cost tradeoff. For a single-question tool with six aliases, the description is complete.

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

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

Schema description covers 100% of six params, all documented as aliases of question, so description doesn't need to add param semantics. It doesn't repeat schema, and no gaps remain.

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

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

States it is a hallucination-resistant answer mode for high-stakes reads, names the exact operation (extract answer from tool result with evidence/refusal), and explicitly contrasts with ask_pipeworx. The verb/resource and scope are unambiguous, so an agent can distinguish it from the sibling.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with examples. It names the alternative ask_pipeworx and the tradeoff (extra LLM call) and tells agent to prefer it for casual lookups.

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

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

The description goes far beyond annotations by detailing resolution confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquid spread warnings, and resolution rule risks. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 very long (about 600 words) and includes excessive detail (e.g., specific fan-out examples, resolution rule parsing). While informative, it could be more concise by summarizing common patterns. The core purpose is front-loaded, but the length may overwhelm agents.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, response shapes, error states), the description covers all necessary aspects: input handling, classification, evidence sources, return fields (market, analysis, evidence), safety mechanisms, and rare cases. Without an output schema, the description thoroughly explains return values and edge cases.

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%, but the description adds significant context: examples for 'market', explanation of depth options ('quick', 'thorough'), and the purpose of include_raw. It also clarifies that default depth is thorough and that include_raw=false keeps responses small. This adds 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 tool researches a Polymarket bet by pulling Pipeworx data. It specifies multiple input formats (slug, URL, question text) and explains the process: resolve, classify, fan-out, return evidence packet. It implicitly differentiates from siblings like polymarket_arbitrage by focusing on a single bet research, not arbitrage.

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 lists explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It gives detailed behavior for various scenarios but does not explicitly contrast with sibling tools or state when not to use. Still, the context is clear enough for an AI agent to decide.

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

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

The description adds behavioral context beyond annotations, explaining data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and returning citation URIs. No contradictions with annotations.

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

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

The description is fairly concise given the complexity, with front-loaded trigger phrases. Every sentence adds value, though slightly verbose for the detail it provides.

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 explains the data sources and sorting, but lacks details on the exact output structure (e.g., field names in the response). Given no output schema, more information on return format would improve completeness.

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

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

Schema coverage is 100%, and the description adds value with examples of parameter values (tickers, drug names) and clarifies what data each entity type returns, beyond the schema's basic description.

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 performs side-by-side comparisons of 2–5 companies or drugs, with specific verbs and examples. It distinguishes from sibling tools by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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 trigger phrases and states when to prefer this tool, but does not include explicit exclusions or when-not-to-use scenarios. It gives clear context for use cases like comparing entities.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds substantial context: account/paywall requirements, parallel decomposition, findings packet shape with gaps[] and contradictions[], citation fetchability, latency expectations, and depth-specific hop behavior. The 'NOT open-web search' clarification is especially valuable and does not contradict the openWorldHint.

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 long but dense and information-rich for a complex tool. Key constraints (account requirement, not open-web, when to use alternatives) are front-loaded, and later sections detail depth behavior and citation guarantees. Minor redundancy exists around citation_uri being mentioned twice, but the length is largely justified by the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description covers all needed call-time context: authentication requirements, expected latency, return packet structure, gap behavior, contradiction reporting, citation fetchability, and depth semantics. An agent has enough information to select the tool and parameters correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds beyond the schema by explaining what each depth means operationally (gap recovery, lead chasing, contradictions[] scan) and what 'quick' vs 'thorough' imply for latency, which helps an agent pick a value more confidently.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' in one call, explicitly contrasting with open-web search. It clearly differentiates itself from ask_pipeworx and names the use case ('best for broad/multi-part questions over structured data').

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

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

Provides explicit when-to-use and when-not-to-use guidance: if not signed in use ask_pipeworx, for a single lookup use ask_pipeworx, and for breaking/colloquial current-news prefer ask_pipeworx. It also explains depth-level selection behavior so the agent can choose the right mode.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N relevant tools with names, descriptions, and full input schemas, ready to call. Consistent with annotations, adds functional behavioral context.

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

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

Two sentences, front-loaded with purpose and usage. Every sentence adds value. 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?

No output schema, but description explains return format (top-N tools with schemas). Covers purpose, usage, and return. Parameter details are in schema. Sufficiently complete given richness of schema and annotations.

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

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

Schema coverage is 100%, so description doesn't need to add much. It mentions return format but not parameter details. Baseline 3 is appropriate as description adds no extra parameter meaning beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, with a specific verb ('discover') and resource ('tools'). It distinguishes from siblings by being a discovery tool, not a domain-specific data tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and provides examples of when to use (e.g., 'look up FDA drug approvals'). No explicit exclusions, but clear context 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?

Annotations mark the tool as readOnly, idempotent, non-destructive. The description adds substantial behavioral context: it fans out across multiple sources, returns specific fields, uses GDELT→GNews fallback, and explains input format. No contradictions.

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

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

The description is a dense paragraph but front-loads example queries. Every sentence adds value, though it could be more structured (e.g., bullet points). For a complex tool, the length is justified.

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

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

Without an output schema, the description explains the return format in detail (cik, recent_filings, fundamentals, patents, news, LEI) with specifics like sorted period_end DESC. It covers input limitations and known issues. Slight gap: no mention of pagination or error states, but adequate for the tool's purpose.

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 already describes parameters. The description adds value with concrete examples (ticker 'AAPL', CIK '0000320193'), clarifies that names are not supported, and gives enum context ('Only company supported today'). This improves clarity beyond the schema alone.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company. It distinguishes from siblings by explicitly recommending it over chaining single-pack lookups and referencing resolve_entity for names.

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 explicit when-to-use ('ALWAYS PREFER... when user asks for a holistic view') and when-not-to-use ('names not supported – use resolve_entity first'). It also mentions a limitation (patents soft-fails after May 2025).

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

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

Description aligns with annotations (destructiveHint=true) and adds context on why to delete (stale or sensitive data), providing value beyond the annotations.

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

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

Two concise sentences that front-load the core action and provide usage guidance without any 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?

Given the tool's simplicity (1 param, no output schema), the description fully covers purpose, usage, and behavioral 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?

Schema covers the single parameter 'key' with a clear description; the tool description doesn't add more detail but is consistent. With 100% coverage, 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 'Delete a previously stored memory by key,' which uses a specific verb and resource, and distinguishes it from siblings like 'remember' and 'recall'.

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 tells when to use: 'when context is stale, the task is done, or you want to clear sensitive data,' and pairs with alternatives 'remember and recall'.

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?

Describes the extraction process and output format, adding context beyond annotations. Annotations already indicate read-only, idempotent, non-destructive; description confirms fetching and emitting markdown, which is consistent.

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, well-structured sentence that front-loads purpose, then provides detail and use cases. No redundant 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?

Given 2 parameters, no output schema, and rich annotations, the description fully covers what the tool does, how it works, and when to use it. Output is described as 'single text blob ready to drop at site-root/llms.txt'.

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 baseline is 3. Description does not add new semantics beyond schema but reinforces usage context. No additional parameter details beyond schema.

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

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

Clearly states the verb 'Generate', the resource 'llms.txt file', and the context 'for any URL so AI crawlers can index the site cleanly'. Differentiates from sibling tools by being specific to generating llms.txt, a distinct 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?

Explicitly lists use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' No explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the return format ('Returns the page body as HTML') and confirms the scope ('full HTML content'), which is useful beyond the annotations. No contradictions.

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

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

The description is two short, purposeful sentences. It front-loads the action and resource, then states the return format and usage sequence with no filler.

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

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

For a one-parameter read-only tool with no output schema, the description adequately covers what the tool does, what it returns, and when to use it. Minor omissions like error or auth details are not material 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?

Schema coverage is 100%, and the single page_id parameter is already documented as 'The ID of the OneNote page to retrieve (from list_pages).' The description adds no semantic detail 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 states a specific verb and resource: 'Get the full HTML content of a single OneNote page... by its ID.' It also clarifies what is returned ('page body as HTML'), making it easy to distinguish from sibling tools like list_pages.

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

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

The description explicitly says 'Use after list_pages' to read a user's OneNote note in full, providing clear contextual guidance. It does not enumerate when not to use alternatives, but the prerequisite relationship is clear.

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

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

Annotations already mark the operation read-only, idempotent, and non-destructive. The description adds useful context beyond those annotations by specifying the exact notebook fields returned and the account-level scope, which matters because there is no output schema. It does not discuss pagination or empty-result behavior, but for a zero-parameter read-only listing tool those are minor 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?

Two sentences, with the operation and scope front-loaded, followed by return details and a usage hint. Every clause adds information and there is no filler or restatement of the title.

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, zero-parameter, read-only listing tool, the description is complete enough: it states scope, return fields, and the intended position in the workflow. Annotations cover side effects, and the absence of an output schema is compensated by the explicit return-field list.

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 coverage is 100%, so there are no parameter details for the description to clarify; the 0-parameter case is a baseline 4. The description does not invent or imply any undocumented 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 opens with the exact operation ('List the OneNote notebooks'), specifies the account scope ('signed-in user's Microsoft 365 / OneNote account'), and names the returned items. It clearly distinguishes this tool from sibling list_pages and list_sections tools, especially with the phrase 'before browsing sections or pages.'

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?

States a clear when-to-use scenario: 'Use to discover a user's OneNote notebooks before browsing sections or pages.' It does not, however, explicitly name sibling tools or state when not to use this tool, so it falls just short of a full 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: newest-first ordering for the global listing, optional search filtering, and the specific fields returned (id, title, created/last-modified times). It does not mention pagination or rate-limit behavior, but the annotation safety profile lowers the burden.

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 appropriately sized and front-loaded: it states the core purpose first, then usage variants, return contents, and the intended workflow. Every sentence contributes useful information 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?

Given a simple read-only tool with three optional parameters, a fully self-documenting schema, and safety annotations, the description is complete. It covers behavior, return fields, ordering, and the use case, leaving no important gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents top, search, and section_id thoroughly. The description restates the section_id vs. omit behavior and mentions search filtering, but it adds little semantic value beyond what the schema provides, warranting the 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 opens with a specific verb and resource: 'List OneNote pages (Microsoft 365 notes)'. It further clarifies scope by describing both section-scoped listing and notebook-wide recent pages, and distinguishes itself from content-reading tools by framing the tool as the step 'before reading their 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 gives clear conditional guidance: pass section_id for a section, omit it for recent pages across notebooks, and optionally filter by search. It also states the intended use case, finding notes before reading content, though it does not explicitly name alternate tools like get_page_content or list_sections as exclusions.

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

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

Annotations already establish a read-only, idempotent, non-destructive profile. The description adds behavior beyond that: the optional parameter changes scope from one notebook to all notebooks, and it discloses the returned fields (id, display name, timestamps). No contradiction with annotations.

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

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

Three short sentences, with the core action and scope front-loaded. Every sentence adds meaning: what is listed, how the parameter changes scope, what is returned, and when to use it.

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

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

For a one-parameter read-only list tool, the description is complete: it covers filtering semantics, return fields, and usage context. The rich annotations handle safety, so no additional behavioral disclosure is needed.

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

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

Schema coverage is 100%, so the schema already documents notebook_id including that omitting it returns all notebooks. The description repeats this behavior rather than adding new semantic detail, which 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 begins with a specific verb and resource: 'List the sections in a OneNote notebook (Microsoft 365).' It clearly distinguishes itself from sibling tools such as list_notebooks and list_pages by stating the object type (sections) and the conditional scope across one or all notebooks.

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

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

It gives practical guidance on when to call it: 'Use to navigate a user's OneNote notes before listing pages,' which places it in a workflow relative to list_pages. It does not explicitly name alternatives or exclusions, but the context is clear enough.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds return field details and the scope 'caller's active subscriptions', providing useful behavioral context beyond annotations.

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

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

Two sentences, no wasted words. The core function and return fields are stated first, followed by usage guidance. Excellent structure and 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?

With one optional parameter, no output schema, and annotations covering safety, the description covers the essential aspects. Slight room for improvement by explicitly mentioning default behavior (active only), but it's implied.

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 for the single parameter 'include_inactive'. The description does not add extra meaning beyond the schema, so baseline score 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 'List' and the resource 'the caller's active subscriptions', with specific return fields (id, type, params, etc.). This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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 guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly mention when not to use, but the context is clear enough.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses the claim_token return and retrieval flow, rate limit ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and human review cadence ('team reads digests daily'). It also warns against pasting end-user prompts, adding rich behavioral context with no contradiction to annotations.

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

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

The description is a single dense paragraph, but every sentence earns its place: purpose, usage triggers, exclusion boundaries, formatting guidance, token flow, rate limits, and quota. It front-loads the purpose in the first sentence and avoids any redundant restatement of the tool name or schema, achieving high information density without 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?

Despite having no output schema, the description covers the essential behavioral contract: how to submit, how to follow up with a claim_token, constraints (rate limit, quota), and scope boundaries. For a low-complexity feedback tool with all optional parameters, this is sufficient for an agent to use it correctly without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage context by mapping enum categories to concrete scenarios ('wrong/stale data (bug)', 'wish existed (feature/data_gap)', 'worked surprisingly well (praise)') and instructs users to 'describe the issue in terms of Pipeworx tools/packs' for the message field. The claim_token round-trip is also explained beyond schema, but the nested context object is not detailed further than the schema already does.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's function with a specific verb and resource. It distinguishes itself from siblings by explicitly scoping to 'tools served by this Pipeworx connection' and contrasting with other MCP servers, leaving no ambiguity about what the tool does.

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 explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear when-not-to-use case: 'if the tool came from a different MCP server ... file it with that server instead,' plus guidance on how to identify Pipeworx tools.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: source (CF analytics-engine), no PII, caching window (5min-1h), and self-aggregating nature, enhancing behavioral understanding.

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

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

Five sentences, front-loaded with main result, uses bullet-like enumeration for use cases. Every sentence adds value; no 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?

Given the tool's simplicity (1 optional param, good annotations, no output schema), the description fully covers purpose, usage, behavioral details, and parameter semantics. No gaps remain.

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

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

Schema covers 100% of the single parameter with enum descriptions. Description adds meaning by explaining the trade-off between shorter and longer windows (hot vs steady-state), going beyond enum labels.

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

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

Description explicitly states it returns top tools, top packs, and total call volume over a window, using specific verbs and resources. It clearly distinguishes from sibling tools by its unique focus on trending data.

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?

Lists three concrete use cases: discovering hot data sources, confirming popular tools, and checking alignment. While it doesn't explicitly exclude alternatives or mention when not to use, the use cases are clear and actionable.

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

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

Discloses detailed internal behavior: partition checks, monotonicity, similarity thresholds, placeholder filters, fill check against CLOB depth. Warns when edges are not realizable. No contradiction with annotations.

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

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

Well-structured and dense with information, but quite long. Could be slightly more concise without losing clarity, but the organization is logical.

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 lacking an output schema, the description fully explains the response structure and key fields. Covers edge cases and error conditions, making it complete for the tool's complexity.

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

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

Schema covers 100% of parameters with descriptions, and the description adds substantial context (e.g., what event slug means, how topic works, semantic anchor, partition filter).

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

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

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. The verb-resource combination 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?

Provides explicit guidance on when to use each mode (no args for trending scan, event for per-event, topic for cross-event) and references an alternative tool (polymarket_fill_risk) for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond these by detailing how segments are computed, caching behavior (1h KV-level), and diagnostics for empty segments. No contradiction with annotations.

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

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

The description is long but well-structured, starting with the core purpose, then detailing three segments, opportunity fields, knobs, and response structure. It is information-dense but not bloated.

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

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

Given the tool's complexity (9 params, no output schema), the description provides comprehensive coverage: it explains output segments, diagnostics, Fed bets handling, and parameter effects. It fully compensates for the lack of an output schema.

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

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

Schema covers all 9 parameters with descriptions, so the baseline is 3. The description adds value by explaining how parameters like min_liquidity and max_spread_pp serve as 'tradeable-edge knobs' and by contextualizing the overall logic.

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 clear and specific purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven discrepancies and structural arbitrage.

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 frames the tool as answering 'what should I bet on today' and notes that Fed bets are excluded from ranking. However, it does not explicitly mention when not to use this tool or list alternative tools for specific 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint as safe read. Description adds rich behavioral context: data from daily snapshots, cache-miss gaps, response structure, and limits (60-day TTL). No contradictions.

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

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

Well-structured: purpose, details, args, response in ALL CAPS, limits. Slightly verbose but every sentence adds value. Front-loaded with key question answered.

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

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

Given no output schema, description exhaustively explains response fields (tracked, expired, snapshot_dates) and data source limitations. Covers all aspects an agent needs to invoke and interpret results.

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

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

Schema covers both parameters (100% coverage). Description adds defaults, ranges, and explanation of window families, enhancing understanding beyond 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?

Clearly states purpose: edge persistence and decay telemetry. Distinguishes from sibling tools like polymarket_edges by focusing on historical persistence and decay. Uses specific verbs and 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?

Implies usage context (comparing fresh vs aged edges) but does not explicitly specify when not to use or list alternative tools. However, the context signal provides siblings, and the description hints at the distinction from current-edge tools.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: walks the ladder, returns top_of_book, vwap_fill_price, slippage, verdict, forced_directional_risk in basket mode. Aligns with annotations and provides context beyond them.

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?

Well-structured with clear sections (SINGLE-MARKET, BASKET) and a summary at the end. Each sentence adds value. Slightly long but warranted due to complexity; could be slightly more concise but effective.

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

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

Given no output schema and tool complexity (two modes, multiple return fields), the description covers all key return fields, explains risks (e.g., forced_directional_risk), and provides practical context. Very 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%, baseline is 3. Description adds meaning beyond schema: explains size_usd interpretation in basket mode ('settlement notional — shares per leg'), clarifies side default logic, and provides default values and clamps. This adds 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?

Description clearly states 'realizable-vs-theoretical edge check against live CLOB order-book depth' with two distinct modes (single-market and basket). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly telling when to use this tool before those.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why not using it leads to problems (partial fills converting arb into unhedged directional position). Clearly distinguishes from 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 annotations already indicating a safe, read-only, idempotent operation, the description adds substantial behavioral detail: it explains compatibility_codes, the fact that warnings can be non-empty even when matches exist, the rule that unknown legs are never paired, skipped comparison counters, and temporal alignment. This is far beyond what the annotations reveal.

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 long but densely packed and highly structured with labeled sections like TWO MODES, RESPONSE, and SAFETY FIELDS. The core purpose is front-loaded, and every sentence contributes behavioral or usage information that is not captured in the schema or annotations.

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

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

There is no output schema, so the description fully carries the burden of explaining the return value. It covers per-venue prices, matched spreads, compatibility warnings and codes, skipped/unclassified legs, temporal alignment, and caveats about pre-mapped topics. Nothing an agent needs to correctly consume the result is omitted.

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 a baseline of 3 applies. The description adds value by explaining the two modes: topic shortcuts auto-fetch matching events, while explicit ticker/slug pairs enable custom comparisons. This enriches the bare parameter names and enum-like topic list with operational meaning.

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 first sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by emphasizing the cross-venue, spread-comparison nature of the tool.

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

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

The description explicitly describes two invocation modes—pre-mapped topic shortcuts and explicit custom pairings—and gives practical guidance on when each is appropriate. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility warnings. It does not explicitly compare against sibling tools such as polymarket_arbitrage, so some alternative-selection reasoning is left to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds scoping behavior (tied to identifier) which goes beyond annotations, providing useful 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?

Concise, three sentences with key information front-loaded. Each sentence provides distinct value: main action, use case, scope, and sibling pairing.

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 retrieval tool with one optional parameter, the description is mostly complete. It explains how to use, scope, and relationships. Lacking return format, but acceptable given 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 coverage is 100% and the description mostly mirrors the schema's parameter description. The examples in schema add value, but the main description contributes little beyond 'omit the key argument' already in schema.

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

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

Clearly states the tool's two functions: retrieving a saved value by key or listing all keys by omitting the key argument. Distinguishes itself from sibling tools 'remember' and 'forget'.

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 use cases (retrieving saved context like ticker, address, notes) and mentions pairing with remember/forget. Does not explicitly state when not to use, but the context is clear.

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

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

The description indicates that setting mark_read:true flags events as read, modifying server state. This directly contradicts the annotations, which declare readOnlyHint=true. According to scoring rules, a contradiction earns a score of 1.

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—four sentences—with the purpose front-loaded. Every sentence adds meaningful information without redundancy. Structure efficiently groups purpose, return fields, filter options, and usage note.

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 5 optional parameters and no output schema, the description adequately covers return fields and key behaviors like mark_read. It mentions an alternative endpoint for scripting. Missing details include pagination behavior beyond limit, error handling, and authentication requirements, but overall is reasonably complete.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the type filter with an example ('sec_8k'), clarifying since is an ISO timestamp, and detailing mark_read and unread_only behavior. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool pulls fired events from subscription feeds and specifies what each returned event carries (source, citation_uri, payload). It distinguishes itself from siblings like list_subscriptions by focusing on events rather than subscriptions, and mentions an alternative endpoint for scripts/dashboards.

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

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

The description explains when to filter by type and since, and how mark_read affects subsequent calls. It notes that polling works fine. However, it does not explicitly exclude alternative tools or state when not to use this tool compared to siblings like validate_claim or search_within.

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?

Fully describes the multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), fallback logic, and potential API sunset issues. Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds rich behavioral context without contradiction.

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

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

Well-structured: starts with query examples, then explains sources and parameters, ends with sibling guidance. Every sentence serves a purpose, 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?

Despite no output schema, the description details the return format (changes[] grouped by source, total_changes, citation URIs). Covers all data sources, parameter formats, and fallback behavior—completely sufficient given complexity.

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

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

Schema coverage is 100%, but the description adds crucial context: explains 'since' accepts ISO dates or relative shorthand with examples and a recommended default, clarifies 'value' can be ticker or CIK. This enriches the schema significantly.

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 provides a change feed for a company over a specified window, with example queries ('What's new with X', 'latest on Y'). It distinguishes itself from the sibling tool 'entity_profile', which is for static profiles.

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 tells when to use this tool (for dynamic changes over a window) and when to use the sibling 'entity_profile' instead (for static profiles). No ambiguity.

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

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

Beyond annotations, description reveals key behavioral traits: key-value pair scoped by identifier, persistence based on authentication (24 hours for anonymous), and that it pairs with recall/forget. No contradiction with annotations.

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

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

Four sentences, each earning its place: purpose, usage guidance, behavioral details, and relationship to siblings. No redundancy, perfectly front-loaded.

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 simple 2-parameter tool with no output schema and supportive annotations, the description covers all necessary context: purpose, usage, persistence, and pairing with other 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 already describes both parameters clearly (100% coverage). Description adds context with inline examples for key patterns and clarifies value as free text. Adds moderate value beyond schema.

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

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

Clear verb 'save' and resource 'data to reuse later'. Distinguishes from sibling tools 'recall' and 'forget' by naming them and describing how they pair.

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 specifies when to use: 'discover something worth carrying forward'. Provides examples of data types and contrasts with anonymous vs authenticated sessions. References sibling tools for retrieval and deletion.

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context: graceful degradation of LEI/FIGI enrichment when external sources are unavailable, explicit handling of unresolved identifiers under `unresolved`, source labelling for every identifier, and internal cascading through multiple lookup endpoints. No contradiction.

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

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

The description is long but dense, with every sentence contributing useful information. It front-loads the purpose with example queries, though the company-type parenthetical is quite lengthy and could be reformatted with bullets for better readability. It remains appropriately structured for a complex 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?

Despite having no output schema, the description covers return behavior (source-labelled identifiers, explicit `unresolved` field), input variants (ticker, CIK, name, ISIN; brand/generic), graceful degradation, and internal cascading. It gives the agent enough to invoke the tool and interpret results effectively.

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%, but the description enriches both parameters significantly. It provides concrete value examples (AAPL, 0000320193, ozempic, metformin), clarifies that ISIN is also accepted and maps to the legal entity via GLEIF, and explains the difference between company and drug inputs. This goes well beyond the schema's basic descriptions.

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

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

The description opens with concrete example queries and explicitly states the tool resolves a user-spoken NAME to canonical/official identifiers required by other tools. It clearly differentiates from siblings by positioning itself as the first step for name-to-ID lookups and lists the two supported entity types (company, drug).

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use condition. It also notes the internal cascading replaces 2-3 manual lookups, but it doesn't name specific alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. Description adds that it 'probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns 'score, confidence, signal density'. This adds detail but does not reveal significant behavioral traits beyond what annotations imply. The description carries limited additional transparency burden due to complete 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, zero wasted words. First sentence states action and mechanism, second provides use case and output. Front-loaded with purpose. Every sentence earns its place.

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

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

Given no output schema, the description adequately explains return values (ranked list with score, confidence, signal density) and the ranking algorithm. It covers the four parameters implicitly through the action description. Missing an explicit mention of the dependency on ai_visibility_check or that calling anthropic requires an API key, but schema descriptions handle that. Overall sufficient for an agent to invoke correctly.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds context: it explains the probing mechanism ('with ai_visibility_check'), the ranking process ('ranks by score, surfaces which is most/least recognized'), and the output format ('score, confidence, signal density per entity'). This provides meaningful behavioral semantics beyond the schema's type definitions.

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

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

Description clearly states the verb 'compare', 'probe', 'rank', and 'surface' applied to 'AI visibility across multiple entities'. It differentiates from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying it uses ai_visibility_check internally and focuses on AI recognition. The resource and action are 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?

Description explicitly gives a use case: 'competitive AI-marketing audits' with an example question. It implies when to use (comparing multiple entities) and references ai_visibility_check as the underlying probe, suggesting single-entity checks should use that tool. However, it does not explicitly state when not to use or list alternatives.

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

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

Annotations already provide readOnly, idempotent, openWorld hints, and non-destructive. Description adds value by explaining fan-out behavior, graceful partial failures, and a 5-30s timeout for bundlephobia's first measurement on new versions. No contradiction with annotations.

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

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

Description is relatively long but every sentence adds value. It is front-loaded with purpose and usage guidelines. Could be slightly more concise but remains effective.

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

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

No output schema is provided, but the description thoroughly explains the return fields (summary block, advisories, links, alternative versions) and behavior on partial failures. Adequate for an agent to understand what to expect.

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 description does not need to repeat schema details. It adds minimal context (e.g., scoped packages accepted, version defaults to latest). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs and resources, and distinguishes from sibling tools by noting ecosystem limitations.

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 tells when to use this tool (agent asks about package safety/popularity/size or cost of adding a package) and when not to use it (non-NPM ecosystems fall under deps.dev:version directly). Provides clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds significant behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. This goes beyond annotations.

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

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

Description is concise, front-loaded with core purpose, then provides technical details. Every sentence adds value with no 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?

Despite no output schema, the description explains return format (top passages with offsets and scores), mentions truncation behavior, and pairs with a sibling. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description adds context (e.g., examples for query, max 200K chars for text) and clarifies that text is the document to search inside. Slight improvement over 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 'semantic search INSIDE a fetched record' and uses specific verbs like 'search inside' and 'return passages.' It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. Also mentions pairing with ask_pipeworx_grounded for grounding, providing clear usage context.

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

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

The description adds significant behavioral context beyond annotations: it discloses the OAuth requirement, the return of a subscription ID, delivery channel specifics (email, SMS, webhook), verification steps, rate limits (10/day for SMS), webhook HMAC signing, and auto-disable after 10 failures. This is comprehensive and consistent with annotations.

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

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

The description is relatively long but well-structured, starting with the core purpose, then expanding on types and delivery. Information is front-loaded. Minor redundancy could be trimmed, but overall it is efficient for the amount of 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 complexity (multiple subscription types, delivery channels, auth requirements) and absence of output schema, the description covers most critical aspects. It explains return value, but lacks error handling or latency notes. Still, it is sufficiently complete 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?

Schema coverage is 100%, so the schema already documents parameters. The description adds concrete examples (e.g., 'items:["5.02"]' for sec_8k) and constraints (phone must match verified number, webhook restrictions). This provides meaningful additional guidance.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream. It specifies the verb 'create' and the resource 'subscription', and distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on setting up new subscriptions.

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 context for when to use this tool (proactive monitoring) and mentions prerequisites (Pipeworx OAuth account). However, it does not explicitly compare to alternatives like 'recent_alerts' or 'ask_pipeworx', though the detail about persistent subscriptions implies the distinction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by explaining it returns 'example questions', is an onboarding tool, and draws from a live catalog. No contradiction with annotations; the description enhances understanding of 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 front-loaded with example questions and a clear purpose statement. It is detailed but each sentence adds value for an onboarding tool. Could be slightly more concise, but structure is logical and effective.

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

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

Given the tool's role as an onboarding entry point with a single optional parameter, the description fully covers when to use it, what it returns, and how to call it. Despite no output schema, the return nature is well explained. Sibling tools exist, but the description positions this tool uniquely.

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 one optional parameter described. The description adds meaning by listing example topics ('finance', 'pharma', etc.) and explaining behavior when the parameter is omitted versus provided. This goes beyond the schema's basic description.

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

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

The description clearly states the tool returns example questions organized by category, using specific verbs like 'returns' and 'draws'. It distinguishes itself as the 'onboarding entry point' and mentions it provides tool+argument shapes, setting it apart from siblings like ask_pipeworx or entity_profile.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to use the optional topic parameter. While it does not explicitly exclude when not to use, the context is clear enough for an agent to infer appropriate usage.

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

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

Description explains behavioral trait: 'The row is deactivated (not deleted) so its historical events stay available.' This adds value beyond annotations (destructiveHint=false, idempotentHint=true) by clarifying the deactivation mechanism and linking to recent_alerts. No contradiction with annotations.

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

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

Two sentences: first states action, second explains side effect and constraint. Every sentence adds necessary information; no fluff. Front-loaded with the primary 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 one required parameter and no output schema, the description covers purpose, ownership constraint, and behavioral outcome (deactivation vs deletion). It also references a related tool (recent_alerts) for context. Complete for agent decision-making.

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?

Single parameter 'id' is fully described in schema (type, description referencing subscribe). Description repeats 'by id' but does not add new semantics beyond what the schema provides. With 100% schema coverage, 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?

Tool name and title clearly indicate unsubscribing from alerts. Description states 'Cancel a subscription by id' which is a specific verb and resource. Distinguishes from sibling tools like subscribe and list_subscriptions.

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?

Description includes ownership constraint: 'you can only cancel your own subscriptions.' This provides clear context for when to use the tool, but does not explicitly mention when not to use it or alternatives. Still, the constraint is helpful for correct invocation.

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

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

The description adds significant behavioral context beyond the annotations: it explains the distinction between 'could_not_verify' and 'unsupported', reveals the error structure (verification_error{stage,detail}), and details the automatic routing logic to different data sources. This gives the agent crucial caveats about how to interpret results. The annotations declare readOnly/openWorld/idempotent, which align with the description; no contradiction.

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

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

The description is longer than average but each sentence provides substantial value: trigger phrases, routing logic, verdict definitions, error implications, and replacement benefit. No filler. It could be tightened slightly, but the detail is justified for a tool with nuanced behavior.

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

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

Despite having no output schema, the description covers return values (verdict types, value with citation, reasoning) and error semantics. It explains the two data-processing paths and when each applies. For a complex tool with only 2 params, this is a very complete description that leaves little ambiguity for the agent.

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

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

Schema coverage is 100% and both parameters are described in the schema, so the baseline is 3. The description adds meaningful extra guidance for tolerance_pct, explaining that it can override the wording-implied tolerance and recommend a 1–2 range for hallucination detection. This enriches the parameter's semantics beyond the schema description.

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 ('validate', 'fact check', 'verify') with a clear resource (natural-language claims against authoritative sources). It distinguishes itself from siblings by explicitly covering the claim-verification use case and contrasting with multi-step alternative pipelines (SEC EDGAR fast path vs grounded pipeline). The trigger phrases and verdict terms make the purpose 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 explicit when-to-use context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also implies when not to use (when not a factual claim) and describes the underlying pipeline replacement to show why this tool is preferred over sequential calls. It lacks a named sibling alternative, but the guidance is clear enough.

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