Data Kcmo

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral context: default probes Workers AI, can probe Anthropic with key, returns per-model and combined data. No contradictions; adds value 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?

Concise paragraph with all essential information front-loaded. Every sentence adds value: purpose, default, keyed alternative, return format, use cases. No fluff.

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

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

No output schema, but description adequately explains return structure (per-model data + combined view). Parameters are fully described. Sufficient for agent to understand inputs, outputs, and 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?

Schema coverage is 100%, but description adds meaning: explains default model, usage of _apiKey, and purpose of context for disambiguation. Adds usage hints beyond the schema.

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

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

Clearly states it probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. Specifies default model, optional API key, and return format. Distinguishes 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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides clear context for when to use, including note that Anthropic requires a BYO API key. Does not explicitly exclude alternatives but gives enough 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 and idempotentHint, so the safety profile is clear. The description adds valuable context about how the tool routes questions to 4,774 tools and returns structured answers with citations. 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 lengthy but well-structured, starting with a clear preference statement, then listing use cases, alternatives, and examples. While it could be slightly more concise, every sentence adds value, and the structure aids readability.

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 the output format (structured answer with citations) and mentions it works on every tier. It covers what, when, and why to use the tool, though it could mention limitations or error handling.

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 multiple aliases described. The description adds no additional meaning beyond what the schema already provides for the 'question' parameter. Baseline of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as a superior alternative to web search for factual questions about structured data. It lists many specific data types (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by specifying when to use ask_pipeworx_grounded or deep_research instead.

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 recommends using this tool first ('START HERE for most questions') and provides clear guidance on when to step up to alternative tools. It provides numerous example questions and usage scenarios, making it easy for an agent to decide when to invoke 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?

Discloses grounded extraction, refusal reasons, and extra LLM call beyond annotations (readOnlyHint, idempotentHint, etc.). 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 key purpose, then explains routing and return format. Slightly long but every sentence adds value.

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

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

Fully explains behavior, return outcomes, use cases, and limitations. Handles complexity well without 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% with clear descriptions for all 6 aliases. The description does not add new parameter 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 purpose as a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism. It distinguishes from sibling ask_pipeworx by noting the extra LLM call cost.

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 provides when to use (quoted, cited, or acted-on answers; high-stakes domains) and when not to use ('prefer ask_pipeworx for casual lookups').

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

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

Discloses extensive behavioral details beyond annotations: fan-out logic, response shapes, resolver contract with confidence levels, parent_event extraction, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and resolution-rule risk. This greatly exceeds what annotations (readOnly, idempotent) 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?

Very long and detailed, with many examples and edge cases. While comprehensive, it is not concise; the length may overwhelm an agent. Front-loads the main purpose well, but subsequent sections are verbose.

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

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

Given the tool's complexity, the description is remarkably complete. It covers every aspect: input, processing, fan-out, response structure, error conditions, and safety checks. No output schema exists, so description must cover return values, which it does thoroughly.

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?

Adds substantial meaning beyond the input schema: explains that market can be slug, URL, or question text; describes depth choices (quick vs thorough with consequences); clarifies include_raw use case (when to keep responses small vs full payloads). Schema coverage is 100%, but the description enriches understanding.

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 researches a Polymarket bet by pulling Pipeworx data. Specifies the verb 'Research' and resource 'Polymarket bet', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on single bet analysis.

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 examples ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'), giving clear context. However, it does not explicitly mention when not to use it or list alternatives among siblings, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), sorting behavior, citation URIs, and handling of off-calendar fiscal years. 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 somewhat long but well-structured: trigger phrases first, then behavior details. Every sentence adds value, though minor redundancy exists (e.g., 'side-by-side' and 'parallel call').

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, description covers return format (paired data + citation URIs), data sources, sorting, and edge cases (off-calendar fiscal years). Complete for a comparison tool with 2 parameters.

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, baseline 3. Description adds context: for company use tickers/CIKs, for drug use names, and clarifies that values are array of 2–5 items. This complements schema well.

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

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

The description clearly states the tool does side-by-side comparison of 2–5 companies or drugs in one parallel call, with trigger phrases like 'compare X and Y'. It distinguishes from siblings like entity_profile by emphasizing bulk 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides guidance on when to use each type (company vs drug), helping agents choose correctly.

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 read-only and idempotent. The description adds critical behavioral context: account requirement, paid plan for 'thorough' depth, parallel decomposition, returns gaps[] for unanswered facets, 15-60s latency, and that it is not open-web search. 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 thorough and well-structured but slightly lengthy. It front-loads the most critical information (account requirement, alternative tool) and uses clear sections. Could be tightened 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?

Given the tool's complexity (1242 data sources, 4774 tools, parallel execution), the description covers all essential aspects: purpose, input guidelines, output format (findings packet with evidence, confidence, source, citations, gaps[]), constraints, and alternatives. 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?

Both parameters are described in the schema (100% coverage). The description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8) and suggesting question phrasing (natural language, broad is fine). The schema itself only lists enum values without mapping to facet counts.

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 specifies the tool's function: grounded multi-source research across 1242 structured data sources, decomposing questions into facets and executing parallel tool calls. It distinguishes itself from siblings like ask_pipeworx by stating it is not for single lookups or breaking news.

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

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

