Fcc Regulations

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 further transparency by detailing the return structure (score, confidence, signals, raw_response) and cost implications (free for Workers AI, BYO key for Anthropic with direct billing).

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

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

The description is concise—four sentences that front-load the primary purpose. Every sentence adds essential information without redundancy or fluff.

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

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

Despite lacking an output schema, the description fully explains the return format (per-model metrics + combined view). Given the tool has 4 parameters with full schema documentation, the description compensates adequately, making it complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model, the condition for using _apiKey, and the purpose of the context parameter. This provides semantic enrichment.

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 probes LLMs for brand/product visibility and returns a score (0-100) per model. The specific verb 'probe' and resource 'LLMs' with scoring distinguishes it from sibling tools like ask_pipeworx or deep_research.

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

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

The description explains key usage scenarios: AI-marketing audits, pre-launch checks, competitive monitoring. It also clarifies model selection (default Workers AI, optional Anthropic with BYO key). However, it does not explicitly state when not to use or mention alternative 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 declare readOnlyHint and idempotentHint, indicating safe, repeatable querying. The description adds context about the structured answer format and citation URIs, and confirms it is a single fast call. No contradictions or missing behavioral disclosures.

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

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

The description is dense but well-organized. It starts with the most critical instruction (prefer over web search), then lists domains, explains the routing mechanism, provides usage examples, and differentiates from sibling tools. Each sentence contributes meaning, though slightly 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 (orchestrating 5,564 tools), the description thoroughly covers purpose, usage, behavior, and limitations. Annotations are present, schema is fully covered, and the description explains what the tool returns and when to use alternatives. 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%, so the description doesn't need to detail parameters. However, it adds value by explaining that the single question parameter accepts aliases (q, text, etc.) and provides natural language examples. This enriches the semantic understanding beyond the schema.

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

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

The description clearly states the tool routes factual questions to appropriate sources and returns structured answers with citations. It uses specific verbs ('routes', 'fills arguments', 'returns') and distinguishes from siblings like ask_pipeworx_grounded and deep_research, as well as from web search.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH' for factual questions, with concrete examples. It advises when to step up to other tools (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions) and notes it works on every tier as a default entry point.

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 the experimental nature, candidate routing improvements, current inactivity, and that it is a full working router. Adds context beyond annotations about fallback behavior and live testing, all consistent with the provided annotations.

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

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

Three sentences, each dense with information. Front-loaded with the core identity (beta, identical), then usage guidance, then behavioral note. 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 the tool is a beta variant of a well-known sibling, the description covers all necessary context: what beta means, why it exists, current status, how to use it, and what the response shape is (same as stable). No gaps for an AI agent to misuse.

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 6 parameters, so the schema already documents the parameter details thoroughly. The description adds no new parameter semantics beyond stating they are identical to ask_pipeworx, which is marginally helpful but not essential. 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?

Description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with experimental routing improvements. It distinguishes from siblings by stating it's the experimental edge version, separating it from the stable ask_pipeworx and ask_pipeworx_grounded.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. Also advises that currently no candidate is active so it matches ask_pipeworx exactly, providing clear when-to-use guidance.

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

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

Annotations already mark readOnlyHint, openWorldHint, and idempotentHint, so the tool is clearly a safe, non-destructive query. The description adds significant context: it explains the evasion mechanism (extracts only from tool result), defines success/refusal response structures, and enumerates refusal categories. The extra LLM call cost is disclosed. A small gap—doesn't explicitly confirm it never invents beyond annotations—but overall well above the minimal bar.

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 the key value proposition ('hallucination-resistant'). Every sentence earns its place except the list of aliases, which is already in the schema. Could trim the alias enumeration, but overall efficient and well-organized.

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

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

Despite lacking an output schema, the description explicitly defines both success and refusal response shapes, covering all important fields. The tool is simple (one required param, no enums, no nesting), and the description fully covers behavior, constraints, and trade-offs without needing additional 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 all parameters being aliases for the natural language question. The description adds the critical behavioral constraint ('answer using ONLY what the tool result contains') that shapes how the question parameter should be used—precise and fact-seeking. This goes beyond the schema's simple type/description.

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

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

