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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context: automatic routing, argument filling, stable citation URIs in the output, compatibility with every tier, and 'one fast call' performance. It does not contradict 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 lengthy but well-structured: it front-loads the key preference directive, then groups use cases, examples, and escalation paths. Each section earns its place, though some repetition of intent (e.g., multiple examples) 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?

For a default query-routing tool, the description covers purpose, use cases, query patterns, sibling comparisons, output format, and operational notes (works on every tier, one fast call). There is no output schema, but the description adequately explains the return value as a structured answer with citations.

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

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

The schema covers all six parameters with 100% coverage, including a rich description of the question field and aliases. The description adds usage examples but no new parameter-level semantics, 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 states the tool's function: routes a question to one of 5,501 tools across 1,441 sources and returns a structured answer with citation URIs. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, making its unique role obvious.

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 opens with 'PREFER OVER WEB SEARCH', lists concrete domains (SEC, FDA, FRED, etc.), provides query trigger phrases, examples, and an explicit 'START HERE' directive. It also names when to escalate to ask_pipeworx_grounded or deep_research, offering clear when-to-use and when-not-to-use guidance.

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

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

The description goes beyond annotations by disclosing the experimental nature, the current state (no candidate active as of 2026-07-26), that routing improvements can be enabled live, and that results are compared against stable. It also clarifies that it is a full working router, not a fallback. This is rich context beyond the readOnly/openWorld/idempotent hints.

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 pack in all essential information: what it is, current status, usage guidance, and reassurance. It is front-loaded with the primary definition and contains no fluff or repetition.

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

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

Given the tool has no output schema and 6 alias parameters, the description covers purpose, current experimental state, and relationship to the stable version. It mentions the same response shape, which mitigates the lack of output schema. Minor ambiguity in 'Falls back to nothing' slightly reduces completeness, but overall it is well-rounded.

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 parameters being aliases for 'question'. The description only states 'same arguments' as ask_pipeworx, adding no new semantic detail beyond the schema. Baseline of 3 applies because the schema fully documents the parameters.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with 5,501 tools, and differentiates it from the stable sibling as the experimental edge. The verb 'ask' and resource 'Pipeworx Beta' are explicit, and its relationship to ask_pipeworx is unambiguous.

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

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

It explicitly says when to use it ('Use it exactly like ask_pipeworx when you want the newest routing') and contrasts it with the stable router by stating results are compared to decide merges. It also clarifies that with no active candidate, it matches ask_pipeworx exactly, implying when stability is needed, use the stable 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?

Despite annotations already indicating readOnly, openWorld, idempotent, and non-destructive, the description adds rich behavioral details: the exact return structure with evidence, refusal reasons, routing scale, and the extra LLM call. No contradiction with annotations.

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

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

The description is front-loaded with the core value proposition, then methodically covers mechanism, return format, usage, and cost. Each sentence adds essential information; no filler or repetition.

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

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

The tool has no output schema, but the description fully specifies return format, refusal types, and success fields. Annotations cover safety. Sibling relationships and use cases are well-explained. Complete for the tool's complexity.

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

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

Schema coverage is 100% with all parameters clearly described as aliases for 'question'. The description adds semantic context by specifying the domain (high-stakes reads, financial/legal/medical) and the expectation of direct answers, which helps agents formulate questions effectively.

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 hallucination-resistant answer mode for high-stakes reads, with a specific verb (EXTRACTS) and resource (data from 5,501 tools across 1,441 sources). It distinguishes itself from sibling ask_pipeworx by emphasizing groundedness and evidence, making it a distinct alternative.

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 ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). Also mentions the extra LLM call cost as a trade-off, providing clear decision 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 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral context beyond these: parallel tool routing, gap[] behavior without invention, hop/contradiction fields, semantic excerpting, expected latency (15-60s, ~90s for thorough), and account/tier restrictions. It also explains that citations are resolvable only when the source emits one, which is a meaningful caveat.

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

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

The description is dense and front-loaded with the most critical info (account requirement) then flows through scope, use cases, alternatives, depth semantics, and return behavior. It is long but every sentence earns its place with actionable detail; a small deduction for the account/tier warning being repetitive near the end of the depth explanation.

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 richly explains return content: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri resolvability. It covers latency, auth/tier, and alternative tools in detail, making the tool fully usable.

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

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

Schema coverage is 100%, but the description adds valuable semantic detail beyond schema: it explains how question decomposition works, defines quick=3 facets, standard=5 with gap recovery + contradictions, and thorough=8 (paid) with an additional iterative hop. The depth parameter's behavioral trade-offs (latency, paid tier) are clarified.

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+resource framing: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources... in ONE call' and contrasts with 'NOT open-web search.' It clearly distinguishes deep_research from sibling ask_pipeworx and other tools by explaining its parallel decomposition and structured-source scope.

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

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

Explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also names alternatives and covers account/tier prerequisites, giving clear exclusions and fallbacks.

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds valuable behavioral context: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), explains patents API sunset with soft-fail, describes return fields structure, and notes parallel execution. No contradictions with annotations.

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

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

The description is front-loaded with example use cases, then provides a dense but structured explanation of what it does and returns. While it is lengthy, every sentence adds value. Minor reduction could improve conciseness 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?

Given the tool's complexity (multi-source aggregation) and lack of output schema, the description thoroughly explains all return components: CIK, company name, recent filings with URIs, fundamentals with specific fields and sorting, patents with sunset note, news with fallback, LEI. This is sufficient for an agent to understand the output without an output schema.

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

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

Schema coverage is 100% and already describes both parameters well (type as 'company', value as ticker/CIK, names not supported). The description in the main text mirrors the schema's parameter descriptions without adding significant new meaning, so baseline 3 is appropriate.

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

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

The description starts with concrete example queries ('Tell me about X', 'research Acme') and explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call'. It clearly distinguishes from sibling tools like resolve_entity, which handles name-to-identifier resolution.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also specifies when NOT to use: 'Names not supported — use resolve_entity first if you only have a name'. This provides clear decision criteria.

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

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

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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral detail: compatibility checks, temporal alignment, skipped cross-type/cross-subtype counters, and rarity of real spreads. 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 comprehensive but somewhat verbose, especially in explaining safety fields. Each sentence adds information, but could be more concise. Front-loaded with purpose and modes.

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

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

Given no output schema, the description adequately describes the response structure (leg-by-leg prices, top_spreads_pp, safety fields). Covers main use cases and caveats. Parameter descriptions are complete. Lacks only a brief summary of expected output format.

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 three parameters. The description adds extra meaning beyond the schema: explains the two modes, interaction between topic and explicit tickers (overrides), and provides examples. Baseline 3, plus extra value yields 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains the response content and safety fields. It is specific and differentiates from sibling 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?

The description provides explicit guidance on when to use each mode, and warns that most pre-mapped topics return compatibility warnings, so they are not all tradeable. It also explains conditions when spreads are meaningful (temporal alignment, equivalent bet shapes).

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, idempotentHint, and non-destructive behavior. The description adds valuable context beyond that: the tool cascades through multiple endpoints internally, auto-disambiguates, and returns specific citation URIs (pipeworx://...). It does not contradict annotations, and the extra details help set expectations about internal processing and output provenance.

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 densely packed with useful information, including user examples, supported types, and return formats. It is a single paragraph without bullet points, but every sentence adds value. The 'Use FIRST' directive is front-loaded, making it immediately actionable. Slightly long but not wasteful.

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

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

Given there is no output schema, the description thoroughly explains return values and citation URIs for both entity types. It covers input variations and mentions auto-disambiguation. It does not delve into edge cases (e.g., ambiguous names, errors), but for a simple resolver with clear type specifics, it is substantially complete. The annotations cover safety and idempotency.

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

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

The input schema has 100% coverage with descriptions for both parameters and an enum for type. The description goes beyond by providing concrete example values (e.g., 'ozempic', 'metformin') and clarifying different input forms for company (ticker, CIK, name). It also explains the output mapping (e.g., ticker + CIK + company_name), which adds semantic value beyond the schema.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical/official identifiers (ticker, CIK, RxCUI). It lists supported types (company, drug) with distinct return data, and the examples ('What's the ticker for…') immediately convey intent. This distinguishes it from sibling tools like entity_profile or compare_entities, which operate on existing IDs.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear heuristic for when to invoke this tool versus alternatives. It also notes that using resolve_entity replaces 2-3 manual lookups, implying efficiency gains. No exclusions are needed because the supported types and input forms are well defined.

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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint true. Description adds that it returns verdicts, actual value with citation, and reasoning, and replaces 4-6 sequential calls. No contradiction.

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

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

The description is detailed and front-loaded with examples and usage context. It is slightly long but every part adds value, making it well-structured 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?

Given no output schema, the description explains return values (verdicts, actual value, reasoning) and covers both parameters thoroughly. It provides complete behavioral context for a claim verification 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%. Description adds that tolerance_pct overrides default, default is implied by wording capped at 5, and provides claim examples, adding meaning beyond schema.

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

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

The description explicitly states the tool validates natural-language claims against authoritative sources, providing specific example phrases and distinguishing between two processing paths. It clearly differentiates from sibling tools like ask_pipeworx_grounded.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies when to use and outlines the two paths (SEC EDGAR for financial claims vs grounded pipeline for others), but does not explicitly state when not to use.

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