Useragent

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that Anthropic requires a BYO key and direct payment, and outlines the return structure (score, confidence, signals, raw_response). 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 a single, well-structured paragraph of 5 sentences. It starts with the primary action and default, then details parameters and return, then lists use cases. No unnecessary words; each sentence earns its place.

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

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

The description covers purpose, parameters, return structure, and use cases. Given the lack of an output schema, it adequately describes the return format. However, it omits potential details like caching behavior or rate limits, which would make it more complete for a 4-parameter tool with rich annotations.

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

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

Despite 100% schema coverage, the description adds significant value: it specifies the default model ('Workers AI Llama-3.3-70b (free)'), clarifies that '_apiKey' is only needed for Anthropic and is passed through, and explains 'context' helps disambiguate common names. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for visibility scores, specifying the verb 'probe' and resource 'LLMs for business/brand/product/topic'. It distinguishes from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on AI visibility scoring rather than general Q&A or scanning.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use additional models (Anthropic) and the default model, but does not explicitly state when to avoid using this tool in favor of siblings.

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

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

Annotations already establish readOnly/openWorld/idempotent/destructive characteristics, and the description adds meaningful behavioral detail on top: it routes questions to an underlying tool network, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not disclose failure behavior for unanswered questions, but the annotations already cover the safety profile.

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

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

The description is front-loaded with the key imperative ('PREFER OVER WEB SEARCH') and organized around scope, use cases, examples, and alternatives. It is longer than strictly necessary due to the domain enumeration and five examples, but each part contributes to preventing misuse of the routing tool.

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 broad scope and no output schema, the description adequately explains the return behavior: a structured answer with stable citation URIs. It covers when to use it, what input it expects, and which sibling tools to switch to for specialized cases. A small gap is not describing how it handles ambiguous or unsupported questions, but overall it is sufficient for an agent to select and invoke it.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the same natural-language question. The description reinforces natural-language input and provides helpful example questions, but it mostly stays at the same level of specificity as the schema; it adds no new constraint or format detail beyond the baseline.

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

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

The description clearly identifies the tool as a factual question-answering router: it routes to 5,743 tools across 1,500 verified sources and returns structured answers with stable Pipeworx citation URIs. It also differentiates itself from siblings by positioning itself as the default ('START HERE for most questions') and explicitly contrasting with ask_pipeworx_grounded and 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 gives explicit when-to-use guidance: prefer over web search for factual/current/historical questions, even when web search could answer, and lists concrete query examples. It also states when not to use it and which alternatives to select: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions.

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 live candidate routing behavior, the fact that no candidate is currently active as of 2026-07-26, and that it is a full working router rather than a fallback stub. This dynamic context is valuable and not captured by the readOnlyHint/openWorldHint/idempotentHint 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 three sentences, each carrying distinct value: definition/parity, live-candidate status, and usage guidance. It is appropriately sized for the experimental nature of the tool, though slightly dense.

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 rich annotations, full schema coverage, and the description's coverage of experimental status, current parity with ask_pipeworx, and how results are used, an agent has enough information to select and invoke the tool correctly. An output schema is absent, but the description states the response matches ask_pipeworx.

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 all six parameters documented as aliases for the required 'question'. The description only mentions 'same arguments' and does not add semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta universal router identical to ask_pipeworx, with the same 5,743 tools, arguments, and response shape. It further distinguishes it as the experimental edge with candidate routing improvements, so an agent can separate it from siblings without opening schemas.

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 states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not spell out explicit exclusion conditions or alternative tools like ask_pipeworx_grounded, but the context is clear.

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

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

