Microsoft Todo

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

The description adds behavioral context beyond annotations, such as default model cost (free), optional Anthropic with BYO key, and return structure. No contradiction with annotations (readOnlyHint, etc.).

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 (two sentences), front-loaded with purpose, and each sentence adds essential 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?

Despite no output schema, the description fully explains return shape (per-model {score, confidence, signals, raw_response} + combined view) and covers all parameters. Complete for a probe tool with its 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?

With 100% schema coverage, the description still adds significant meaning: explains entity as brand/product/topic, models as list with default and option for Anthropic, _apiKey as required for Anthropic, and context as disambiguation. Adds critical cost and usage nuances.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for visibility'), clearly distinguishing it from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on scoring visibility across models.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context. It does not explicitly list exclusions or alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context on top: the tool acts as a router, fills arguments, returns structured answers with stable citation URIs, and works on every tier in one fast call. No contradiction with annotations, and the added routing/citation details exceed 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 longer than two sentences but every sentence is purposeful: preference over web search, domain examples, routing behavior, alternatives, and usage triggers. It is front-loaded with the key guidance and uses examples to enhance clarity without being 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 (router to thousands of sources), the description covers the core behavior, use cases, alternatives, return format (structured with citation URIs), and even notes it works on all tiers. No output schema exists, so the description appropriately conveys the expected results. This is complete for the tool's scope.

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% because every parameter is an alias for 'question' with clear descriptions. The description itself does not add extra semantic meaning beyond the schema; it only reiterates the natural-language nature of the question. Baseline 3 is appropriate since the schema fully documents the parameters.

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

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

The description identifies a specific verb+resource+scope: 'Routes the question to the right one of 5,461 tools across 1419 verified sources' and returns 'structured answer with stable pipeworx:// citation URIs.' It clearly distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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 guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It also gives clear when-not-to-use and alternatives: 'for a hallucination-resistant single answer with verbatim evidence + confidence 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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context: it's a full working router, not a stub, with a retired candidate as of 2026-07-26 so it currently matches ask_pipeworx exactly. It also discloses the live-testing and comparison mechanism, going beyond the structured fields.

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

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

Four sentences, each serving a distinct purpose: defining beta status, noting identical scope, stating current no-candidate state, and giving usage directive. No redundancy, front-loaded, and 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?

Description covers purpose, current operational state, and usage context among sibling tools. It points to ask_pipeworx for response shape and usage, but doesn't explicitly warn against using it in production or describe what routing improvements might change, leaving a small gap for a beta 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 all six parameters documented as aliases for 'question'. The description merely says 'same arguments' without adding any new parameter-level meaning, so the baseline 3 applies.

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

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

Description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,461 tools and arguments. It explicitly distinguishes from the stable sibling by noting candidate routing improvements and the current exact equivalence, 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?

Gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison against the stable router for merge decisions. However, it doesn't explicitly state when to prefer the stable version (e.g., production stability), so it falls slightly short of a complete when/when-not.

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 specific behavioral traits beyond the annotations: it returns a structured refusal with distinct refusal reasons, uses only tool-result content, and costs one extra LLM call. This enriches the read-only/idempotent hints from annotations without any 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 lengthy but well-structured: it opens with the core purpose, then details return/refusal formats, then gives usage guidance with cost trade-off. Each segment is necessary for the tool's complexity, though slightly dense; it earns a 'concise for purpose' score rather than a 5.

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 there is no output schema, the description compensates by explicitly specifying the return shape `{answer, evidence, confidence, source, fetched_at, refusal_reason}` and all possible refusal reasons. It also covers cost and use cases, leaving no major gaps for high-stakes usage.

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

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

Schema description coverage is 100%, with `question` and five aliases fully documented. The description does not add parameter-specific details, but the schema already sufficiently handles parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' that routes to the right tool, fetches data, and extracts answers only from the tool result. It explicitly differentiates itself from sibling `ask_pipeworx` by emphasizing grounded, evidence-based responses for high-stakes reads.

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 guidance: 'whenever an answer will be quoted, cited, or acted on' and lists example domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative `ask_pipeworx` for casual lookups and mentions the extra LLM call cost, giving clear selection criteria.

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 provides extensive behavioral details beyond annotations: market resolution process, classifier list, fan-out examples, response shapes, resolver contract with match confidence, parent event extractor, news fallback mechanisms, safety short-circuits, closed market handling, spread warnings, and resolution-rule risk. 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 each section adds value, covering many scenarios. It is front-loaded with the main purpose and structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Could be slightly more concise but appropriate for the 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?

