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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: it routes to a large number of tools, fills arguments, returns stable pipeworx:// citation URIs, and is fast ('one fast call'). This goes beyond the annotations without contradicting 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?

The description is lengthy but densely informative, front-loaded with the key directive 'PREFER OVER WEB SEARCH' and structured with examples and alternatives. Some redundancy exists (repeating use cases and examples), but every sentence contributes actionable guidance. It could be tightened, but the structure helps scanning.

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

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

Despite lacking an output schema, the description explains the return format (structured answer with stable citation URIs) and covers the tool's scope, limitations, and next steps for advanced needs. It includes many examples, mentions it works on every tier, and explains when not to use it, making it highly complete for a tool of this complexity.

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

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

Schema coverage is 100%: all six parameters are aliases for the same 'question' property, and the schema already describes it as 'Your question or request in natural language' with alias notes. The description adds example questions but does not provide additional parameter semantics beyond what the schema already covers, so the baseline of 3 is appropriate.

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

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

The description clearly states this tool routes factual questions to 5,439 tools across 1,412 sources and returns structured answers with citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and distinguishes itself from siblings by explicitly naming alternatives (ask_pipeworx_grounded, deep_research).

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 when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...' with a list of trigger phrases. It also clearly states when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research').

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 beyond annotations by explaining the beta status, the fact that candidate routing may be enabled live, the current inactive state (matching ask_pipeworx exactly), and that it is a full working router rather than a fallback. This adds significant context beyond the readOnly/openWorld/idempotent hints.

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

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

Three sentences efficiently pack the core identity, current status, usage guidance, and reassurance that it is fully functional. No filler, front-loaded with the key concept.

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 as a router, the description fully explains what it is, how it relates to ask_pipeworx, and the current experimental state. Since it references the same arguments and response shape as ask_pipeworx, no additional detail about return values is necessary.

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

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

Schema coverage is 100% with all six parameters (question and aliases) already described. The description merely states 'same arguments' without adding new semantics, so it meets the baseline but does not exceed it.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router that handles the same tools and arguments. It distinguishes itself from the stable sibling by emphasizing its experimental routing improvements, giving a specific verb+resource+scope.

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

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

Provides explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, implying its use for testing/experimentation and indirectly that stable ask_pipeworx is for production needs.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals the tool's internal process: routing, argument filling, extraction, and refusal behavior. It details the exact return structure, refusal reasons, and the extra LLM call overhead, which are not visible in the schema or annotations.

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

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

The description is dense but efficiently packed: every sentence adds unique value (purpose, process, output schema, refusal reasons, use cases, cost trade-off). It could benefit from line breaks to improve scannability, but it's 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?

With no output schema, the description fully specifies the success and error response shapes, including all refusal reason enums. It also covers routing behavior, cost implications, and use cases, making it self-contained 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?

The schema already documents all six parameters with 100% coverage (all are aliases for 'question'). The description adds no additional parameter-specific semantics, but it doesn't need to since the schema is comprehensive. 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 core function: a hallucination-resistant answer mode that picks tools, fetches data, and extracts answers using only tool results. It differentiates from the sibling ask_pipeworx by emphasizing evidence/refusal behavior and names the specific use case. The verb 'ask' and resource 'Pipeworx' are clear.

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

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

Explicit usage guidance is provided: use when answers will be quoted, cited, or acted on, and avoid for casual lookups in favor of ask_pipeworx, which costs one less LLM call. The description names the alternative and gives a concrete cost trade-off.

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 only indicate read-only, open-world, idempotent. The description adds substantial behavioral context: account/paywall requirements, parallel decomposition, output packet structure (evidence, confidence, source, citation, gaps), gap recovery, contradictions scanning, semantic excerpting, and expected latency. 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, front-loading the account requirement and alternating between core functionality, use cases, and depth semantics. Some redundancy with the schema's depth descriptions makes it slightly longer than strictly necessary, but every section contributes useful contextual 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?