The description provides a specific verb-resource combination ('hallucination-resistant answer mode'), clearly distinguishes from ask_pipeworx by highlighting the grounded extraction behavior, and lists explicit use cases (financial verdicts, legal claims, medical lookups).

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

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

Explicitly states when to use (high-stakes reads needing citation or action) and when not to prefer the sibling ask_pipeworx (casual lookups), and contrasts the trade-off (extra LLM call). No ambiguity about 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: fan-out process, response shapes, resolver contract, parent event extraction, news fallbacks, safety short-circuits, spread warnings, resolution-rule risk. 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?

Very long and detailed, covering many edge cases and internal mechanisms. Not concise; reads more like a manual than a tool description. Better structure could front-load core info and have details separate.

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 fully explains what to expect: evidence packet, analysis, market match confidence, parent event, news fields, safety behaviors. Covers all relevant aspects for an AI agent to use 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 covers 100% of parameters with descriptions. The overall description adds context to depth and include_raw but does not significantly extend meaning beyond the schema's parameter 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?

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Specifies input types (slug, URL, question text). Does not explicitly distinguish from siblings like polymarket_arbitrage or polymarket_edges, but the scope is distinct enough.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Does not mention when not to use or alternatives, leaving some ambiguity.

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

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

Annotations already indicate non-destructive, read-only, idempotent behavior. The description adds valuable context: parallel call, off-calendar fiscal year handling, sorted results by primary metric, and citation URIs.

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 compact but packs essential information. Slightly dense but every sentence adds value. Could be structured with explicit sections, but it's efficient.

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

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

Given the complexity of two entity types and multiple metrics, the description covers input, output order, data sources, and special handling (off-calendar fiscal years). No output schema but return format is implied.

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

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

Schema coverage is 100%. The description explains the enum values ('company' vs 'drug') with concrete examples (tickers/CIKs for company, names for drug). It also specifies what data each type pulls.

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

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

The description clearly states the tool provides side-by-side comparison of 2-5 companies or drugs, with specific verbs like 'compare' and 'rank'. It distinguishes from sibling tools by emphasizing it replaces sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. Clearly separates usage for company vs drug types with specific data sources.

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

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

The description adds significant behavioral context beyond annotations: details the decomposition process, parallel routing to 5,564 tools, output format (evidence, confidence, source, citations, gaps), limitation of not being open-web search, second-hop iteration for gaps, semantic excerpting, and expected time (15-90s). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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, running multiple paragraphs with specific numbers (1462, 5,564) and fine-grained details about citation_uri, hop fields, and excerpting. While well-structured and front-loaded with the account requirement, it could be more concise without losing essential information.

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

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

No output schema exists, so the description must fully explain the return value. It does: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers contradictions[], hop field, and citation_uri. The description is complete for a complex research tool.

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

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

Schema coverage is 100% (baseline 3). The description adds meaningful context: explains the depth levels (quick, standard, thorough) with their specific behaviors (gap recovery, contradictions, iterative hops), and clarifies that the question parameter accepts natural language and broad/multi-part questions. This goes beyond the enum descriptions in 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: 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call'. It distinguishes from siblings like ask_pipeworx for single lookups and breaking news, and provides specific examples of when to use (e.g., 'compare X and Y's regulatory + financial exposure').

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 gives when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also mentions account requirement and alternative for non-signed-in users.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by stating that results come with 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' 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 front-loaded with purpose, then lists domains and return value. It is reasonably concise, though the list of domains could be trimmed slightly. 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?

No output schema exists, but the description adequately explains the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Given the tool's simplicity, this is sufficient for an agent to understand what it will receive.

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

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

Schema description coverage is 100%, so the schema already explains parameters. The description's list of example domains (SEC filings, financials, etc.) adds contextual meaning for the query parameter, but most information is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists concrete domains (SEC filings, financials, FDA drugs, etc.) and explains the return value (top-N tools with schemas). This distinguishes it from sibling tools like deep_research or validate_claim, which are specific research tools, not discovery 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 says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use and when-not-to-use guidance. It also describes the output format, helping the agent decide when to invoke.

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 it as readOnly, idempotent, etc. The description adds valuable context: parallel invocation, soft-fail for patents, and multiple source handling. No contradictions.

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

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