Explicit when-to-use (broad/multi-part questions over structured data) and when-not-to-use (breaking/current news, prefer ask_pipeworx). Also provides account prerequisites and alternative tool if not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This clarifies what the output contains and its usability.

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 front-loaded with the core purpose. It includes a list of domains and an explanation of the return value. Each sentence adds value, though the list of domains could be trimmed without losing meaning. Overall well-structured.

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

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

Given the complexity (6 params, no output schema), the description explains the tool's return format fully. It covers the main parameter, aliases, and usage context. Lacking mention of ordering or determinism, but for a discovery tool these are minor omissions.

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 parameters having descriptions. The description mentions aliases for 'query' which are already documented in the schema. It adds no new semantic information beyond what the schema provides, meeting the baseline but not exceeding it.

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

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

The description clearly states 'Find tools by describing the data or task.' and specifies the domains it covers. It distinguishes this tool from siblings by emphasizing it is the primary discovery mechanism, with no sibling offering similar functionality.

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 when you need to browse, search, look up, or discover what tools exist for: [domains].' and advises to 'Call this FIRST when you have many tools available.' No explicit mention of 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?

Beyond annotations (readOnlyHint, etc.), the description details behavioral traits: parallel fanning across multiple sources, soft-fail for USPTO sunset, GDELT→GNews fallback, and specific return fields. 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 slightly long but well-structured, front-loading use cases and key advice. Every sentence adds value, though minor redundancy exists (e.g., 'full cross-source profile' then listing sources).

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 explains return fields (CIK, filings with URIs, fundamentals, patents, news, LEI), limitations, and fallbacks (USPTO sunset, GDELT→GNews), leaving no critical gaps.

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

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

The input schema covers 100% of parameters with descriptions. The description adds examples (e.g., 'AAPL', '0000320193'), clarifies that only company type is supported, and explicitly states that names are not accepted, enhancing 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 explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists example queries, differentiates it from chaining multiple lookups, and names sibling tools like resolve_entity for name resolution, making its purpose very clear.

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

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

The description includes explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity if only a name is available, clearly indicating when to use this tool versus alternatives.

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

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