No output schema exists, so the description fully specifies the return type: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It covers performance, account tiers, alternatives, and depth behavior, making it comprehensive for a complex research 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% for both parameters, so baseline is 3. The description does not add meaning beyond the schema—the depth explanation in the schema already covers hops and gaps, and the question description already states 'Broad/multi-part is fine'. The description provides no extra parameter insights.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources... in ONE call' and 'Decomposes your question into focused facets, routes each to the right one of 5,439 tools IN PARALLEL, and returns a findings packet'. It uses specific verbs and distinguishes itself from siblings like ask_pipeworx.

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 use cases: 'Best for broad/multi-part questions over structured data', with direct exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirements and the fallback alternative (ask_pipeworx) for non-signed-in users.

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 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 are all false (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false), and the description adds context beyond them by disclosing rate limiting ('Rate-limited to 5 per identifier per day') and the fact that feedback directly affects roadmap. It also clarifies that reporting is free and doesn't count against quota. It doesn't explicitly state side effects (e.g., 'creates a record'), but the rate limit implies stateful behavior, and the non-destructive nature is 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 comprehensive yet efficiently structured. Every sentence serves a purpose: primary use, when to use, what not to do, how to focus feedback, team handling, rate limits, and cost — all in a compact paragraph. It is front-loaded with the main verb and action, avoiding 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 complexity (3 params, one nested object, no output schema), the description covers all necessary context: what to report, when to use, how to phrase feedback, exclusions for other MCP servers, and operational details (rate limit, cost, team review). It is complete for a feedback submission tool and leaves no ambiguity about invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies how to fill the message and context fields. It also explains the meaning of 'type' via examples embedded in the description (e.g., 'broken, missing, or needs to exist') that parallel the enum. This exceeds baseline.

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 action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this tool from siblings by focusing on submitting feedback about Pipeworx tools/packs, and the 'broken, missing, or needs to exist' phrasing clearly covers bug, feature, and data gap reporting.

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 exclusion for tools from other MCP servers and offers guidance for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists'), making it fully 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?

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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by detailing safety fields: compatibility_warning conditions (bet shape mismatch, semantic mismatch), temporal_alignment, and skipped counters. It openly discloses that most pre-mapped topics return warnings, providing full transparency.

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

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

The description is dense and well-structured with clear sections (modes, response, safety fields). While every sentence adds value, the length and complexity of some sentences could be slightly streamlined. It is a minor deduction for an otherwise excellent description.

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

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

Despite no output schema, the description thoroughly details the response structure including venue prices, spread fields, compatibility_warning, temporal_alignment, and counters. It covers edge cases (mismatched bet shapes, temporal gaps) and provides enough information for an agent to use the tool safely.

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

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

Schema coverage is 100% with descriptions. The description adds meaning by explaining the two modes, listing the 10 topic shortcut values, and clarifying how explicit tickers override the topic-mapped side. It provides context on how parameters interact, exceeding what the schema alone offers.

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's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes it from siblings like polymarket_arbitrage by focusing on a different venue 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?

The description explicitly states when to use the tool (comparing two venues pricing the same outcome) and provides guidance on when spreads may not be meaningful (via compatibility_warning conditions). It warns that real spreads are rare and that pre-mapped shortcuts often yield warnings, setting appropriate expectations.

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 mark it as read-only, idempotent, and non-destructive. The description adds that it 'cascades through several lookup endpoints internally' and explains the return format (ticker, CIK, citation URI for company; RxCUI, ingredient, brand for drug). No contradictions exist, and it provides valuable 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?

The description is front-loaded with a clear purpose statement and uses examples. It is organized with bullet points for supported types. While it is longer than minimal, every sentence adds value. Could be slightly more concise, but it's well-structured.

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

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

The tool has 2 required params, enum for type, and no output schema. The description fully compensates by detailing return values per type, including citation URIs. It explains internal cascading and covers both entity types thoroughly. 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 coverage is 100% (baseline 3). The description adds meaning by explaining accepted input values (ticker, CIK, name for company; brand/generic for drug) and the expected output format. This goes beyond schema descriptions, though the schema already provides enum for 'type' and string hints for 'value'.

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

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

The description clearly states its purpose: resolve a name to an identifier. It provides concrete examples ('What's the ticker for…') and distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID.' It enumerates supported entity types (company, drug) with specific outputs, making 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?

Explicitly states when to use: 'Use FIRST whenever you have a name but need an ID.' It explains it replaces manual lookups but does not explicitly mention when not to use or name alternative tools. The guidance is clear and directive, though slightly lacking in exclusionary context.

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

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

Annotations already declare readOnlyHint, 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?

Annotations indicate safe, idempotent, read-only behavior. The description adds important context: financial claims use structured SEC data, other claims fall through to a grounded pipeline, and it returns a verdict with citations. This goes beyond what annotations provide.

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

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

The description is detailed but somewhat verbose (multiple sentences with examples). It is front-loaded with query examples and structured logically, but could be trimmed for 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?

Despite no output schema, the description fully enumerates return fields (verdict values, actual value with citation, reasoning) and explains both processing paths. No apparent gaps for a tool of this complexity.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining tolerance_pct can override implied tolerance (e.g., 1-2 for hallucination detection) and notes a default cap of 5, which the schema lacks.

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

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

The description clearly states the tool is for natural-language claim verification using authoritative sources, with specific examples like 'Is it true that...' and 'fact check'. It distinguishes its scope (company-financial vs. other claims) without explicitly naming siblings, but the specificity earns a top score.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines two processing paths. However, it does not explicitly say when NOT to use it or compare to sibling tools like ask_pipeworx or deep_research, leaving some ambiguity.

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