Well-structured and front-loaded with examples, but somewhat verbose with full list of return fields. Could be slightly more concise while retaining clarity.

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

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

No output schema exists, so description must cover returns. It does so adequately (CIK, filings, fundamentals, patents, news, LEI). Missing details on pagination or error handling, but sufficient for a holistic profile 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%, but description adds clear usage: only 'company' type, ticker or zero-padded CIK, names not supported. This goes beyond the schema's enum and type descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources and return types, distinguishing it from siblings like resolve_entity.

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 preference over chaining lookups: 'ALWAYS PREFER over chaining single-pack...' and provides alternatives: 'use resolve_entity first if you only have a name.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context on input forgiveness, keyless operation, and coverage of specific parts, enriching the behavioral understanding 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 thorough but well-organized, starting with core purpose, then examples, then coverage details. Every sentence adds value, though it could be slightly more concise.

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

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

Given only one parameter, 100% schema coverage, no output schema, and sufficient annotations, the description is complete: it covers input variations, common names, part retrieval behavior, and sibling distinctions.

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

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

Schema description covers the citation parameter fully (100% coverage). The tool description adds numerous examples and explains that passing a whole part returns a section list, and that common names work, providing significant added 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 it retrieves the full text of an FCC regulation by citation, with specific examples and coverage of Title 47. It distinguishes from sibling tools by noting that separate packs handle filings and licensing data.

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

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

Explicitly provides when to use (to get FCC rule text) and when not to use (for filings/licensing data, which are handled by other tools). Also lists common citation formats and accepted common names.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds return format details (citation, heading, excerpt, source URL) and mentions 'Keyless' (no API key). It is consistent with annotations and adds useful context beyond them.

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

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

The description is long but well-structured: purpose first, then examples, then differentiation. Every sentence contributes information. Minor verbosity but acceptable for the detail needed.

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

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

Despite no output schema, the description specifies return fields (citation, heading, excerpt, source URL). It covers which data is searched (rules) and what is not (filings). For a search tool, this is complete and actionable.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value through concrete query examples and states the default limit (10). This supports correct invocation.

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 keyword search across FCC regulations (47 CFR). It provides specific examples and distinguishes from sibling tools like fcc_regulation and fcc packs.

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 extensive example queries, topics, and explicit differentiation from other tools: 'Searches the FCC RULES text; the separate fcc and data-fcc packs search FCC filings and licensing data.' This clearly tells the agent when to use this tool.

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

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

Annotations already indicate destructiveHint=true; description adds context about clearing sensitive data and the key-based deletion. No contradiction, but no further behavioral details beyond annotations.

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

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

Two sentences, no wasted words, front-loaded with core action. Very concise 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 a single required parameter, no output schema, and clear annotations, the description fully covers purpose, usage, and pairing. No gaps.

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

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

Schema coverage is 100% and describes the 'key' parameter well. Description adds 'by key' which is already implied, providing no additional semantic depth beyond the schema.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. It distinguishes from siblings by mentioning '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 lists three use cases (stale context, task done, clear sensitive data) and advises pairing. Lacks explicit when-not-to-use guidance but covers main scenarios.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detail on the process: fetching the page, extracting title/description/key links, and emitting standard format. 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?

The description is a single paragraph that covers purpose, process, and use cases efficiently. It is concise but could be more structured for scanning. No redundant sentences.

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

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

Given 2 parameters, no output schema, and annotations, the description explains the output format and use cases well. It is sufficiently complete for a simple tool.

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

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

Schema description coverage is 100% (both url and max_links described). The description adds no extra meaning for parameters beyond what the schema provides, so baseline 3 applies.

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

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

The description uses the specific verb 'generate' and resource 'llms.txt file', clearly stating the tool's function. It distinguishes from sibling tools like scan_competitor_ai_presence and ai_visibility_check by focusing on file generation rather than 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?