The description discloses significant behavior beyond the annotations: it routes through thousands of sources, fills arguments, fetches data, and extracts answers using only tool-result content. It also specifies the exact refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and the extra LLM call cost, which is valuable beyond readOnlyHint/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 sentence earns its place: purpose, mechanism, return contract, refusal behavior, usage guidance, and cost tradeoff. It is front-loaded with the most important distinction ('hallucination-resistant') and ends with actionable routing advice.

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 having no output schema, the description provides a complete return contract including the success shape and all refusal reasons. It also covers when to use, when not to use, cost implications, and behavioral guarantees, so an agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the parameter descriptions already fully document the aliases for the single 'question' parameter. The tool description does not add much parameter-level detail beyond implying the input is a natural-language question, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by emphasizing that answers are extracted using ONLY the tool result. The verb+resource relationship is explicit: this tool answers questions through grounded extraction rather than generation.

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 states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also names ask_pipeworx as the alternative for casual lookups and explains the cost tradeoff ('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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds extensive behavioral detail: resolver contract (confidence levels, alternatives), parent event extraction, news fallback, safety short-circuits, closed market handling, spread warnings, and cancellation rule parsing. No contradiction with annotations.

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

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

Description is very long (multiple paragraphs) and covers many details, but lacks clear structure or bullet points. Some redundancy (closed markets mentioned twice). Could be more concise and organized for easier parsing by an AI agent.

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 complexity (many fields, edge cases, and no output schema), description covers all critical aspects: inputs, outputs, classifiers, fan-out logic, response shapes, resolver confidence, parent events, news error handling, safety, closed markets, wide spreads, and cancellation rules. Leaves no major 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%, but description adds meaning beyond schema: explains market parameter accepts multiple formats (slug, URL, text), clarifies depth values (quick=2-3 sources, thorough=full fan-out), and provides guidance on include_raw (when to use true/false). Examples further illustrate usage.

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

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

Description explicitly states the tool researches Polymarket bets by pulling Pipeworx data, specifies input types (slug, URL, question text), and describes output (evidence packet + comparison). Clearly distinguishes from sibling tools like general research or other polymarket 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?

Provides explicit use cases ('should I bet on X', etc.) and describes blocking conditions (low confidence, closed markets) that guide when to trust results or avoid using the tool. Implicitly tells when not to use based on market status.

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, so safety profile is clear. The description adds behavioral context: parallel call execution, correct handling of off-calendar fiscal years, sorted results by primary metric, and inclusion of pipeworx:// citation URIs. No contradictions.

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

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

The description is comprehensive but not overly verbose. It front-loads with common user query patterns and each sentence adds information. Slightly longer than necessary, but still efficient for the detail provided.

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 mentions 'Returns paired data + pipeworx:// citation URIs per entity' and lists the data fields for each type. This provides sufficient context for an AI agent to understand the return shape. Lacks details on pagination or large result sets, but given the tool's bounded scope (2-5 entities), it is appropriate.

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 meaning beyond schema: it explains what each 'type' enum value retrieves (company: 10-K revenue/net income/cash/debt; drug: FAERS/FDA counts) and specifies that 'values' should be tickers/CIKs for companies and drug names for drugs, with a range of 2-5.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, listing specific data pulled for each type (10-K financials for companies, FAERS counts for drugs). It distinguishes from sequential lookups with explicit phrasing 'ALWAYS PREFER over sequential single-pack 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?

The description provides strong guidance: it specifies query triggers (e.g., 'which is bigger', 'rank these companies'), prefers over sequential lookups, and sets entity count range (2-5). It lacks explicit exclusions (e.g., when not to use) but is otherwise very directive.

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 the readOnly/openWorld/idempotent annotations, disclosing decomposition behavior, parallel routing to 5,743 tools, the findings packet structure, explicit gaps[], 'never invented' hallucination policy, contradiction[] scans, semantic excerpting, latency expectations, and auth/paywall constraints. These are exactly the behavioral traits an agent needs to invoke and interpret the tool correctly.

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 and every major behavioral claim is relevant, but it is one long run-on paragraph with duplicated guidance: 'use ask_pipeworx instead — it works on every tier' appears twice. The purpose and usage guidance are not cleanly front-loaded, and the structure would be more scannable as separated usage, behavior, and output expectations.

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 return fields, citation resolvability, gap handling, contradictions, depth semantics, auth requirements, latency, and limitations. An agent has enough context to decide when to call it, how to set depth, what to expect back, and how to handle failure gaps.

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

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

The input schema already covers both parameters at 100% coverage, including a detailed explanation of the depth enum. The description repeats much of this and adds some operational context like 'thorough needs a paid plan' and timing expectations, but it does not add substantially new meaning for the question or depth parameters themselves. 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in ONE call, and explicitly distinguishes itself with 'this is NOT open-web search.' It also names concrete use cases like 'compare X and Y's regulatory + financial exposure,' which clarifies what the tool is for and how it differs from alternatives.

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 ('Best for broad/multi-part questions over structured data'), and explicit when-not-to-use guidance with a named alternative ('For a single lookup use ask_pipeworx instead'). It even handles the auth edge case: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' This is model best-practice routing.

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

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

Annotations indicate readOnlyHint, idempotentHint, and non-destructive nature. Description adds valuable behavioral details: returns top-N relevant tools with full schemas and examples, and each result is 'ready to call directly, no second schema lookup needed.' No contradiction with annotations.

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

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

Description is concise (4 sentences) and front-loaded with purpose. Each sentence earns its place: purpose, usage examples, key behavior (returning ready-to-call results), and explicit call-to-action ('Call this FIRST'). No fluff.

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

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

Despite no output schema, the description adequately explains that the tool returns a list of tools with names, descriptions, and schemas. For a discovery tool, this is complete. The context of being a first step among many sibling tools is well addressed.

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). Description adds meaning by explaining the 'query' parameter expects natural language, listing aliases, and providing examples. The limit parameter is also described. This goes beyond the schema's 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?

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific data domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself as the discovery tool among siblings like deep_research and entity_profile.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (when you already know the tool). No need for alternatives since the sibling list is provided.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive, so the bar for behavioral disclosure is lower. The description still adds valuable behavior: one parallel fan-out across many sources, soft-fail behavior for patents, expected empty results for FDA products in small-molecule-only companies, and a real 'no data' vs bug distinction via sources_used/sources_failed. It also explains name resolution and the resolved:false outcome.

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 information-dense; every sentence adds a distinct fact an agent needs. The user-intent phrases are front-loaded, followed by input flexibility and failure semantics. Some length is justified by listing the fan-out sources, though it could be tightened without losing value.

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

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