Despite no output schema, the description thoroughly explains all response fields, evidence structure, safety mechanisms, edge cases, and caveats. It leaves no important aspect undocumented 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 substantial meaning: market parameter accepts slug, URL, or question text with examples; depth parameter explains 'quick' vs 'thorough'; include_raw explains when to use true vs false. Goes well 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 Polymarket bets by pulling relevant Pipeworx data, classifying the bet, and returning an evidence packet with market-vs-model comparison. It distinguishes from sibling tools by being specific to Polymarket betting research with fan-out to category-specific data sources.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It provides numerous examples of fan-out for different bet categories. However, it does not explicitly state when NOT to use this tool or list alternatives, though 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses data sources (SEC EDGAR for companies, FAERS etc. for drugs), handling of fiscal years, sorting by primary metric, and output format with citation URIs. 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?

Description is dense but well-structured, front-loading trigger phrases. Every sentence adds value, though could be slightly more concise.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers purpose, data sources, sorting, output format. No output schema, but return type is described adequately.

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

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

Schema coverage is 100%, but description adds meaning: explains 'values' for company (tickers/CIKs) and drug (names), provides examples, and clarifies max/min constraints. Adds context 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 starts with user-trigger phrases like 'Compare X and Y' and 'X vs Y', clearly stating the tool performs side-by-side comparison of 2-5 entities. It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. Provides example queries but does not explicitly state when to avoid using.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, but the description adds extensive behavioral detail beyond these: account requirements, depth tiers with paid plan, decomposition into facets, parallel routing to 5,461 tools, output structure (findings packet with verbatim evidence, confidence, source, fetched_at, citations), gaps[] for unanswered facets, contradiction[] scans, semantic excerpting, and latency expectations. It even discloses that citations are 'stable pipeworx://' and only present if resolvable. 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 (~350 words) but densely packed with essential operational details. It is front-loaded with account requirements and core behavior, then flows through usage guidance, depth behavior, output details, and performance. Minor redundancy exists (e.g., the citation resolvability clause could be trimmed), but overall every major behavioral aspect earns its place for a tool of this 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?

This is a complex tool with no output schema, so the description must carry the return-value explanation. It does: 'returns a findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers account constraints, paid tier, depth semantics, contradictions, semantic excerpting, and latency. The description fully equips an agent to decide when to use the tool and interpret its output, despite 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 coverage is 100% (both question and depth are documented), so baseline is 3. The description adds meaningful extra semantics: it explains depth tiers in operational terms (standard adds gap-recovery hop and contradictions[], thorough adds iterative hop and is paid), includes example questions to clarify expected input, and warns that question breadth is acceptable. These insights go beyond schema descriptions, raising the score to 4.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It specifies the verb (researches), resource (structured data sources), and scope (multi-source, broad questions). It also differentiates from sibling tools by explicitly contrasting with ask_pipeworx ('For a single lookup use ask_pipeworx') and noting this is 'NOT open-web search', making 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 provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also explains fallback behavior if not signed in ('If you are not signed in, use ask_pipeworx instead'). This is model-caliber usage 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 readOnlyHint and idempotentHint. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly, without contradicting annotations.

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

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

Well-structured with front-loaded purpose, examples, return details, and usage guidance. Slightly long but each sentence adds value; no waste.

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

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

Given 6 parameters, no output schema, but description explains returned content (names, descriptions, schemas). Missing security or rate limit info but acceptable.

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

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

Schema coverage is 100% with descriptions for all 6 parameters; description adds natural language context and aliases but doesn't significantly extend 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 description uses specific verb 'find' and resource 'tools', and lists many domains. It clearly distinguishes itself from sibling tools as the discovery mechanism, not a task-specific 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 states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use and implies when-not-to (already know 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, destructiveHint. The description adds significant behavioral context: fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), details returned fields, mentions patent API sunset and soft-fail behavior, and explains news fallback. 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 front-loaded with example queries and packs a lot of information into a few sentences. Every sentence adds value, though it is slightly lengthy. Still very efficient.

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

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