The description provides concrete use cases (client indexing, personal project drafting, competitor auditing) but does not explicitly state when to avoid this tool or differentiate from similar siblings. Use cases are clear but exclusion criteria are absent.

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 signal readOnly and idempotent. Description adds return field names and default active-only behavior, complementing annotations without contradiction.

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

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

Two sentences: first defines purpose and output, second gives usage guidance. No unnecessary words, front-loaded with essential info.

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 lists return fields (id, type, etc.) and explains usage context. Tool is simple with one optional param, so description is complete.

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

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

Schema coverage is 100%, so baseline is 3. Description does not elaborate on the include_inactive parameter beyond what schema provides, so no added 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?

Clearly states verb 'List' and resource 'subscriptions', specifies it returns caller's active ones, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises to use before adding more subscriptions or to find an id to cancel, providing practical context. Lacks explicit when-not-to, but implied by sibling tool existence.

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

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

With all annotation hints set to false, the description carries the full burden of behavioral disclosure. It reveals a non-synchronous claim-token flow: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed.' It also discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), and the team's daily digest review. These are meaningful behavioral traits beyond the schema and annotations.

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

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

The description is a single dense paragraph, but every sentence serves a purpose: usage triggers, scope boundaries, claim-token mechanics, rate limits, and quota. It's front-loaded with the core purpose and then expands on nuances. Slightly longer than ideal, but the added length is justified by the tool's multi-mode behavior (filing vs. checking) and the need to prevent cross-server misuse.

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

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

There is no output schema, so the description must explain return behavior. It does explain the claim_token return for unauthenticated submissions and the subsequent retrieval flow. However, it doesn't specify what happens when an account is present or whether the immediate response includes any status field beyond the token. Given the tool's complexity (4 params, nested context, enums) and lack of output schema, the description is nearly complete but could be a bit more explicit about the immediate response shape for authenticated users.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantic guidance beyond the schema: it explains how the claim_token parameter is used for follow-up reads ('pass the `pwfb_…` token that filing returned, with no other arguments'), and it advises on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This adds practical parameter-level meaning not present in 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 specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates distinct feedback categories (bug, feature/data_gap, praise) and clearly distinguishes this from sibling tools like ask_pipeworx or discover_tools. The scope is unambiguous—it's a feedback channel for Pipeworx tools, not a general query or research 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 provides explicit when-to-use triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a clear exclusion and alternative: 'ONLY for tools served by this Pipeworx connection—if the tool came from a different MCP server... file it with that server instead.' This goes beyond basic context to offer concrete decision rules.

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 context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h depending on window). 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?

Three sentences with clear structure: first sentence states output, second lists use cases with bullet points, third describes technical characteristics. No superfluous 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?

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, behavior, and caching. No gaps given the tool's complexity.

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

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

Schema description coverage is 100%, and the parameter 'window' is clearly described with enum values. The tool's description reinforces the meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', adding semantic value beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window' with specific temporal options. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on aggregate trending data.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming popular tools, and aligning use case with agent needs. The description also explains when to use different window durations ('Shorter windows surface what's hot right now; longer windows show steady-state demand').

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 readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: how monotonicity and partition checks work, semantic anchor (Jaccard similarity), partition filter logic, and fill check against live CLOB depth with warnings about unrealizable edges. 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 well-structured with clear sections for each mode and sub-algorithms, but it is lengthy. Every sentence contributes value, though some details (like the threshold value '3pp') could be slightly condensed. Overall 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?

Despite lacking an output schema, the description thoroughly documents the response structure: including opportunities array with fields (gap_pp, suggested_trade, reasoning, monotonicity context) and mode-specific fields (partition_check, fill_check). It also covers edge cases (e.g., realizable edge ≤ 0) and cross-references polymarket_fill_risk.

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?