The description aligns with annotations: destructiveHint=true and idempotentHint=true are consistent with 'Delete a previously stored memory by key'. It adds behavioral context about the purpose (clear stale or sensitive data). 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 concise sentences front-load the action and include usage guidance. Every sentence earns its place without unnecessary verbosity.

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 delete tool with one parameter and no output schema, the description provides sufficient context: what it does, when to use it, and related tools. Annotations cover behavioral aspects.

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 fully describes the 'key' parameter with 100% coverage. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'), effectively distinguishing it from sibling tools 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 states when to use the tool ('context is stale, task is done, clear sensitive data') and mentions related tools ('Pair with remember and recall'), providing clear context and 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, openWorldHint, idempotentHint, destructiveHint false. Description adds that it fetches the page and extracts title/description/key links, which is consistent. It doesn't reveal additional side effects beyond the read-only nature, but the annotations cover the safety profile adequately.

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 two sentences plus a usage list. It is front-loaded with the main action. Slightly verbose in the usage list but still efficient. No wasted words.

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

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

Given no output schema, description explains the output format: 'standard llms.txt markdown format' and 'a single text blob ready to drop at site-root/llms.txt.' This is sufficient for an agent to understand what to expect. Input is well-covered with schema and parameter descriptions.

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 'url' and 'max_links' described clearly. The description mentions 'max_links' but adds no new meaning beyond the schema. Baseline 3 is appropriate since the schema handles parameter semantics.

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

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

Description clearly states it generates an llms.txt file for a URL. The verb 'generate' and resource 'llms.txt' are specific. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file creation rather than scanning.

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 provides explicit 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.' This guides when to use the tool. No explicit when-not-to-use, but the specific nature makes it clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and non-destructiveness. The description adds context about the source catalogue and return fields, but does not elaborate on rate limits or api key behavior beyond the schema.

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 the action verb 'Search', and every word 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?

With four optional parameters and no output schema, the description covers the tool's purpose, return content, and connection to kcmo_query. It lacks explicit pagination behavior, but offset/limit parameters are self-explanatory.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. It adds value by explaining the purpose of the returned resource IDs, but that is not parameter-specific.

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

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

The description clearly states the tool searches a specific open-data catalogue by keyword and returns dataset names, descriptions, and resource IDs, directly tying the output to usage with kcmo_query.

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 keyword-based dataset discovery and hints at connection to kcmo_query, but it does not explicitly state when to use this tool versus its siblings (kcmo_query, kcmo_recent) or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, destructiveHint; description adds behavioral details like default limit (100) and max (5000), which is useful but not critical. 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 concise sentences, front-loaded with purpose, 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?

Covers all needed aspects: purpose, usage, parameters, references sibling tools, and explains optional API key. No output schema needed per instructions.

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. Description adds context about full SoQL syntax, default limit/max, and explains resource_id format, providing extra 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?

Description clearly states verb ('Run a raw SoQL query'), specific resource ('Kansas City, MO open-data resource via data.kcmo.org'), and distinguishes from sibling tools (kcmo_datasets, kcmo_recent).

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 ('to run a raw SoQL query') and directs to alternatives ('Use kcmo_datasets to find a resource id, or kcmo_recent for the common ones').

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful behavioral context: 'Returns the latest rows (newest-first)' and the ability to add SoQL filters. This enhances transparency 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 concise (three sentences) with the most critical information first: purpose, preferred use cases, dataset names, and behavior. Every sentence serves a purpose without redundancy.

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

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

Given the tool's simplicity and no output schema, the description adequately covers what the tool does, when to use it, the datasets available, and how to filter. It references the sibling tool for complex queries, providing complete context for an 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% with clear descriptions for all four parameters. The description reinforces the 'where' filter use but does not add significant new meaning beyond the schema. A score of 3 is appropriate per guidelines.

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

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

The description specifies the tool returns 'Recent records from a common Kansas City, MO open dataset' using a friendly name, listing exactly two datasets (311, crime). It explicitly contrasts with web search and sibling tool 'kcmo_query', making its role 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 gives clear guidance: 'PREFER OVER WEB SEARCH' for specific queries like 'recent crime in Kansas City, MO', and 'for anything else use kcmo_query'. This tells the agent when to use this tool and 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?

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds return field details but doesn't cover pagination or ordering, which is acceptable for a simple list.

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 return fields, followed by usage guidance. No redundant information.

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

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