Given no output schema, the description thoroughly explains return structure (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with source details and limitations. Parameters are fully covered. The description is complete for a complex multi-source tool.

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

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

Schema coverage is 100% with both parameters described. The description adds usage examples and clarifies that names are not supported, but does not add new semantic constraints beyond what the schema already provides (type enum, value as string). 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 starts with concrete example queries and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from sibling tools like compare_entities and resolve_entity by specifying it's the preferred holistic view and that names require resolve_entity first.

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: 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also clearly states when not to use ('names not supported – use resolve_entity first') and what to pass (ticker or CIK).

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?

Descriptive text just says 'Delete', which aligns with annotations (destructiveHint=true). No additional behavioral context 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?

Extremely concise: two sentences that efficiently convey purpose, usage guidance, and sibling context without waste.

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

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

All necessary information for a simple deletion tool (one param, no output schema) is present: what it does, when to use, and with what siblings.

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

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

Schema coverage is 100% and schema already describes the 'key' parameter. Description adds no extra meaning beyond the schema.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and implicitly distinguishes from sibling tools '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?

Explicit guidance on when to use: context stale, task done, or clearing sensitive data. Also suggests pairing with '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?

Annotations already indicate a safe, idempotent read operation. The description adds behavioral context by explaining the fetch-extract-emit process and output format, which is valuable 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?

Three sentences front-loading purpose, process, and usage. Every sentence adds value; no redundancy or fluff.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, usage, behavior, and output format adequately. No gaps given the tool's simplicity.

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

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

Schema coverage is 100%, so the description does not need to add meaning. It mentions only the 'url' parameter, not 'max_links', but the schema already describes both. Baseline 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and purpose (AI crawler indexing). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on the specific output format.

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 lists three use cases: getting a client's site indexed, drafting for own projects, and auditing competitors. It does not mention when not to use or alternatives, but the use cases are clear and sufficient.

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

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

Annotations already indicate read-only and non-destructive. The description adds return fields and default active-only behavior, but does not mention pagination or rate limits.

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

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

Two sentences with no fluff: first states purpose and return fields, second gives usage guidance. Highly efficient.

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

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

For a simple read-only list tool with one optional param and good annotations, the description covers purpose, return structure, and usage guidance completely.

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

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

Schema coverage is 100% with clear parameter description. The description adds context of 'active subscriptions' implying default, but does not significantly enhance 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 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. It distinguishes from siblings like subscribe/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?

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use and contrasts with subscribe/unsubscribe.

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, giving no safety signals, so the description carries the burden. It discloses the rate limit ('Rate-limited to 5 per identifier per day'), the internal process ('team reads digests daily'), and the fact that it's free and doesn't count against tool-call quota. It also warns against pasting end-user prompts, clarifying what to include. Minor omission: no mention of data retention or privacy, but for a feedback tool this is ample.

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

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

The description is front-loaded with the core purpose and then follows a logical flow: what to report, when to use, exclusions, content instructions, rate limit. Every sentence earns its place, and there is no filler or redundancy.

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

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

For a simple feedback tool with no output schema, the description covers purpose, usage, exclusions, quota details, and content formatting. It even addresses the tool's relationship to other MCP servers, making it fully contextual for an agent deciding whether to use it.

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

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

Schema description coverage is 100%, so the schema already documents type, context, and message thoroughly. The description reinforces the type enum and adds practical nuance beyond the schema, such as '1-2 sentences typical, 2000 chars max' and 'don't paste the end-user's prompt.' It adds value while the schema remains the primary reference.

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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools by being the only feedback tool, and enumerates concrete categories (bug, feature, data_gap, praise).

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 ('Use when a tool returns wrong/stale data...') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also tells the agent to describe issues in terms of Pipeworx tools, providing clear actionable guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, cached with varying 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?

Two sentences plus a concise bullet list and caching note. Every part is informative. No redundancy or filler.

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

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

For a simple tool with 1 parameter, full annotations, and no output schema, the description covers purpose, use cases, caching, data source, and privacy. No missing information.

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

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

Schema covers the single parameter with enum and description. Description adds nuance about short vs long windows ('surfaces hot right now' vs 'steady-state demand'), providing extra 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 returns trending tools, packs, and call volume over a window. It uses specific verbs ('returns') and specifies the resource (Pipeworx trends). Distinguishes from siblings like discover_tools (which lists all tools) and ask_pipeworx variants.

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?

Three explicit use cases are provided (discovering hot sources, confirming canonical tool, aligning use case). No when-not or alternative tools mentioned, 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?

The description adds value beyond the annotations (which indicate read-only, idempotent, non-destructive behavior) by detailing the scanning logic, fill check condition, and that it does not execute trades. It does not contradict annotations and transparently discloses constraints like semantic anchor and partition filter.

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 well-structured with section headers and bullet points. It front-loads the core purpose and mode selection. Some sentences are lengthy but not wasteful; overall it efficiently conveys complex logic.

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 output schema, the description thoroughly covers behavior, modes, edge cases (fill check, similarity threshold), and response structure. It is self-contained and 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 description coverage is 100%, and the description adds rich context: explains event slug format, acceptance of full URLs, topic mode's cross-event search, semantic anchor, and partition filter. It significantly enhances understanding beyond the schema 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?

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (no args, event, topic) with distinct behaviors and distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by its unique arbitrage detection logic.

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 guidance on when to use each mode: no args for trending scan, event for specific event (recommended), and topic for cross-event scanning. It also explains when not to trade based on fill check results. However, it does not directly compare to sibling tools or mention when to choose this tool over 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?

Describes internal model families, segmentation, diagnostics, and caching behavior, adding significant context beyond annotations. No contradiction with readOnlyHint, idempotentHint, or other 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 lengthy and detailed, which aids clarity but lacks conciseness. Front-loading the purpose helps, but the technical breakdown could be more succinct without losing value.

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

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

Despite no output schema, the description fully explains the response structure, diagnostics, and caching, making it contextually 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 decent descriptions, but the tool description adds value by explaining the rationale, defaults, and usage of key parameters like min_liquidity and max_spread_pp as 'tradeable-edge filters'.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using specific verbs and resources. It differentiates from siblings by focusing on model-driven edge detection, not arbitrage or tracking.

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

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

The description implies usage for discovering betting opportunities ('what should I bet on today') but does not explicitly exclude alternatives like polymarket_arbitrage or edge_tracker. No when-not-to-use guidance is 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 cover read-only, idempotent, non-destructive. Description adds substantial context: daily snapshots, decay from daily closes, TTL limits, gaps, and response structure. 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?

Front-loaded with purpose and key concept. Detailed but not excessively verbose given the tool's complexity. Could potentially trim minor details but remains 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?

No output schema exists; description fully explains response fields (tracked[], expired[], snapshot_dates[]) with interpretation. Covers limits, defaults, and edge cases comprehensively.

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. Description adds defaults (days=14, max 30; window='1wk'), clamps, and context (decay uses default slippage). Adds value beyond schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question. It distinguishes from siblings like polymarket_edges (current edges) and polymarket_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?

Describes use case for assessing edge history vs freshness, and contrasts a fresh wide edge with an old one. Implicitly advises against intraday use but does not explicitly reference sibling tools for 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant behavioral detail: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and describes the behavior in basket mode (theoretical_sum vs realizable_sum, capture_ratio, thin_legs). It also discloses the risk of forced directional risk. 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 relatively long but well-structured with sections for single-market and basket modes, and clear listing of return fields. It is front-loaded with the core purpose. Some use of all-caps for emphasis (e.g., 'REQUIRES', 'USE THIS') is slightly verbose, but every sentence adds valuable information for the agent, earning a high conciseness score.

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

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

Given the complexity of the tool (two modes, multiple return values, no output schema), the description is remarkably complete. It explains all return fields (top_of_book, vwap, slippage, shares_filled, verdict, etc.), covers defaults, and highlights critical warnings about partial fills and forced directional risk. This allows the agent to understand the tool's behavior without needing additional 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 coverage is 100%, with each parameter already described. The tool description adds mode-specific semantics, such as default values for `side` in single-market vs basket mode, the interpretation of `size_usd` (settlement notional in basket mode), and the requirement for either `market` or `event`. This provides meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It explicitly distinguishes between single-market and basket modes. It also positions itself relative to sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', making its purpose distinct.

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

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

The description provides explicit guidance on when to use: before acting on arb signals or large trades. It specifies the requirement for one of `market` or `event`, explains both modes, and warns about the risk of partial fills converting arb into unhedged directional positions. It also gives default values and usage context for parameters.

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 readOnlyHint, openWorldHint, idempotentHint; the description adds significant behavioral detail: compatibility_warning fires for non-equivalent bet shapes or semantically unrelated events, temporal_alignment indicates whether months align, and skipped_cross_type/cross_subtype expose dropped comparisons. 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 relatively long but each sentence adds value. It is front-loaded with the main purpose and then details modes, response structure, safety fields, and warnings. Could be slightly more structured with bullet points, but the flow is logical and comprehensive.

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 explains the response structure: leg-by-leg prices, spread array, compatibility_warning, temporal_alignment, and skipped_* counters. It covers edge cases like non-equivalent bet shapes and temporal misalignment. The description is complete for a complex tool with 3 parameters and two usage modes.

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 three parameters documented). The description adds value by explaining the two modes: topic (pre-mapped shortcuts) vs explicit (kalshi_event_ticker + polymarket_event_slug). It lists all 10 topic values and explains that explicit parameters override topic-mapped sides. This goes 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 clearly states it's a cross-venue spread tool between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit event identifiers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue pricing differences.

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 guidance on when to use the tool (computing spreads between venues) and when not (via compatibility_warning and temporal_alignment fields). It explains that pre-mapped topics often return warnings, effectively telling the agent when the result is not tradeable. It also offers alternatives: explicit event tickers for custom pairings.

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. The description adds valuable context: scoping to identifier (anonymous IP, BYO key hash, account ID) and behavior when key omitted (lists all keys). 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 with no waste. The first sentence states core functionality, the second provides usage context and pairing. Information is front-loaded and each 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?