Despite 100% schema description coverage, the description adds significant semantic value beyond the schema: it explains that `event` accepts slugs or URLs, that `topic` is a seed question, and details the algorithmic behavior of each parameter, including the partition_check and fill_check logic.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (trending scan, event, topic) and implicitly differentiates from siblings like polymarket_fill_risk and polymarket_edges by focusing on arbitrage detection.

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: when to call with no args (trending scan), when to use `event` (specific market), and when to use `topic` (cross-event scan). It also instructs to use polymarket_fill_risk for custom sizing, clarifying when not to use this tool.

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

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

The description adds extensive transparency beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It details the three response segments with model families, the logic for structural arbitrage (partition_overround, bias correction, placeholder filters), concentrated longshot conditions, and diagnostics for empty segments. It also explains caching behavior and the meaning of edge_pp_net, kelly_fraction, and 24h-move warnings. 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 dense and verbose, running several paragraphs with inline bullets. While it is well-organized with clear section headings (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), it could be more concise. Every sentence adds value, but the length is excessive for a tool description; a bulleted list would improve 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?

For a complex tool with 9 parameters, no output schema, and multiple segments, the description is highly complete. It explains the output structure (by_segment, fed_candidates, diagnostics), edge cases (e.g., Fed bets exclusion, partition arbs with zero parent Kelly), and caching. It also details how parameters like min_partition_leg_kelly interact. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor context for parameters like 'window' (volume window) and 'category_filter' (restrict segments), but the schema already describes each parameter adequately. The tool-level description's 'Tradeable-edge knobs' section reinforces min_liquidity and max_spread_pp but doesn't add significant new semantics beyond the schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' providing a specific verb (scan/return), resource (Polymarket markets), and output (opportunities). It also distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by describing three distinct segments (model_driven, structural_arbitrage, concentrated_longshot).

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' giving clear usage context. It notes that Fed bets are excluded from ranking and why, and mentions caching. However, it does not explicitly state when not to use this tool vs alternatives like polymarket_arbitrage or polymarket_edge_tracker, though the sibling tool names and context imply 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 indicate read-only, idempotent, and non-destructive. The description adds significant behavioral context: snapshot dependency, data gaps meaning no scanning, decay computed from daily closes not intraday, and interpretation of signed values. 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 lengthy but efficient; every sentence adds value. It is front-loaded with the core question, then details response structure, and ends with limitations. Slightly verbose but justified given complexity.

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

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

Despite no output schema, the description thoroughly explains the response arrays (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day), and edge cases (gaps, lifespan). Covers all relevant context for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description provides additional context: 'default 14, max 30' for days, and 'snapshot family' for window with default '1wk'. This reinforces and adds clarity beyond the schema.

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

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

The description uses specific verbs ('track', 'telemetry') and clearly states the resource ('edge persistence and decay'). It distinguishes from siblings like polymarket_edges by focusing on historical trend analysis, not just current edges.

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 the tool's purpose with a concrete question ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. old edges. It includes limits (60-day TTL, snapshot gaps) but does not explicitly mention when not to use or alternatives.

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

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

Discloses key behavioral traits beyond annotations, such as walking the order-book ladder, returning verdicts (clean/degraded/cannot_fill), and warning about forced directional risk and partial fills. All consistent with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false.

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 modes, and front-loaded with purpose. However, it is relatively dense and could benefit from minor formatting improvements (e.g., bullet points) for 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?

Given no output schema, the description fully explains return values for both modes, including metrics like vwap_fill_price, slippage, capture_ratio, and thin_legs. It covers all necessary context for safe usage, such as requiring one of market or event.

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 significant meaning beyond the schema, explaining the difference between single-market and basket modes, default behaviors for side and size_usd, and constraints (e.g., clamp 10–1,000,000). 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?

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live order-book depth, and distinguishes between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a risk check before executing trades.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' with a clear rationale about theoretical overround not being capturable and partial fills converting arbs into directional positions.

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. The description adds rich behavioral context: explains compatibility_warning conditions (matched_pairs:0 scenarios), temporal_alignment field, and skipped_cross_type/subtype counters. 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 verbose but well-structured. It front-loads the main purpose and uses clear sections for modes, response, and safety fields. Some redundancy exists (e.g., explaining compatibility_warning in detail twice). Could be trimmed slightly, but still effective.

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

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