For a complex multi-source tool with no output schema, the description covers input variants, resolution behavior, per-source failure modes, expected-empty nuances, and return fields such as cik, filings URIs, fundamentals, and sources_used/failed. The only minor gap is that it doesn't enumerate every return field exhaustively or describe limits like the 'up to 5 filings' cap in more depth, but it is largely 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 the schema documents both parameters. The description adds meaning by clarifying that type='company' and type='ticker' are interchangeable and that value may be a ticker, CIK, or company name regardless of type. That goes beyond the schema, which says type is either but does not explicitly say both behave identically for value shapes.

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 natural-language queries and states a precise purpose: a one-call, cross-source profile of a US public company. It names the resource (US public company via SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, GLEIF) and differentiates from single-pack lookups, so an agent can distinguish it from siblings like resolve_entity and 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?

It says explicitly to ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups for holistic views, and it defines accepted input forms: ticker, zero-padded CIK, or company name. It also explains when resolution fails (private company → resolved:false with notes), which helps an agent decide whether to fall back to another 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 mark destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data and staleness. No contradiction, but doesn't address idempotentHint=true or potential side effects.

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

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

Two concise sentences plus a pairing note. Every sentence adds value, front-loaded with action and usage.

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 simple tool (1 param, no output schema, annotations present), the description fully covers purpose, usage, and related tools. No gaps remain.

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

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

Schema coverage is 100% for the 'key' parameter, which already has a description. The tool-level description doesn't add further parameter semantics, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific, and it distinguishes from siblings like 'remember' and 'recall' by explicitly naming them.

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

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

Description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also pairs with 'remember' and 'recall', offering alternatives and context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format, which aligns with annotations and provides 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 two sentences plus a short use-case list, all front-loaded with the core purpose. Every sentence adds value: first sentence defines action, second explains process and output, third lists use cases. No unnecessary 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 tool with 2 parameters and no output schema, the description fully covers what the tool does, what input is needed, and what output is produced (a text blob in llms.txt format). It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining that the url is fetched and extracted, and max_links controls the number of link entries. This adds meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing specifically on llms.txt generation.

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

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

The description explicitly lists three use cases: getting a client's site indexed by AI, drafting llms.txt for own project, or auditing competitor visibility. It does not explicitly state when not to use or provide alternatives, but the use cases are clear and imply when this tool is appropriate.

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 return field details and usage context, providing value beyond 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, no wasted words, front-loaded with action and return fields, then usage guidance. Highly efficient.

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

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