With one optional parameter, no output schema, and annotations present, the description covers all necessary context: workflow (save/recall/forget), scoping, and listing behavior. No gaps.

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

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

Schema coverage is 100% and the schema description already explains the parameter fully. The description restates this information without adding new semantics, meeting the 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 clearly states the verb (retrieve/list) and resource (saved values via remember). It distinguishes the tool from siblings (remember, forget) and provides concrete use cases (user's target ticker, address, prior research notes).

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

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

The description explains when to use: to look up context stored earlier without re-deriving it. It implicitly identifies alternatives (remember, forget) but does not explicitly 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?

The description explains the mark_read parameter's effect (flags events as read so next call shows newer ones), adding context beyond the readOnlyHint annotation. 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 four sentences, concise, and front-loaded with the core purpose. Every sentence adds value without unnecessary details.

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

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

Given the absence of an output schema and required parameters, the description sufficiently describes the output (source, citation_uri, payload) and provides usage context (polling, API alternative). It is complete for a read-only fetch tool.

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

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

The description adds context to parameters, e.g., explaining that type filters by subscription type and since is an ISO timestamp. This enriches the schema descriptions, which already had 100% coverage.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It differentiates from sibling tools like list_subscriptions and recall by focusing on retrieving alert events.

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 filtering options (type, since) and mentions that polling works fine, offering an alternative API endpoint. However, it does not explicitly state when not to use this tool or compare it to siblings.

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

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

Beyond annotations, the description details internal fan-out to SEC EDGAR, GDELT/GNews fallback, and USPTO with soft-fail behavior, plus return structure (changes[], total_changes, citation URIs). No annotation 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 well-structured with examples first, then source details, then parameters, and differentiation. It is slightly verbose for a tool description but every sentence contributes meaningful 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?

Comprehensive for a complex tool with multiple data sources and no output schema: describes return format, source behaviors, rate-limit fallbacks, and window formats. Fully covers what an agent needs 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 coverage is 100%, but the description adds valuable context: relative date shorthand formats, example ticker/CIK inputs, and recommendation for typical monitoring window ('30d' or '1m').

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 a change feed for a company over a recent window, using specific verbs like 'What's new with X' and explicitly distinguishes from the sibling tool entity_profile 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?

The description provides explicit when-to-use guidance with example queries and directly tells the agent to use entity_profile for static profiles, offering clear context on tool selection.

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

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

Discloses key-value storage, scoping by identifier, and persistence duration (24h/anonymous vs persistent/authenticated). Annotations support non-destructive, non-readOnly, idempotent 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?

Three concise sentences, front-loaded with purpose. No fluff; every sentence adds essential context.

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

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

Covers all needed context: purpose, when to use, behavior, persistence, and relation to siblings. No gaps given tool 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 already describes both parameters with examples. Description adds value by providing usage conventions for keys and value types.

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+resource ('Save data') with explicit purpose ('reuse later'). Distinguishes from sibling tools 'recall' 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?

States when to use ('when you discover something worth carrying forward') and mentions pairing with recall/forget. Also scoping and persistence details.

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, and non-destructive behavior. The description adds valuable context: it cascades through multiple endpoints, returns citation URIs, and auto-disambiguates inputs. 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 dense but efficiently organized: starts with concrete user queries, states the primary use, then details supported types and returns. No fluff; every sentence contributes actionable information.

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

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

For a tool with no output schema, the description provides sufficient detail about return values, citations, and input handling. It also conveys the internal complexity (cascading lookups) and positions the tool as a replacement for multiple manual steps, making it complete for both selection and invocation.

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

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

Although schema coverage is 100%, the description enriches both parameters significantly. It explains what each entity type returns, the accepted input formats for 'value' (ticker, CIK, name, brand/generic), and the auto-disambiguation behavior. This adds meaning far 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 resolves a user-spoken name to the canonical identifier required by other tools. It gives concrete examples ('ticker', 'CIK', 'RxCUI') and distinguishes itself from siblings by emphasizing this is the first step when an ID is needed.

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 FIRST whenever you have a name but need an ID,' which is strong contextual guidance. It does not explicitly mention when not to use it or name alternatives, but the supported types and examples make the usage scope 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density. No contradictions with annotations.

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

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

Two sentences plus a parenthetical example. Every sentence adds value: main action, use case, return details. 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?

Given no output schema, the description explains return type (ranked list with score, confidence, signal density). It covers what the tool does, but lacks details on pagination or error handling. Still sufficiently complete for its 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%, so baseline is 3. The description adds that 'entities' are 2-8 items with first entry treated as 'subject', and 'context' disambiguates common names. This provides useful nuance 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 it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single probe) and compare_entities (generic comparison).

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 a concrete use case ('competitive AI-marketing audits') and an example question ('does Claude know about us...'). It does not explicitly list when not to use or alternative tools, but context is clear enough for an AI 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?