For a simple read-only list tool with rich annotations and one optional parameter, the description covers purpose, return fields, default behavior, and usage context. Missing details like pagination limits are minor.

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 parameter description. The description reinforces the default behavior ('active subscriptions') and adds context beyond the schema by implying the default for include_inactive.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies return fields (id, type, params, etc.), and 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?

Explicitly advises using this tool to review monitored subscriptions before adding more or to find an id to cancel, providing context for when to use it relative 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?

Description adds valuable behavioral context beyond annotations: it's free, doesn't count against quota, rate-limited to 5/day, and the team reads digests daily. 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 concise, front-loaded with purpose, and every sentence adds value. No unnecessary information 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?

Given the tool's simplicity and no output schema, the description fully covers input semantics and usage context. It is complete for effective agent use.

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 by explaining enum values and providing examples. It complements the schema well without redundancy.

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

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

Description clearly states the tool sends feedback to the Pipeworx team, listing specific use cases (bug, feature, data_gap, praise). It distinguishes itself from sibling tools which are primarily query or data retrieval tools.

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

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

Explicitly provides when-to-use scenarios (broken/stale data, missing tools, praise) and what not to do (don't paste end-user prompt). This helps the agent determine 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?

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: it's self-aggregating, derived from CF analytics-engine with no PII, and cached 5min-1h depending on window. This goes beyond the annotations and provides a complete safety and performance profile.

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

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

The description is three sentences: first sentence states main function, second lists use cases, third adds technical details. Every sentence is purposeful and front-loaded. Zero waste.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what the tool returns (top tools, top packs, total call volume), the nature of the data (aggregated, no PII), caching behavior, and purpose. It is complete for effective use.

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 for the single optional parameter 'window' with enum and description. The description adds interpretive semantics: 'shorter windows surface what's hot right now; longer windows show steady-state demand,' which enriches the schema-provided 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 clearly states the tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources ('returns the top tools, top packs, and total call volume'), and distinguishes itself from siblings as an aggregation/trending tool, especially given the explicit mention of being derived from CF analytics-engine.

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 concrete use cases (discovering hot data sources, confirming a canonical tool, aligning use case with demand) and explains the meaning of different windows. While it doesn't explicitly state when not to use or list alternatives, it provides clear context for when the tool is most valuable.

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 read-only, idempotent, and non-destructive. The description adds extensive behavioral context: monotonicity violation detection, partition-sum checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check against live depth. 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 thorough but verbose, containing multiple sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and detailed explanations. While well-structured, it could be more concise 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 format (opportunities[], partition_check fields, fill_check data). It also covers failure modes (skipped_low_similarity) and edge cases, making it self-contained for agent invocation.

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

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

Schema coverage is 100% with descriptions for 'event' and 'topic'. The tool description enriches these with usage examples (e.g., 'fed-decision-may-2026') and explains what each mode does in detail, adding value beyond the schema.

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

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

The description starts with a clear verb-resource pair: 'Find arbitrage opportunities on Polymarket' and specifies the method (monotonicity violations + partition-sum checks). It distinguishes from sibling tools by mentioning specific modes and checks not present in others.

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 each mode: no args for trending scan, 'event' for specific market, 'topic' for cross-event scanning. Examples of slugs and seed questions are provided. Lacks explicit when-not-to-use cases, but the specificity compensates.

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, and destructiveHint=false. The description adds rich behavioral context: caching strategy (1h at KV level), response structure (by_segment, fed_candidates, diagnostics), edge calculation details, and warnings like the 24h-move alert. 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 quite lengthy and packed with technical details, resembling a specification rather than a concise summary. It is well-organized with sections and examples, but it could be more concise. Not all details (e.g., exact model parameters like α values) are essential for basic tool selection.

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 (9 parameters, multiple segments, no output schema), the description is remarkably complete. It covers all response fields (edge_pp_net, kelly_fraction, market metadata, diagnostics) and explains edge calculation, filter behavior, and caching. 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 coverage is 100%, so the schema already provides good descriptions for all 9 parameters. The description supplements this by explaining how knobs like min_liquidity and max_spread_pp act as tradeable-edge filters, and clarifying defaults and usage context. While helpful, the schema alone is already strong, so the description adds incremental value.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from sibling tools by specifying three model families and segments (model_driven, structural_arbitrage, concentrated_longshot), making it clear that this tool covers a broader scope than, say, polymarket_arbitrage alone.

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

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

Explicitly built for 'what should I bet on today' without paging hundreds of markets. Provides detailed knob descriptions (min_liquidity, max_spread_pp, etc.) that guide when to adjust filters. Also notes that Fed bets are excluded from ranking due to unreliable signal, giving clear usage boundaries.

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 safe read-only behavior. Description adds limits (60-day TTL, snapshot gaps), decay computation basis, and response structure, surpassing annotation coverage.

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

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

Front-loaded with purpose, then args, then response. Slightly verbose but well-organized. Every sentence adds value.

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

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

Despite no output schema, description details response format (tracked, expired, snapshot_dates), trend computation, and limitations. Fully covers what the tool returns.

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%. Description adds context: days lookback default and max, window family, and explains that snapshot_dates show data gaps, enhancing understanding beyond schema.

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

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

Description clearly states it provides edge persistence and decay telemetry, differentiating from current snapshot tools like polymarket_edges. It answers the specific question 'how long has this edge existed and is it shrinking?'

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 for assessing edge trustworthiness over time, contrasting fresh vs old wide edges. No explicit when-not-to-use, but context is strong given sibling tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral detail: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains basket mode with forced directional risk, and warns about thin books and partial fills. No contradiction.

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

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

The description is well-structured with clear sections for SINGLE-MARKET and BASKET, and front-loaded with the core purpose. While it is somewhat lengthy, every sentence adds necessary information. Minor room for tighter phrasing but overall 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 values for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single; theoretical_sum, realizable_sum, capture_ratio, etc. for basket). It also covers parameter details, modes, and critical risk warnings about thin books and partial fills. Complete 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%, so baseline is 3. The description adds value beyond schema by explaining parameter behavior: `side` default and auto-detection in basket mode, `size_usd` interpretation differences between single-market and basket, and context for `market` and `event` parameters. This justifies a higher score.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It explains both single-market and basket modes, and explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by stating where to use this tool before acting on their signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risk of not using it (conversion of arb into unhedged directional position) and specifies required parameters and defaults.

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 read-only, open-world, and idempotent behavior. The description adds critical behavioral details: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped cross-type/subtype counters. It goes well beyond the annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is slightly long but every sentence adds meaningful information. Front-loaded with the core 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?