For a simple list tool with one parameter and no output schema, the description covers purpose, return fields, and usage context completely. 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 description coverage is 100% for the single optional parameter 'include_inactive'. Description does not add extra information beyond the schema's description, 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?

Description clearly states it lists the caller's active subscriptions, specifies returned fields, and distinguishes from sibling tools like subscribe/unsubscribe by mentioning use cases: review before adding or find id to cancel.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This guides the agent on appropriate contexts and indirectly tells them not to use for subscribing/unsubscribing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive actions. The description adds that it extracts specific categories (browser, OS, device type, bot flag), which provides some behavioral context beyond annotations, but it does not disclose edge cases or error handling.

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

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

Single sentence, front-loaded with action verb, lists output categories without extraneous words. Every part of the description is necessary and informative.

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

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

With no output schema, the description lists structural output components (browser, OS, device type, bot flag), which provides a good sense of return values. It could be more precise about the format, but for a simple parsing tool it is sufficiently 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% with the single 'user_agent' parameter clearly described. The description does not add new meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Description begins with 'Parse a User-Agent string,' clearly specifying the verb and resource. It lists exact output fields (browser, OS, device type, bot flag) and distinguishes itself from sibling tools, none of which parse user agents.

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

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

The description implies use for extracting structured data from user-agent strings but gives no explicit guidance on when or when not to use it, nor mentions alternative tools. It is adequate but lacks decision-making context.

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

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

With all annotations false, the description carries the burden and does it well: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token workflow for later status checks, and the requirement to describe issues in terms of Pipeworx tools rather than pasting end-user prompts.

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 carries actionable information, front-loaded with the purpose. The structure flows from purpose to usage criteria to exclusions to behavioral details, avoiding 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?

Functionally complete: covers when to use, what to include/exclude, the two operation modes (file vs. claim_token lookup), rate limits, and post-submission expectations ('digests daily ... affects roadmap'). The only minor gap is the lack of an explicit success response format, but the claim_token mention and schema partially cover it.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining the claim_token round-trip (filing returns a token to poll later) and giving content guidance ('don't paste the end-user's prompt') that refines message/context parameters. This goes slightly beyond the schema's structural 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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the verb (tell), resource (Pipeworx team), and scope (feedback on tool bugs, gaps, praise). It distinguishes this tool from sibling research/query tools by positioning it as the exclusive channel for reporting issues about Pipeworx 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 specifies when to use: for bugs, missing features, data gaps, or praise. It gives a clear exclusion—'ONLY for tools served by this Pipeworx connection'—and directs users to file issues with a different MCP server instead, plus a disambiguation tip ('Not sure? Pipeworx tool names are the ones this connection lists'). This is model guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds transparency about data source (CF analytics-engine), no PII, and caching (5min-1h), which are valuable 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?

Three focused sentences, front-loaded with the essential output, followed by use cases and sourcing details. Every sentence adds value without redundancy.

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

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

Given only one parameter, no output schema, and rich annotations, the description is almost complete. It explains outputs, derivation, caching, and use cases. Missing explicit return structure, but the output is straightforward.

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 schema already explains the window parameter's behavior ('shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description does not add additional parameter-level insight beyond that.

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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, and distinguishes from sibling tools like discover_tools or ask_pipeworx.

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

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

The description lists three specific use cases: discovering hot data sources, confirming canonical tools, and checking alignment. It provides clear context for when to use, though it does not explicitly exclude use cases or mention alternatives.

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

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

The description discloses numerous behaviors beyond annotations: scanning modes, semantic anchor (Jaccard similarity), partition filter, fill check (theoretical vs realizable edge), and conditions for not trading. No contradictions with annotations.

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

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

The description is dense and long (about 200 words). While all content is relevant, it lacks structure like bullet points or separate sections, making it harder to parse quickly. It is verbose but not overly so.

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 modes, internal checks, output fields), the description covers modes, parameters, checks, return structure, and references another tool. No output schema exists, so the description compensates well.

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 each parameter has a description. The description adds extensive semantics: examples of event slugs and topic seeds, how each mode works, and internal logic. This goes beyond the schema descriptions, earning a 4.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb ('find'), resource ('arbitrage opportunities on Polymarket'), and methodology, distinguishing it from sibling tools like polymarket_edge_tracker.

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: 'Call with NO args for a trending_scan... pass event for... or topic for...' It explains when to use each parameter and even mentions an alternative tool ('For custom sizing use polymarket_fill_risk').

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 (readOnlyHint, idempotentHint, destructiveHint) are already clear. Description adds deep behavioral detail: model families, response structure, caching, diagnostics, Fed note – all 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?

