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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond those hints: it fills arguments, returns structured answers with stable citation URIs, supports citations and provenance, uses sensible defaults with 'actually' overrides, and may return stale answers if a fact is already stored as workspace memory. It also discloses an auth requirement caveat.

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 most important guidance and generally well organized, but it is overly long and contains a repeated sentence about routing across 5,798 tools. Some phrases are vague and unfinished, such as 'If you have no auth creds? then is there a budget?' and 'maybe use pipeworx support,' which reduce clarity and polish.

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, multi-source tool with no output schema, the description provides a strong amount of context: it explains the answer format, citation behavior, routing strategy, alternatives, caveats, and auth limitations. It is almost complete, but the garbled budget/auth sentence and vague platform-support note leave minor gaps in an otherwise thorough definition.

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

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

Schema description coverage is 100%, so the schema already documents all six properties and their alias relationships. The description adds extra value by explaining that ask_pipeworx fills in sensible defaults, that users can override with 'actually' + clarification, and by giving concrete example questions that clarify what type of natural-language input is expected.

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 ask_pipeworx routes questions to one of 5,798 tools across 1,517 verified sources and returns structured answers with stable pipeworx:// citation URIs. It also explicitly frames the tool as the preferred default over web search for factual/current/historical data, making its purpose and scope unmistakable.

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

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

The description gives extensive when-to-use and when-not-to-use guidance, explicitly naming alternatives such as ask_pipeworx_grounded, ask_pipeworx_beta, deep_research, bet_research, recall, search_within, general chat models, and compute_tool. It also states 'START HERE for most questions' and 'PREFER OVER WEB SEARCH', making routing decisions highly actionable.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial context beyond this: it is a beta, currently has no active candidate, currently matches ask_pipeworx exactly, and exists to test routing improvements. The 'falls back to nothing' line is particularly helpful for setting agent expectations.

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-structured, front-loading the beta relationship and then clarifying current behavior. The exact tool count and retirement date are extra details but they reinforce the transparency. It is slightly longer than necessary, but every sentence contributes useful context.

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

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

For a read-only, idempotent router, the description covers what the tool does, when to use it, how it differs from its stable counterpart, its current state, and what not to expect. The absence of an output schema is mitigated by stating that the response shape is identical to ask_pipeworx, giving agents a complete behavioral model.

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 every parameter documented as an alias for 'question'. The description adds only a generic statement that arguments match ask_pipeworx, which is redundant with the schema for this tool. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by framing itself as the experimental routing edge. The verb 'ask' and the explicit relationship to ask_pipeworx make the purpose unambiguous.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It also clarifies that it is a full working router with no fallback. It does not discuss exclusions versus ask_pipeworx_grounded, but the primary use case is clearly stated.

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

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

The description goes far beyond annotations: it details the exact success return shape, all refusal reasons and their meaning, and explains it only uses tool-result content. Discloses the extra LLM call cost and the refusal behavior when data doesn't directly answer. No contradiction with readOnlyHint or 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 dense but every clause adds value: purpose, behavior, return contract, usage guidance, and cost comparison. It is structured with front-loaded intent and explicit refusal format. No filler or repetition.

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

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

Given the tool's high-stakes nature, the description is complete: it covers output shape, refusal cases, when to prefer alternatives, and cost consequences. The input schema covers parameters, and the description covers everything an agent needs to make a correct invocation decision.

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 only required parameter 'question' is already documented with aliases. The description does not add meaning about parameter formatting or semantics beyond the schema, and that's acceptable given the baseline.

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

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

The description states a specific purpose: a 'hallucination-resistant answer mode for high-stakes reads' that routes through the same pipeline as ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from siblings by its grounded/exact-answer behavior and explicit refusal mechanism.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' It also names the alternative (ask_pipeworx) and tells when NOT to use this tool ('prefer ask_pipeworx for casual lookups'), plus a cost tradeoff (one extra LLM call).

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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds essential behavioral context: account and paid-plan requirements, expected latency, gap recovery behavior, contradiction scanning, citation_uri fetchability, semantic excerpting, and the guarantee that gaps are never invented. This is far more than the annotations alone provide.

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

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

The description is long but every sentence earns its place: account requirements, alternatives, tool mechanics, output format, latency, and behavioral guarantees all matter for correct invocation. It is front-loaded with the most decision-critical constraint (account required, use ask_pipeworx otherwise) and reads as dense but structured, not padded.

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 is remarkably complete. It covers input, decomposition behavior, output contents, citations, gaps, contradictions, timing, and account constraints. An agent has enough information to decide whether to call it and what to expect when it returns.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what each depth level actually does (quick single-hop, standard gap recovery, thorough iterative hop), which depth requires a paid plan, and that the question parameter accepts broad multi-part natural language. This justifies a score above baseline, though the schema already documents the core parameter fields well.

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

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

The description clearly states that deep_research performs grounded multi-source research across Pipeworx's structured data sources, decomposes questions into facets, and returns a findings packet. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell exactly what this tool does and what it is not.

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

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