No output schema, but the description explains the response structure: 'leg-by-leg prices (raw probability 0-1) plus matched spread[]...' and details safety fields. Covers edge cases (temporal misalignment, non-equivalent bet shapes). Given the tool's complexity, the description provides comprehensive context.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining the topic values (list of 10 shortcuts) and how explicit tickers override topic mapping. Also includes examples in the schema. The description enriches understanding beyond raw schema definitions.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute spread), resource (two prediction market venues), and scope. It distinguishes from sibling tools by focusing on cross-venue analysis, unlike single-venue tools like polymarket_arbitrage.

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

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

Provides explicit guidance on when to use the tool (two modes: topic shortcuts and explicit tickers) and when not to (when compatibility_warning fires due to non-equivalent bet shapes or temporal misalignment). Warns that pre-mapped topics often return warnings, setting realistic expectations. No alternatives mentioned but usage conditions are 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, idempotentHint, destructiveHint. Description adds scoping to user identifier and behavior when key omitted, providing value beyond metadata.

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

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

Two sentences, no redundancy, front-loaded with main action. Every sentence serves a purpose.

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

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

No output schema; return format not described. Missing error handling (e.g., missing key). Adequate for a simple tool but could be more complete.

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

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

Schema covers the single parameter fully (100% coverage). Description reinforces omitting key to list, but adds no new semantics 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 the tool retrieves a saved value or lists all keys, with specific verb+resource and distinction between the two modes. It differentiates 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?

Provides concrete examples (ticker, address, research notes) and mentions pairing with remember and forget. Lacks explicit when-not-to-use but context is clear from 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 safe, read-only, idempotent behavior. The description adds valuable context: what fields are returned, how mark_read and unread_only flags work, and that the feed is also accessible via HTTP. 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 four sentences long, each adding distinct value. It is front-loaded with the core action, then details returned fields, parameters, and usage notes. 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, the description adequately describes return values. All five optional parameters are explained. Annotations cover safety. The tool is fully documented for an AI agent to understand and use correctly.

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

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

Schema coverage is 100% with descriptions. The description adds extra behavioral context for mark_read and explains filter options (type, since), going beyond the schema. For example, it clarifies that setting mark_read:true causes subsequent calls to show only newer events.

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 pulls fired events from the subscription feed, specifies what each alert carries (source, citation_uri, raw payload), and distinguishes itself by mentioning an alternative access method (GET registry.pipeworx.io/alerts.json). It is specific and informative.

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 notes that polls work fine and provides the alternative endpoint, but does not explicitly state when to use this tool versus siblings. It implies usage for retrieving recent alerts and suggests filtering options, which is clear enough for most scenarios.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description details external API calls, fallback logic, and API status (USPTO/PatentsView sunset). This adds critical behavioral context the agent needs.

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 compact, front-loaded with natural language examples, and efficiently covers purpose, sources, parameters, and output. Every sentence provides necessary information without redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, date parsing), the description fully specifies behavior, input, and output. It also addresses edge cases (USPTO soft-failure) and distinguishes from sibling tools.

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

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

Schema already covers all parameters (100% coverage). The description adds value by explaining the 'since' format in detail (ISO date vs relative shorthand) and providing a typical usage tip ('30d' or '1m').

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

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

The description clearly states the tool provides a 'change feed for a company' using multiple sources (SEC, GDELT, GNews, USPTO). It distinguishes itself from the sibling tool 'entity_profile' which is for static profiles, thereby setting clear boundaries.

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 guides when to use this tool for 'what's new' queries and when to use 'entity_profile' instead. It also describes the fallback mechanism (GDELT preferred, GNews on rate limit) and explains input format options.

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

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

Beyond annotations, the description discloses scoping by identifier, persistence differences (authenticated vs anonymous), and retention duration (24 hours). 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?

Three well-structured sentences: first captures purpose, second explains usage triggers and paired tools, third adds behavioral details. 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?

Even without output schema, the description fully covers behavior (idempotent, scoped, persistent/transient) and usage context, making it self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by framing parameters as key-value pair and naming conventions (e.g., 'subject_property'), which aids correct 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?