Well-organized with sections and bullet points. Front-loaded purpose. Slightly verbose but every part adds value; could be tightened 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?

For a complex tool with 9 params, no output schema, and multiple model families, the description covers models, response structure, knobs, caching, diagnostics, and edge-case notes (Fed). Highly 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 100% of parameters with descriptions. Description adds context (e.g., slippage rationale, min_liquidity tradeable-edge explanation) that extends schema meaning, justifying above-baseline score.

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

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

Description clearly states verb ('scan'), resource ('top Polymarket markets'), and unique value ('Pipeworx data disagrees with market price'). Distinguishes from siblings like polymarket_arbitrage by focusing on model-driven 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?

Explicitly targets 'what should I bet on today' use case and mentions knobs for filtering. Lacks explicit when-not-to-use comparisons with alternatives but provides enough context for typical usage.

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

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

The description adds substantial behavioral context beyond the annotations, including data source (daily snapshots), limitations (60-day TTL, snapshot gaps), and decay computation (from daily closes, not intraday). No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections (main text, RESPONSE, LIMITS). Each sentence adds value, though some redundancy with schema info could be trimmed.

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 provides a detailed account of the response structure (tracked, expired, snapshot_dates) and limitations. It is complete for a telemetry tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the context of 'days' (lookback) and 'window' (snapshot family) with defaults and clamping. It also clarifies the semantics of the parameters in relation to snapshots.

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: providing edge persistence and decay telemetry from daily snapshots. It answers specific questions about edge duration and trends, and distinguishes itself from siblings like 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?

The description implicitly guides usage by explaining the data source and what questions the tool answers. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safety. Description adds rich behavioral details: it walks the ladder, returns specific fields like top_of_book, slippage, verdict, forced_directional_risk, and clamping of size_usd. No contradictions.

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

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

Description is verbose but well-structured with all-caps keywords (REQUIRES, SINGLE-MARKET, BASKET) to improve scannability. Every sentence adds value; however, it could be slightly more concise using bullet points.

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 documents return fields for both modes (single-market: 6 fields; basket: 7 fields including per-leg detail and thin_legs). It also covers edge cases like partial fills and forced directional risk, making it fully self-contained.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds extra context: explains size_usd differs between single-market (USD spend/proceeds) and basket (settlement notional per leg), provides defaults and clamp range. This goes 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 defines the tool as a realizable-vs-theoretical edge check against live order-book depth, with explicit mention of single-market and basket modes. It distinguishes from siblings by stating it should be used before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

Explicitly states when to use the tool: before any polymarket_arbitrage sell/buy-every-leg signal or polymarket_edges trade above ~$500. It also explains consequences of not using it (unhedged directional position). While it doesn't state when not to use, the context is clear.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior, and the description adds substantial behavioral context beyond that: the token-overlap matcher, compatibility warnings and codes, temporal alignment caveats, skipped-leg counters, and a standing fee disclosure. There is no contradiction with 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 it is well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, fees_note) and front-loads the core purpose before diving into caveats. Every sentence contributes information, though the density and length keep it just short of minimal-waste.

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

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

With no output schema, the description carries the full burden of documenting return behavior, and it does so thoroughly: raw per-leg probabilities, top_spreads_pp with per-entry flags, compatibility fields, temporal_alignment semantics, fees_note, and skipped-cross counters. An agent has enough detail to call the tool correctly and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds useful interaction semantics: topic auto-fetches mapped events while the explicit ticker and slug override that mapping, and both modes run the identical matcher. It largely restates the parameter values already in the schema, but it clarifies how the three parameters combine.

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: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It then makes the tool's identity unambiguous by naming both modes, the response shape, and safety fields, so an agent will not confuse it with same-venue tools like 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?

The description gives clear context for when to use the tool: compare prices across Kalshi and Polymarket, either via pre-mapped topic shortcuts or explicit ticker/slug pairings. It also warns that pre-mapped topics are often not tradeable, but it does not explicitly name sibling alternatives or state 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond annotations by specifying scoping ('Scoped to your identifier...'), which is not present in annotations. 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 extremely concise (3 sentences) yet packed with all necessary information. It is front-loaded with the primary action, and 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?