The description gives explicit when-to-use guidance: use it for broad/multi-part questions over structured data. It also names alternatives and conditions—use ask_pipeworx for single lookups, breaking/colloquial current news, or when not signed in—so the agent has clear routing 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 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?

Beyond the readOnly/idempotent annotations, the description discloses fan-out across multiple upstream APIs, a GDELT→GNews fallback, USPTO soft-fail behavior, and the semantics of empty sections ('an empty section is a real "no data", not a bug'). This gives the agent a realistic model of partial and failure-prone data.

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?

Although long, the description is front-loaded with examples and the core 'full cross-source profile in ONE parallel call' statement, and every subsequent clause carries information about sources, return fields, failure semantics, or accepted inputs. The length is justified by the absence of an output schema.

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 supplies a de facto return contract: it enumerates each returned section (cik, recent_filings, fundamentals, patents, etc.) and explains the meaning of sources_used/sources_failed. It also covers name resolution, ticker/CIK forms, private-company behavior, and data-specific caveats, so an agent can invoke and interpret the result correctly.

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

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

Schema coverage is 100%, and the description largely restates the schema text for `type` and `value` (same examples AAPL/0000320193/Moderna, same interchangeability note). It adds the global scope of 'US public company' but that is tool-level context, not new parameter-level semantics. 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 opens with concrete user query patterns and an explicit statement: 'full cross-source profile of a US public company in ONE parallel call.' This names the verb (profile), resource (US public company), and scope (cross-source), and clearly separates it from single-pack SEC/XBRL/news 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?

It explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear decision rule. It also documents edge cases (private companies return resolved:false, no data is reported via sources_failed), which tells an agent what to expect and when not to treat output as an error.

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?

Exceptionally detailed on behavior beyond annotations: identical matcher across modes, safety fields that can be non-empty even when pairs are returned, gross vs net fee disclosure, skipped counters, unknown-leg handling, and the meaning of null temporal_alignment. All consistent with readOnly/idempotent/non-destructive 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?

Long, but explicitly labeled with sections like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, which makes it navigable. The purpose is front-loaded and the extensive edge-case detail is justified given the tool's complexity and lack of an output schema.

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

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

With no output schema, the description fully carries the burden of describing return semantics: top_spreads_pp, compatibility_codes, per-pair flags, temporal_alignment, fees_note, skipped counters, and low_confidence_pairs. Nothing essential for correct invocation or interpretation 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?

All three parameters are already fully described in the schema, so the description adds value by explaining how topic vs explicit modes relate and that both run the same token-overlap matcher. This is useful context beyond the schema, though somewhat redundant with the 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?

Opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then lays out the two operational modes and the response shape, so an agent can clearly distinguish this from same-family tools like polymarket_arbitrage or polymarket_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?

Provides clear mode-based usage guidance: topic shortcuts for pre-mapped events, explicit tickers/slugs for custom pairings, and a warning that most pre-mapped topics currently return compatibility_warning rather than tradeable spreads. It does not explicitly name sibling alternatives for exclusion, but the context is strong.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds significant behavioral context: it cascades through multiple lookup endpoints, asserts nothing on ambiguous matches (returns figi_candidates), labels identifiers by source, explicitly lists unresolved identifiers, and explains how ISINs resolve to legal entities. These details are not present in annotations and substantially increase transparency about the tool's behavior.

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

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

The description is dense and information-rich, starting with examples and the core purpose, then detailing supported types and edge cases. It is not overly verbose for the tool's complexity, but it is a long paragraph that could be slightly streamlined (e.g., listing examples in a more scannable way). It is appropriately front-loaded with the primary use case.

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 so thoroughly: it mentions identifiers are labeled with source, unresolved identifiers are under 'unresolved', multiple matches return 'figi_candidates', and graceful degradation when external services fail. Combined with the parameter detail and usage guidance, the agent has a complete picture 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 the parameters are already documented, but the description enriches meaning beyond the schema. For the 'value' parameter, it provides formatting rules (pass entity name only, not full noun phrase) with concrete examples (e.g., 'NEW YORK ST DORM AUTH' vs 'NEW YORK ST DORM AUTH revenue bonds'). For 'type', it details what each type returns (CIK, ticker, LEI, FIGI, RxCUI) and acceptance criteria (ticker, CIK, ISIN, or name). This goes well beyond the schema's basic enums and descriptions.

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

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

The description opens with concrete query examples ('What's the ticker for...') and then states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings by emphasizing it is the first stop for name-to-ID resolution and enumerates two supported types (company, drug) with explicit sub-details. This is specific, actionable, and differentiates it from other tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear directive. It further clarifies when not to use certain behaviors (e.g., for bonds, pass the issuer exactly as printed, not the full noun phrase) and explains fallback behavior (graceful degradation when GLEIF/OpenFIGI unavailable). This provides strong guidance on when and how to invoke the tool, including what to avoid.

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.