The description states 'Save data the agent will need to reuse later', which is a specific verb+resource. It explicitly distinguishes from siblings such as 'recall' and 'forget', clarifying its unique role.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward', with examples like resolved ticker or user preference. Also directs to paired tools: 'Pair with recall to retrieve later, forget to delete.'

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses significant behavioral details: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers, source attribution for each identifier, and internal cascading of lookups. This adds substantial context 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 quite verbose, with extensive parenthetical explanations and multiple examples. While well-structured with SUPPORTED TYPES, it could be tightened without losing key information. The purpose is front-loaded, but the length may tax agent attention.

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

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

With no output schema, the description thoroughly covers what the tool returns for each type (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), including fallback behavior and coverage limitations. It is complete for a tool of this complexity and provides sufficient guidance for correct 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% and both parameters are described. The description enriches this with concrete examples (ticker, CIK, ISIN, brand/generic names), clarifies the ISIN-to-LEI mapping, and explains how each type resolves to specific identifiers. This goes beyond the basic 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides numerous example queries and distinguishes itself from siblings by positioning it as the go-to tool for name-to-ID resolution, with explicit supported types.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool cascades through multiple lookups, replacing 2-3 manual steps. However, it does not explicitly mention when not to use it or name alternative tools for other purposes, such as entity_profile.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds that the tool probes each entity with ai_visibility_check, ranks by score, and returns fields like score, confidence, signal density. It also mentions optional Anthropic API key, adding 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?

Two concise sentences with a practical example. Every word adds value, front-loaded with action and outcome.

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 what the tool returns (ranked list with score, confidence, signal density per entity). All four parameters are accounted for via schema, and the description fills in behavioral and contextual 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 the description need only add nuance. It explains that the first entity is treated as the 'subject' for narrative, and that context disambiguates common names—both helpful details not in schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a query example. It implies when to use (multi-entity comparison) but does not explicitly state when not to or name alternatives, though the sibling list contextualizes this.

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 idempotency and read-only behavior. The description adds critical behavioral nuance: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 front-loaded with the main purpose and then provides detail in a logical order. While somewhat long, every sentence carries useful information. Could be slightly more concise but 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?

Despite no output schema, the description lists all return fields (summary block, advisories, links, alternatives) and explains partial failure behavior. This fully prepares the agent for what to expect from 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 coverage is 100%, but the description adds value by noting that scoped packages (e.g., '@types/node') are accepted, which is not in the schema. The default version behavior is also reinforced. The added context justifies a score above baseline.

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

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

The description clearly states the tool's purpose: a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs ('scan', 'check') and resources ('npm package'), and distinguishes from sibling tools by specifying the ecosystem and scope.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and provides exclusion guidance: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly tells when and when not to use the 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 embedding model (BGE-base-en), similarity method (cosine), chunking (500-char overlapping windows), character limit (200K chars with truncation flag), and output details (offsets, similarity scores). Annotations already indicate safe reads, and description adds rich behavioral context beyond them.

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

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

Every sentence earns its place: front-loaded purpose, usage guidance, technical details, and pairing with sibling. No filler, efficiently packed with 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?

Covers all essential aspects: purpose, when to use, how it works (embeddings, chunking), constraints, output features, and relationship with sibling. Even without output schema, the description sufficiently describes what the agent can expect.

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

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

Schema coverage is 100%, but description adds meaningful context: 'Pass the text you already pulled' for text, natural-language query with examples for query, and limit range and default. This helps an agent understand usage 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 does semantic search inside a fetched record, using specific verbs ('search within') and resources ('a fetched record'). It distinguishes from siblings like ask_pipeworx_grounded by noting the use case: when the record is too large for the prompt.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Does not explicitly state when not to use, but context is clear.

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

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

The description contradicts the idempotentHint annotation: it states that each call returns a new subscription ID, implying non-idempotent behavior, while the annotation suggests idempotency. Other behaviors (caps, verification) are well explained.

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

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