Although there is no output schema, the description explains what the tool returns (value for a key, list for no key) and mentions scoping and related tools. This is complete for a simple retrieval tool given the rich annotations.

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

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

Schema coverage is 100% (the single optional 'key' parameter is described). The description adds value by clarifying that omitting the key lists all keys, which is not explicit in the schema description. This goes beyond the baseline 3.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('value saved via remember', 'saved keys'). It distinguishes from siblings like 'remember' and 'forget' by explicitly mentioning their pairing.

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 clear when-to-use guidance ('look up context... without re-deriving it from scratch') and mentions complementary tools. It lacks explicit when-not-to-use advice, but the context is sufficiently clear.

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

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

Annotations indicate read-only and idempotent; description adds context about return fields (source, citation_uri, payload) and the mark_read side-effect, which is non-destructive. No contradiction.

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

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

Four sentences, each earning its place: purpose, return content, filtering/mark_read, and alternative access. No redundancy or fluff.

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

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

Covers all 5 parameters, return values (though no output schema), side-effects, and usage modes (polls, scripts). Sufficient for a read-only retrieval tool.

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

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

Schema coverage is 100%, but description adds examples (type='sec_8k', ISO timestamp for since) and explains mark_read's effect, going beyond schema descriptions.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', and distinguishes from sibling tools like list_subscriptions by focusing on alert retrieval.

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 filtering guidance for type and since, explains mark_read for deduplication, and notes polling suitability and an alternative HTTP endpoint. Lacks explicit when-not-to-use but is clear overall.

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), it explains the parallel fan-out to multiple sources, GDELT→GNews fallback on rate limit/5xx, soft-fail for USPTO due to API sunset, and the structure of returned 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?

The description is front-loaded with example queries, then provides a dense but efficient technical explanation including fallback logic and output structure, with 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?