Despite not having an output schema, the description fully explains the response structure (leg-by-leg prices, matched spreads, compatibility fields). It covers parameter usage, edge cases (temporal mismatch, shape mismatch), and safety fields. 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% with descriptions for each parameter. The description adds value by explaining the two modes (topic vs explicit), listing the topic shortcuts, and specifying override behavior. This enhances understanding beyond the schema.

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

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

The description opens with a clear verb-noun phrase 'Cross-venue spread' and specifies the two resources (Kalshi and Polymarket). It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The two modes and response contents are explicitly stated.

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

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

The description explains when to use the tool (to find cross-venue spreads) and warns about compatibility issues and temporal alignment. It provides clear mode selection guidance but does not explicitly contrast with alternative tools like bet_research or compare_entities.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it is scoped to the agent's identifier, providing 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 concise and front-loaded with core functionality. It could be slightly tighter but remains 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 tool with no output schema, the description covers key points: retrieval, listing, scoping. It does not detail return format but is sufficient.

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

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

Schema coverage is 100% for the single parameter. The description adds meaning by explaining omission behavior, complementing 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 retrieves a value saved via remember or lists all keys if omitted. It distinguishes from siblings like 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?

The description explains when to use: to look up context stored earlier. It does not explicitly state when not to use or name alternatives, 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 claims that setting mark_read:true flags returned events as read, which is a state change. However, annotations declare readOnlyHint: true, indicating the operation is read-only. This is a direct contradiction. The description also provides behavioral details beyond annotations (return fields, polling suitability), but the contradiction outweighs these.

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 three sentences, front-loaded with the main action, then return fields, then parameters and alternatives. Every sentence adds value without fluff. It is well-structured and easy to scan.

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

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