Beyond annotations (readOnly, idempotent), the description discloses that bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timeouts. 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 dense and front-loaded with the main purpose, but it is slightly long. However, every sentence provides useful information, and there is no redundancy. Could be slightly more structured but efficient.

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

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

Given the complexity (composite tool, two services, partial failures, timeout behavior), the description thoroughly covers what the tool does, what it returns, its limitations (npm only), and edge cases. No output schema exists, so the description adequately explains return values.

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 covers both parameters (100% coverage) with descriptions. The tool description adds marginal value by mentioning scoped packages and default version behavior, but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's composite nature, combining deps.dev and bundlephobia to answer 'should I add this npm package?' It distinguishes itself from siblings by being npm-specific and aggregating multiple concerns.

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

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

Explicitly says when to use it ('is X safe / popular / small') and when not to (other ecosystems, pointing to deps.dev:version directly). Provides clear guidance on 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses specific behavioral traits: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also notes that every passage carries an offset for quote verification, which is critical for agent decision-making.

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 and well-structured. It begins with the core functionality in the first sentence, then explains when to use, pairs with a sibling tool, and ends with technical details. Every sentence serves a purpose without unnecessary repetition.

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

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

Despite lacking an output schema, the description fully explains the return structure (passages with offsets and similarity scores) and algorithmic details. It also covers constraints (character limit, window size, truncation behavior) and provides a usage scenario, making it complete for an AI agent to understand and 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 coverage is 100%, so baseline is 3. The description adds value by providing example queries for the 'query' parameter and explicitly stating the default value for 'limit' (5) and the max character limit for 'text' (200K). These details are practical and enhance understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record' and specifies the input (text and natural-language query) and output (top-N passages with character offsets and similarity scores). It also distinguishes from sibling tools by mentioning how it pairs 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?