Despite no output schema, the description adequately describes the return format (changes[] grouped by source, total_changes count, pipeworx:// citation URIs) and covers all important behavioral aspects of this complex multi-source tool.

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

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

With 100% schema coverage, the description adds value by explaining the since parameter format with ISO dates and relative shorthand ('7d', '30d', '3m', '1y') and suggests typical monitoring values, which goes beyond the schema.

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

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

The description clearly states it provides a change feed for a company from multiple sources (SEC EDGAR, GDELT/GNews, USPTO) within a time window, distinguishing it from the sibling entity_profile which returns a static profile.

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

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

Provides explicit usage examples ('What's new with X'), explains fallback behavior (GDELT→GNews), specifies when to use entity_profile instead, and gives guidance for the since parameter ('Use '30d' or '1m' for typical monitoring').

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 idempotent and non-destructive behavior. Description adds value by explaining key-value storage, identifier scoping, and session vs. authenticated persistence. No contradictions.

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

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

Front-loaded with primary purpose, but description is slightly verbose with examples and pairing notes. Still clear and 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?

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, behavior, and persistence thoroughly. 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 provides full descriptions for both parameters (key, value) with examples. Description does not add significant meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Save data') and resource ('key-value pair'), with concrete examples ('resolved ticker, target address'). It clearly distinguishes from sibling tools like 'recall' and 'forget'.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and pairs with 'recall' and 'forget'. Also provides context on scoping and persistence duration.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower. The description adds rich behavioral context: it discloses internal cascading lookups ('replaces 2-3 manual lookups'), graceful degradation when GLEIF/OpenFIGI are unavailable, explicit listing of unresolved identifiers, and the behavior of returning figi_candidates when ambiguity exists. It also explains that non-equity instruments (bonds) are covered, which is non-obvious. This goes well beyond what annotations provide.

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

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

The description is long but well-structured: it leads with a purpose statement and directive, then enumerates supported types, then details edge cases and fallbacks. It uses quotes and examples to break up text. While it could be trimmed, the density of critical information (e.g., bond issuer name handling, unresolved identifiers) justifies the length. It's not bloated or repetitive.

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

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

For a tool with two entity types and multiple identifier sources, the description covers every aspect an agent needs: input format, output expectations (including unresolved and candidates), failure modes, and even performance characteristics ('replaces 2-3 manual lookups'). There is no output schema, so the description carries the burden of describing return behavior, and it does so comprehensively.

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

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

Schema coverage is 100% (both parameters described). The description adds substantial nuance: for 'value', it explains exactly what to pass for company (ticker, CIK, or name) vs drug (brand or generic), and warns against including trailing security-class words for bonds. For 'type', it clarifies the meaning of each enum value and what identifiers are returned. The description complements the schema rather than repeating it.

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

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

The description opens with concrete example queries and states clearly: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates the exact identifier set (CIK, ticker, LEI, FIGI, RxCUI) and supported types (company, drug). The phrase 'Use FIRST whenever you have a name but need an ID' explicitly distinguishes it from sibling tools like entity_profile or compare_entities, making the purpose unmistakable.

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

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

The description gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also explains when to avoid using it (e.g., when a name matches multiple instruments, it returns candidates rather than asserting). It provides detailed input instructions for each entity type, including a warning for bonds to pass only the issuer name, not the full noun phrase. This is explicit, actionable usage guidance.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. The description adds value by explaining that it internally calls ai_visibility_check, ranks results, and returns score, confidence, and signal density. 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?

Three sentences: purpose, process, and use case. Front-loaded, no fluff, earns every sentence.

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 mentions 'Returns ranked list with score, confidence, signal density per entity', which adequately describes the output. Also covers entity count constraint (2-8). Complete for the tool's purpose.

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

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

Schema description coverage is 100%. The description does not add significant new meaning beyond the schema; the schema already explains the 'entities' parameter's role (first as subject) and other parameters. 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 explicitly states 'Compare AI visibility across multiple entities side-by-side' and details the process of probing with ai_visibility_check and ranking. It distinguishes itself from the sibling tool 'ai_visibility_check' by focusing on multiple entities.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' and an example query. However, it does not explicitly state when not to use it or compare to other tools like 'compare_entities'.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral detail: fans out across two services, returns specific fields, handles partial failures gracefully, and warns about potential 5-30s delay on bundlephobia first measurement. 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 moderately long but every sentence adds value. It front-loads the main purpose and then details outputs, scope, and edge cases. Could be slightly more streamlined, but not excessively verbose.

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

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

Despite no output schema, the description thoroughly lists the return fields (summary block, advisories, links, alternatives) and explains error handling. Covers all necessary context for an agent to use and understand the tool's capabilities.

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 both parameters clearly. Description adds no new semantic depth beyond stating that version defaults to latest, which is already in the schema. Adequate but not additive.

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

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

The description explicitly states the composite purpose: checking a single npm package for safety, popularity, size, etc. It uses a specific verb ('scan') and a clear resource ('dependency'). Distinguishes from sibling tools by specifying the npm ecosystem and contrasting with other package managers.

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

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

Provides explicit usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Clearly states NPM-only scope and directs other ecosystems to an alternative tool (deps.dev:version). Includes behavior for partial failures and timeouts.

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 rich behavioral details beyond the annotations, such as the embedding model (BGE-base-en), window size (500-char overlapping), maximum input length (200K chars with truncation and flagging), and output format (passages with offsets and similarity scores). Annotations already declare read-only, open-world, and idempotent hints, and the description is fully consistent with 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 structured with a clear initial purpose statement, followed by usage guidance, technical details, and pairing suggestions. It is informative without being excessively long, though the technical details could be slightly condensed for brevity.

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

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

Given the tool's complexity (semantic search with specific model, truncation, offsets, and no output schema), the description fully covers behavior, limitations, and output structure. It provides sufficient context for an agent to use the tool correctly, including examples and pairing suggestions.

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 enriches the parameter definitions with examples for 'query' (e.g., 'supply-chain risk'), clarifies the 'text' parameter's max length and truncation behavior, and specifies the default and range for 'limit'. This adds meaningful guidance beyond the schema alone.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, specifying the action ('search within') and the resource ('record text already pulled'). It implicitly distinguishes itself from other tools by focusing on searching within an already-fetched document, but does not explicitly differentiate from similar search tools like ask_pipeworx_grounded, though it pairs with it.

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

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

The description explicitly advises using this tool when 'the record is too big to cram into the prompt,' explaining the benefit of saving context and returning only relevant passages. It also suggests pairing with ask_pipeworx_grounded for grounded question answering. However, it does not mention when not to use it or provide 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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent. Description adds details: returns new subscription ID, SMS cap of 10/day, phone verification requirement, webhook auto-disable after 10 failures, and HMAC signing details. No contradictions.

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

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

Description is dense but well-organized: header, prerequisites, supported types, delivery channels. Every sentence adds value. Could be slightly more concise but efficient overall.

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

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

Given no output schema, description adequately explains return value (subscription ID) and the one-time webhook secret. Covers all parameters, constraints, and behavioral details, making the tool fully self-contained.

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

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

Schema coverage is 100%. Description enriches each parameter with practical examples (e.g., sec_8k items mapping, webhook signing secret) and constraints, adding significant meaning beyond the schema.

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

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

Description clearly states it creates a subscription to a live-data event stream and returns the subscription ID. Verb 'create' plus resource 'subscription' is specific. Distinguishes from siblings 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?

Specifies prerequisite of Pipeworx OAuth account, lists supported event types and delivery channels. Does not explicitly contrast with sibling tools that may offer similar data (e.g., polymarket_arbitrage), but provides clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details like returning drawn-from-live-catalog examples and the effect of omitting/using the topic parameter.

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 synonyms and structured effectively, though slightly lengthy. Every sentence adds value, but could be 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 no output schema, the description fully explains the return format (category-bucketed questions with exact tool+argument shapes). It covers all aspects needed 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% with a clear description for the 'topic' parameter. The description adds context about the return shape (cross-category spread vs focused) and lists example topic values beyond the schema's enumeration.

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 is the onboarding entry point for an agent, returning category-bucketed example questions with tool+argument shapes. It distinguishes from siblings by focusing on 'what can you do' rather than specific tasks.

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

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

Explicitly says 'Use this FIRST' and provides context for when to call with or without the topic parameter. Lacks explicit exclusion of when not to use, but the guidance is clear and helpful.

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

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

Annotations indicate non-read-only, non-destructive, idempotent. Description adds that the row is deactivated (not deleted) so historical events persist. This clarifies exact mutation behavior and aligns with annotations (no contradiction).

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

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

Three concise sentences, each serving a distinct purpose: action, constraint, and side-effect. No unnecessary 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 and simple single-parameter input, description covers ownership, effect (deactivation), and historical availability. Lacks error handling or state idempotent guarantee, but sufficient for typical use.

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

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

Schema description for 'id' covers format (uuid) and source (returned by subscribe). Description adds the ownership constraint (id must belong to caller), which is meaningful context 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?

Description states 'Cancel a subscription by id' — a specific verb (cancel) and resource (subscription) with scope (by id). It distinguishes from sibling 'subscribe' by implication and mentions ownership enforcement.

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 'Ownership is enforced — you can only cancel your own subscriptions', a clear usage condition. Does not explicitly list alternatives like 'subscribe' but context suggests it's the inverse operation.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description adds substantial context: the two processing paths, the verdict enum values, the critical distinction between 'could_not_verify' and 'unsupported', and the meaning of tolerance_pct. It explains failure modes and citation format, all consistent with 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 informative. It opens with natural-language examples, then states when to use it, explains the internal routing, enumerates the verdict values, and highlights a critical caller-facing caveat. The 'IMPORTANT for callers' section is justified and adds critical safety 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 has no output schema, the description fully explains what is returned (verdict, actual value with citation, reasoning) and covers error semantics (could_not_verify vs unsupported). It also explains the two distinct verification paths and the coverage of both company-financial and other claims, making it complete for an agent to correctly invoke and interpret results.

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

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

The input schema already covers both parameters with descriptions, giving a baseline of 3. However, the description adds practical guidance: tolerance_pct is described as overriding the claim's implied tolerance and recommended for hallucination detection, and the claim parameter is illustrated with examples. This goes beyond the schema.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, using specific verbs like 'verify' and 'fact check'. It distinguishes itself from sibling tools by detailing the SEC EDGAR fast path for company-financial claims and the grounded pipeline for all other claims, and by noting it replaces 4–6 sequential calls.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear when-to-use. It also contrasts with the alternative of multiple sequential calls, but does not explicitly list sibling tools to avoid or exclusions for non-claim queries, so it falls slightly short of a 5.

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