Given no output schema, the description adequately explains the return fields (source, citation_uri, raw payload), filtering options, polling suitability, and an alternative access method. It lacks details on error handling, rate limits, or edge cases, but for a read-only tool with clear parameters and annotations, it is fairly complete. The contradiction slightly reduces confidence, but completeness is still good.

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

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

The input schema already documents all 5 parameters with clear descriptions (100% coverage). The description reinforces the filtering parameters (type, since) and mark_read behavior, but does not significantly add new meaning. It provides an example type ('sec_8k'), which is helpful but not critical. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It uses specific verbs ('pull', 'returns') and identifies the resource ('fired events', 'alerts'). This distinguishes it from sibling tools like 'list_subscriptions' (which lists subscriptions) and 'recent_changes' (which shows changes, not 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 explains filtering by type and since, and mentions that polls work fine. It also provides an alternative access method (GET registry.pipeworx.io/alerts.json for scripts/dashboards), giving context on when to use this tool vs. direct HTTP. However, it does not explicitly compare to sibling tools like 'subscribe' or 'list_subscriptions' for subscription management, leaving some implicit differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral details: data sources (SEC, GDELT, USPTO), fallback logic (GDELT→GNews on rate limit), failure conditions (PatentsView sunset), and return structure (changes grouped by source). No contradictions.

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

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

Single paragraph is well-structured and front-loaded with query examples. Every sentence adds value. Minor improvement could be breaking into sections, but highly efficient overall.

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 3 required params, no output schema, and no nested objects, the description is remarkably complete. It covers all sources, fallback behavior, parameter formats, and return structure. 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%. The description adds substantial value beyond the schema: explains 'since' accepts ISO dates or relative shorthand with examples, 'value' can be ticker or CIK, and 'type' context. This fully clarifies parameter usage.

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

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

Description clearly defines the tool as a 'change feed for a company' that fans out to multiple sources in one parallel call. It provides explicit query examples and distinguishes from the sibling 'entity_profile' 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?

Includes explicit usage contexts via example queries and states when to use 'entity_profile' instead. No alternatives for other siblings are mentioned, but the guidance is 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?

Annotations already mark the tool as idempotent and non-destructive. The description adds value by explaining memory scoping by identifier, persistence details (authenticated vs. anonymous, 24-hour retention), and the key-value storage model. 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 concise at four sentences, front-loads the primary purpose, and uses clear, actionable language. Every sentence adds value without redundancy.

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

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

Given two simple parameters, no output schema, and comprehensive annotations, the description covers all necessary context: purpose, usage, scoping, persistence, and related tools. It is fully adequate for an AI agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% with clear parameter descriptions. The tool description adds usage examples and naming conventions (e.g., 'subject_property') which provide extra context but do not fundamentally add meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('save') and resource ('data the agent will need to reuse later'). It distinguishes itself from sibling tools by mentioning pair tools (recall, forget) and provides concrete examples of usage (resolved ticker, target address, etc.).

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 includes explicit guidance on when to use ('when you discover something worth carrying forward') and provides practical examples. It suggests pairing with recall and forget but does not explicitly state when not to use or list alternatives for non-persistent storage. Still, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: each call cascades through several lookup endpoints, and it replaces 2-3 manual lookups. This complements the annotations well without contradiction.

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

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

The description is well-structured, starting with common user queries, then the core purpose, followed by supported types with specific details. Every sentence adds value; there is no fluff. It is appropriately sized 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 fully explains return values for each type, including citation URIs. With 2 required parameters, high schema coverage, and rich annotations, the description provides complete context for an agent to invoke the tool 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 descriptions for both parameters. The description enriches semantics by detailing what each type returns (e.g., company returns ticker, CIK, company_name, citation URI) and what input formats are accepted (ticker, CIK, or name for company; brand or generic for drug). This goes 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: resolving a user-spoken name to canonical/official identifiers. It provides specific examples (ticker, CIK, RxCUI) and differentiates from siblings by positioning it as the first tool to use when needing an ID. The verb 'resolve' and resource 'entity' are precise.

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 FIRST whenever you have a name but need an ID.' This provides clear guidance on when to use. However, it does not mention when not to use or direct alternatives among siblings like 'entity_profile' or 'compare_entities', which slightly reduces the score from a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it internally calls ai_visibility_check, ranks results, and returns score/confidence/signal density. This adds context beyond annotations, though auth requirements for specific models are left to schema.

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 are concise and front-loaded, stating action, process, use case, and output format. No wasted words.

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

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

Given no output schema, description explains the return format (ranked list with per-entity score, confidence, signal density). It also mentions internal call to ai_visibility_check. Adequate for a multi-entity comparison 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%, so baseline is 3. Description adds meaning by noting the first entity is treated as the 'subject' for narrative, and context is shared across probes. This supplements 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 tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks results, and identifies most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 'useful for competitive AI-marketing audits' and gives an example query. While it doesn't explicitly state when not to use or list alternatives, the purpose 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?

Beyond annotations (readOnlyHint, etc.), description discloses partial failure behavior, 5-30s delay for bundlephobia first measurement, and that sources_failed list timeouts. Adds context on fanning out across multiple sources.

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 main purpose first, then details. 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?

Covers all needed context: ecosystem limitations, return fields summary, partial failure behavior, and timing caveats.

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?

Adds meaningful details beyond schema: 'Scoped packages accepted' for package, and 'Defaults to latest version' for optional version parameter.

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

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

Description clearly states it's a composite check for adding npm packages, specifying covered aspects (license, advisories, bundle size, etc.). Distinguishes from siblings by noting NPM ecosystem only and mentioning deps.dev for other ecosystems.

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 agent asks about safety, popularity, size, or cost of adding a package. Also states when not to use: for non-NPM packages, use deps.dev:version directly.

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 transparency beyond annotations by detailing the embedding model (BGE-base-en), overlapping windows (500-char), and a clear cap of 200K chars with truncation flagging. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

The description is front-loaded with the main purpose and each sentence adds value. It is informative but not excessively verbose, though it could be slightly more compact.

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 (semantic search, embeddings, offsets), the description covers purpose, usage context, limitations (200K cap, truncation), and output format (passages with offsets and scores). No output schema exists, but the description adequately explains what is returned.

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 descriptions for all 3 parameters. The description adds context by explaining the truncation cap for the 'text' parameter and providing query examples, which slightly exceeds 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 it performs semantic search inside a fetched record and returns passages with character offsets and similarity scores. It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded, making its unique role evident.

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

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

The description explicitly advises using this tool when a record is too large for the prompt, saving context. It also explains pairing with ask_pipeworx_grounded, but does not explicitly state when not to use it or list direct 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 indicate mutation (readOnlyHint=false) and no destruction (destructiveHint=false). The description adds rich behavioral details: OAuth requirement, type-specific parameters, delivery channels (feed, email, sms, webhook) with constraints (e.g., 10/day SMS cap, webhook auto-disable, signing secret returned once). This goes well 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 efficient: two well-structured paragraphs. The first sentence states the core purpose. Then it covers account requirements, type examples, and delivery options. Every sentence adds value without redundancy. It is front-loaded and easy to parse.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers account prerequisites, type variants, delivery channel behaviors, and constraints. It references related tools (recent_alerts, registry endpoint). It sufficiently explains what the tool does and how to use it, leaving no obvious gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value by providing detailed examples for each type in 'params' (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps). For 'delivery', it explains each option, including constraints (verified phone, webhook signing) that are not in the schema descriptions.

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

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

The description clearly states the action ('Create a proactive monitoring subscription'), the resource ('subscription'), and the purpose ('to a live-data event stream'). It also mentions returning the new subscription id, which is specific. The sibling tools include list_subscriptions and unsubscribe, so 'Create' distinctly differentiates this tool.

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

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

The description specifies the account requirement (Pipeworx OAuth account) and excludes anonymous/BYO users. It lists supported types with examples but does not explicitly compare with alternatives like recent_alerts or polymarket_arbitrage. It does mention that the feed is always on and can be pulled via recent_alerts, providing context for post-subscription usage.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it is an onboarding entry point, results are drawn from a live catalog of thousands of tools, and it explains both full spread (no topic) and focused usage. 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 relatively long but well-structured. It front-loads trigger phrases, then explains the output and usage. Every sentence provides essential information, but a slight trim could be made without loss. Still, it is efficiently informative.

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 simplicity of the tool (one optional parameter), no output schema, and rich annotations, the description fully covers what the agent needs: when to use it, what it returns (category-bucketed example questions with tool shapes), and how to vary the call. No gaps detected.

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 already comprehensively describes the topic parameter (values, omission behavior). The description's parameter guidance ('Call with no arguments for the full spread, or pass topic to focus') adds minimal new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies this as the onboarding entry point for the agent, enumerating trigger phrases ('What can I ask?', 'give me ideas') and explicitly stating its purpose: to answer what Pipeworx is good for. It contrasts with sibling tools by mentioning meta-tools like ask_pipeworx and entity_profile as distinct tools, and describes the return value as category-bucketed example questions with exact tool+argument shape.

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

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

The description explicitly advises to use this tool FIRST when the agent does not know what Pipeworx can do. It provides clear context with trigger phrases and shows how to focus with the topic parameter. It does not explicitly state when NOT to use it, but the guidance is strong enough for appropriate 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?

Beyond annotations, the description adds key behavioral details: ownership enforcement, deactivation (not deletion), and the fact that historical events remain available via 'recent_alerts'. This provides significant context about the tool's side effects.

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 consists of two concise sentences with no redundancy. Every sentence adds value: first states the action and constraint, second explains the data lifecycle impact.

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

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

For a simple one-parameter tool, the description covers the core functionality, ownership rule, and data behavior. It does not mention return values, but that is acceptable given the tool's simplicity and 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?

The schema already provides a complete description for the single parameter (id). The description notes that the id is returned by 'subscribe', which adds mild context but does not contribute new structural 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 action ('Cancel a subscription by id') and specifies the resource (subscription). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by explaining ownership enforcement and the deactivation behavior.

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

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

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use the tool. It does not explicitly state when not to use or list alternatives, but the context from sibling names 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 context: sources (SEC EDGAR + XBRL), output (verdict with structured form, actual value with citation, percent delta), and efficiency (replacing 4–6 calls). 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 well-structured with examples and a note about replacing sequential calls. It is concise but slightly dense; could be broken into smaller sentences or bullet points. Front-loads key purpose with natural-language examples.

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 one parameter, no output schema, and rich annotations, the description provides necessary context: scope, sources, output format, and efficiency. It is sufficient for an agent to understand when and how to use the tool.

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

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

Schema has 100% coverage for the single 'claim' parameter with a clear description. The description reinforces this with examples but does not add further constraints or meanings beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources, specifically company-financial claims for public US companies via SEC EDGAR + XBRL. It provides example queries and distinguishes itself by replacing 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also scopes usage to company-financial claims. While it does not explicitly exclude non-financial claims or mention alternatives, the specificity implies other tools for broader questions.

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