Provides explicit guidance on when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also suggests an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 non-read-only, idempotent, non-destructive behavior. The description adds crucial context: requires OAuth account, BYO/anonymous cannot persist, webhook signing secret returned once, auto-disable after 10 failures, and SMS daily cap. 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 well-structured, front-loading the core purpose and then detailing types and delivery. Some redundancy with schema descriptions is present but acceptable given the complexity. No wasted sentences, though length could be reduced slightly without losing information.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is highly complete: it covers all types, delivery options, prerequisites, and failure behaviors. Minor gap: the idempotentHint annotation suggests repeated calls may be safe, but description doesn't address duplicate subscription behavior.

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

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

The input schema has 100% description coverage, but the tool description adds significant meaning beyond the schema: it explains each enum value for 'type' with real-world examples, provides detailed parameter structures for each type, and elaborates on delivery constraints (phone verification, webhook signing, auto-disable).

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 explicitly states the tool creates a subscription ('Create a proactive monitoring subscription to a live-data event stream') and returns the subscription ID. It lists supported types and delivery channels, clearly differentiating from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides context on when to use the tool (to create a persistent subscription) and prerequisites (Pipeworx OAuth account, phone verification for SMS). It implicitly distinguishes from one-off queries or listing tools but does not explicitly state when not to use it or mention all 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 confirm the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. This goes beyond the annotations to explain the output nature.

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 well-structured with a front-loaded purpose statement and clear sentences. It is slightly verbose but each sentence contributes value, especially for an onboarding tool. It could be more concise, but the level of detail is appropriate for the tool's role.

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 return format (category-bucketed example questions with tool+argument shapes) and provides a list of categories. Combined with usage guidance and parameter details, it leaves no significant gaps for an agent to understand how to use this 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 a clear description for the topic parameter. The description enriches this by listing the categories (finance, pharma, etc.) in context and explaining that omitting topic gives a cross-category spread. This adds meaning 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's purpose as an onboarding entry point for new agents, using specific verbs like 'returns category-bucketed example questions' and 'learn how to call the meta-tools'. It distinguishes itself from sibling tools by positioning it as the first tool to call when unsure about Pipeworx's capabilities.

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 on when to use the tool ('FIRST when you do not yet know what Pipeworx can do') and how to use it (no arguments for full spread, topic argument to focus). However, it does not explicitly state when to avoid it or compare to alternatives, though the context implies its unique role.

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 non-destructive and idempotent, and the description adds that the row is deactivated (not deleted) and ownership is enforced. This goes beyond annotations, providing useful 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?