The description is front-loaded with the core purpose, followed by structured details on types and delivery. Every sentence adds necessary information without redundancy.

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

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

Given the tool's complexity and the absence of an output schema, the description covers all essential aspects: purpose, prerequisites, supported types, parameter details, delivery channels with constraints, and return value.

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

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

The description significantly expands on the schema by providing usage examples, constraints (like phone verification, daily caps), and detailed explanations for each parameter, especially for delivery channels.

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 creates a subscription, returns an ID, and lists supported types and delivery channels. It distinguishes itself from sibling tools like list_subscriptions 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?

The description implicitly indicates when to use it (to create a subscription) but does not explicitly contrast with alternative tools like list_subscriptions or unsubscribe, though the sibling list implies these alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent. The description adds behavioral context: it returns example questions categorized by topic, and can be called with no arguments or a topic focus. This goes beyond annotations by detailing output structure and invocation flexibility.

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 information-dense but not overly long. It front-loads the core purpose and usage, then details the output categories. Every sentence serves a purpose, though some redundancy (e.g., listing categories in both the description and schema) could be trimmed slightly.

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 what the tool returns (categorized example questions with tool+argument shapes) and when to use it. It is complete for an onboarding tool with simple input.

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

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

Schema coverage is 100%, baseline 3. The description adds examples for topic values (e.g., 'finance', 'pharma') and explains the effect of omitting vs providing a topic, adding meaningful context beyond the schema's description.

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

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

The description clearly states that this tool is the onboarding entry point, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by positioning itself as the first tool to use.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides example queries like 'what can I ask Pipeworx?' and 'getting started'.

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

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

The description adds significant value beyond annotations: it clarifies that the row is deactivated (not deleted) and historical events remain via recent_alerts. Annotations only indicate non-destructiveness and idempotency; the description explains the actual side effect and ownership enforcement.

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

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

The description is two sentences, front-loaded with the action and constraint, followed by a clear explanation of the side effect. Every sentence is informative 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?

The description covers purpose, constraint, and behavioral side effects for this simple one-parameter mutation tool. It does not describe the return value or error conditions, but given the tool's simplicity and the presence of annotations, it is reasonably complete.

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

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

Schema coverage is 100% and the parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.' The description adds context by mentioning 'by id' and ownership enforcement, which helps understand how the parameter is used, but does not provide additional syntax details.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription', and specifies the action is by id. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and 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 provides explicit ownership constraint: 'you can only cancel your own subscriptions.' It implies when to use this tool (to cancel) and mentions that deactivation keeps historical events available, but does not explicitly state when not to use or name alternatives.

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

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

Annotations already declare readOnly, openWorld, and idempotent behaviors, and the description adds substantial context beyond them: the meaning of could_not_verify (a non-result with verification_error, not evidence), the distinction between unsupported and refuted, the structured SEC EDGAR fast path versus grounded fallback, and the verdict vocabulary. This gives callers crucial behavioral understanding 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 long but densely packed with relevant examples, routing logic, return details, and error semantics. It is front-loaded with natural-language trigger phrases and each sentence adds value; however, it could be slightly more concise by moving the 'Replaces 4–6 sequential calls' detail to the end. Overall, the length is justified given the tool's complexity.

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

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

There is no output schema, so the description must explain return values—and it does with a full list of verdicts, the actual value with a pipeworx:// citation, and reasoning. The description also covers error semantics (could_not_verify with verification_error), fallback behavior, and parameter overrides, making it complete for safe and correct 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 description coverage is 100%, with both claim and tolerance_pct fully described in the schema. The description adds some context (e.g., tolerance override for hallucination detection, exact percent-delta math), but it does not substantially enhance the parameter semantics beyond what the schema already provides, so a baseline 3 is appropriate.

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

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

The description uses specific action phrases like 'fact check' and 'verify the claim that…' and clearly identifies the resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by explicitly explaining that it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear use context. It also differentiates between company-financial claims and other factual claims, describing the fallback routing, but it does not explicitly state when NOT to use this tool versus alternatives like deep_research or ask_pipeworx_grounded.

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