Two sentences that are front-loaded with the action and efficiently convey the purpose, constraint, and effect. No redundant information; each sentence adds essential value.

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

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

For a simple tool with one fully documented parameter and annotations covering safety, the description covers ownership, non-destructive behavior, and historical event availability. It is complete and 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 has 100% coverage with clear description of the 'id' parameter ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter detail beyond the schema, so baseline score applies.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from sibling tools like 'subscribe' (opposite), 'list_subscriptions' (listing), and 'recent_alerts' (historical events), making the purpose unambiguous.

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

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

The description mentions 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear usage context. It does not explicitly state alternatives but implies when not to use (not for others' subscriptions) and references 'recent_alerts' for historical access.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds details about the dual pipeline, use of percent-delta math, routing to live sources, and output verdicts, providing significant 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 example phrases and purpose, but it is lengthy with detailed explanations of the two pipelines. Some sentences could be more concise without losing meaning.

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

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

Despite no output schema, the description lists the verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported) and the return format (value with citation, reasoning). It adequately covers the tool's behavior for its 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 for both parameters. The description adds value by explaining the default tolerance_pct behavior and the impact of overriding it, going beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with example phrases. It distinguishes between company-financial claims (fast path) and other claims (grounded pipeline). However, it does not explicitly differentiate from sibling tools like deep_research or 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?

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides specific scenarios for claim types. It gives context on when to use the fast path vs. grounded pipeline but does not include explicit exclusions or alternatives.

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