Bright Data

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

Annotations indicate readOnly, idempotent, openWorld, non-destructive. The description adds transparency about the return format: 'Returns per-model {score, confidence, signals, raw_response} + a combined view'. It also notes the direct payment relationship with Anthropic when using `_apiKey`.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence serves a purpose: stating the action, explaining defaults and optional behavior, and listing 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?

Despite lacking an output schema, the description fully explains what is returned (per-model score, confidence, signals, raw_response, combined view) and the conditions for using the optional parameters. Given the tool's moderate complexity and rich annotations, the description is complete.

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

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

Schema coverage is 100% and each parameter has a description. The description adds context: the default model, that `_apiKey` is optional unless probing Anthropic, and the optional `context` parameter helps disambiguate. This enriches understanding beyond the schema.

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

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

The description clearly states the tool 'probes one or more LLMs' for knowledge about an entity and provides a 'visibility score (0-100) per model'. The verb 'probe' and the specific outcome differentiate it from sibling tools like entity_profile or deep_research, which do not focus on AI visibility scoring.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also clarifies when to provide an API key for Anthropic models. However, it does not explicitly mention alternatives or when not to use this tool, though the unique functionality makes it clear.

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

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

Beyond the readOnly, openWorld, and idempotent hints in annotations, the description adds valuable context: it routes to underlying tools, fills arguments, returns citations, and works on every tier with one fast call. This enriches the agent's understanding without contradicting the structured 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 most important instruction ('PREFER OVER WEB SEARCH') and follows with clear examples and alternative-tool guidance. It is somewhat lengthy but every sentence contributes context for a broad, default entry point, making it appropriately sized.

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 breadth, the description covers purpose, usage triggers, alternatives, return format (structured answer with citations), and scope (current/historical data across many domains). For a no-output-schema tool with rich annotations, this is a complete and self-sufficient description.

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 all six parameters documented as aliases for 'question'. The description itself adds no extra parameter meaning, so the baseline of 3 applies. The examples in the schema, not the description, provide usage illustrations.

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 a specific verb and resource: routes questions to the right one of 5,462 tools and returns a structured answer with citation URIs. It distinguishes from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, making its unique role as the default entry point clear.

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

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

It gives explicit 'PREFER OVER WEB SEARCH' guidance, lists trigger phrases ('what is', 'look up', 'get the latest'), and provides when-not-to-use exclusions by directing to ask_pipeworx_grounded and deep_research for specific cases. This fully covers when and when not to use the tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that this is an experimental edge, may have live routing candidates, and currently matches stable exactly. It also notes the last candidate retirement date and the comparison/merge process, which is valuable behavioral context.

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 somewhat long but well-structured, starting with the core identity, then current state, usage guidance, and a reassurance. Some redundancy exists ('identical', 'same') but every sentence contributes valuable context.

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

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

For a router tool with no output schema, the description is highly complete: it covers beta status, current parity with stable, usage direction, and the guarantee that it's a full working router. It also explicitly states the response shape matches ask_pipeworx, eliminating ambiguity.

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 provides 100% description coverage for all six parameters, which are aliases for the same 'question' field. The description's 'same arguments' reference adds no new parameter-specific meaning beyond the schema, 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 it's a beta version of ask_pipeworx, a universal router with 5,462 tools. It distinguishes itself from the sibling ask_pipeworx by emphasizing identical functionality with experimental routing improvements.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no active candidate) and the alternative stable router, making when-to-use versus ask_pipeworx clear.

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

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

Beyond annotations (read-only, open-world, idempotent), the description discloses the extraction mechanism, the exact success and refusal return shapes, and the extra LLM call cost. It even enumerates all refusal_reason values, giving the agent full understanding of failure modes.

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?

Though dense, every sentence contributes critical information: what it does, how it differs from siblings, return structure, refusal reasons, use cases, and cost trade-off. No wasted words; it is structured with a strong opener followed by mechanism and usage guidance.

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 6 parameters and no output schema, the description fully covers behavior, return format, refusal semantics, use cases, and cost. The annotations and schema cover safety and parameters, and the description fills all remaining gaps comprehensively.

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

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

Schema coverage is 100% with all six parameters described as aliases for 'question'. The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate since the schema already documents each alias fully.

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 immediately identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and clearly explains its function: route to the right tool, fetch data, extract answer from the tool result only. It also distinguishes itself from sibling ask_pipeworx by noting the extra LLM call and the explicit refusal behavior.

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

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

Explicit guidance is provided: use when answers will be quoted, cited, or acted on and must not invent facts, with examples (financial verdicts, legal claims, medical lookups). It also says to prefer ask_pipeworx for casual lookups due to the extra cost, naming the alternative directly.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description discloses extensive behavioral details: resolver contract with confidence levels, parent event extraction, news field fallback mechanisms, safety short-circuits, closed market handling, tradeability warnings, and cancellation rule parsing. This far exceeds what annotations provide alone.

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

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

The description is quite long and densely packed with information. While it is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with the primary purpose, its length may hinder quick parsing. Every sentence adds value, but some redundancy exists (e.g., repeating 'low_confidence_match' explanation). A more concise version could improve efficiency.

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

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

Given the tool's complexity and absence of an output schema, the description comprehensively covers inputs, resolution, classification, fan-out behavior, response shapes, safety mechanisms, edge cases (closed markets, wide spreads), and risk factors (cancellation rules). It leaves no critical aspect undocumented, making it fully adequate for an AI agent to understand and use the tool correctly.

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

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

All three parameters are fully described in the input schema (100% coverage). The description adds some context, such as examples for the 'market' parameter and explanation of 'depth' (quick vs thorough), but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to research a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies the inputs (slug, URL, question text) and the workflow (resolve, classify, fan out, return evidence). The use cases ('should I bet on X', etc.) differentiate it from sibling tools like polymarket_edges which focus on edge detection rather than data aggregation.

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

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

The description explicitly states when to use the tool (e.g., 'should I bet on X', 'what does the data say about Y') and provides extensive examples of fan-outs for different bet types. It implicitly differentiates from siblings through these use cases but does not explicitly state when NOT to use it or mention direct alternatives. The safety warnings about low-confidence matches and closed markets provide additional usage 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 indicate read-only, open-world, idempotent, non-destructive. The description adds that it uses a SERP-type zone and returns parsed results. No contradictions, but minimal extra behavioral disclosure (no rate limits or auth details beyond what's in params).

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 practical example. No fluff, front-loaded with purpose.

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

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

No output schema, but description mentions return fields (rank, title, link, description). Parameters are well-documented. Could add more on pricing or error handling, but sufficient for agent invocation.

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

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

Schema covers all 6 parameters with descriptions. The description adds an example call and clarifies defaults for zone and start. Slight improvement over 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 the tool runs a Google search via Bright Data SERP API and returns parsed organic results with geo-targeting. It distinguishes from brightdata_unlock (raw HTML) and other search 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 explains when to use (parsed Google results with geo-targeting) and mentions alternatives (Web Unlocker zones for raw HTML). It lacks explicit 'when not to use' but provides enough context.

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

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

Discloses rotation, anti-bot bypass, CAPTCHA solving, synchronous call taking 10-30 seconds, truncation for large pages, and pay-per-request pricing. All beyond 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?

Single paragraph with front-loaded purpose. Every sentence adds value: features, behavior, prerequisites, pricing, example. No redundant or vague sentences.

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

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

Covers purpose, behavior, prerequisites, pricing, and example. Lacks explicit error handling and detailed return structure (though format parameter controls this). Adequate but not exhaustive.

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 parameter descriptions. Description adds context (e.g., zone auto-naming, API key source) and an example, providing moderate value beyond schema.

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

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

Description clearly states 'Fetch any URL through Bright Data Web Unlocker' with specific verb and resource. Differentiates from sibling brightdata_serp by mentioning built for hardest-to-scrape sites (Cloudflare, PerimeterX, Akamai).

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 indicates when to use (hard-to-scrape sites) and notes behavior (10-30 seconds sync, truncation), but does not explicitly mention when-not-to-use or contrast with siblings like brightdata_serp. Still provides clear 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 indicate read-only, open-world, idempotent behavior. Description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs.

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

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

Description is fairly long but front-loaded with example queries. Every sentence adds value, though could be slightly more condensed. Good structure with clear examples.

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

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

Covers all key behavioral aspects for a tool that handles two entity types, data retrieval, sorting, and output format. No output schema but mentions what is returned (paired data, citations). Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds: explains data sources for each type, gives examples for values (tickers/CIKs/drug names), and mentions sorting behavior, adding value beyond the schema.

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

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

Description clearly states side-by-side comparison of 2-5 companies or drugs with specific data sources per type. Distinguishes from sibling tools by emphasizing it replaces multiple sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and quantifies efficiency gains (replaces 8-15 lookups). Provides clear context for when to use this tool.

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

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

Overdelivers beyond annotations: discloses account requirements, parallel decomposition, gaps[] never-invented behavior, contradictions[] for certain depths, citation_uri fetchability guarantees, semantic excerpting, and expected latency ranges. No contradiction with annotations; readOnlyHint, openWorldHint, idempotentHint, destructiveHint are all consistent.

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 unique operational information (account constraints, sibling alternatives, hop mechanics, citation rules, performance expectations). It is front-loaded with the critical account requirement, though slightly rambling in the middle; still earns its length for a tool of this complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the return shape (findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field) and covers edge cases like breaking news returning empty gaps. Complete enough for an agent to invoke and interpret results 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 already covers 100% of parameters, but the description adds significant semantic depth, especially for the depth enum: explains what quick (=3 facets, single hop), standard (=5 facets, gap recovery, contradictions), and thorough (=8 facets, paid, iterative hop + contradictions) mean behaviorally. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool's primary verb ('research') and resource ('Pipeworx's 1419 STRUCTURED data sources'), and explicitly distinguishes it from open-web search and from sibling tools like ask_pipeworx. It also outlines the mechanism (decomposes, routes, returns findings packet), making the purpose unambiguous.

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

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

Provides explicit guidance on when to use this tool versus ask_pipeworx ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), plus account tier requirements. This is exactly the kind of actionable usage context agents need.

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 provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral traits: it returns top-N most relevant tools with full input schemas and curated examples, and each result is ready to call directly. 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 somewhat long due to listing many use cases, but it is front-loaded with the main purpose and well-structured. Every sentence adds value.

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

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

Despite no output schema, the description explains the return format (top-N tools with names, descriptions, full schemas) and the limit parameter. It is complete for a discovery tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about aliases for query and the limit default/max, but does not add deep semantic value beyond what is in the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of use cases (SEC filings, financials, etc.) and differentiates it from siblings by advising to call this first when exploring the tool set.

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 when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly state when not to use or list alternatives, but the context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, notes that patents soft-fails after May 2025, and describes the news fallback from GDELT to GNews. 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 queries and a clear purpose statement. It is dense with information but remains readable; however, the enumeration of return fields is somewhat run-on. Still, every sentence adds value and the structure is logical, earning a high score though not maximally tight.

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

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

With no output schema, the description fully explains return fields (CIK, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with sunset notice, news via fallback, LEI). Covers prerequisites (name not supported, use resolve_entity). All relevant context for an agent to invoke and use the tool correctly is present.

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

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

Both parameters are 100% covered in schema with descriptions. The description reinforces by providing concrete examples ('AAPL', '0000320193'), explicitly states that only 'company' type is supported and names are not accepted, and references the resolve_entity fallback. This adds practical value beyond the schema alone, meriting above baseline.

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

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

The description starts with concrete example queries and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the tool's specific purpose and distinguishes it from chaining individual lookups, making the intent unmistakable.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. It also warns that names are not supported and directs the agent to 'use resolve_entity first if you only have a name,' covering both when and when not to use the tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds context about clearing sensitive data and assumes idempotent behavior, consistent 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?

Two concise sentences: first states the action and resource, second provides usage guidance and pairing suggestions. No waste.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and pairing recommendations.

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 single 'key' parameter described as 'Memory key to delete'. The description adds no additional 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 action ('Delete a previously stored memory by key') and resource ('key'), and the tool is distinct from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', giving clear context and alternatives.

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

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds that the tool fetches the page, extracts title/description/key links, and emits markdown format, providing behavioral context beyond safety. 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 concise with four sentences, front-loaded with the primary purpose. No wasted words; each sentence adds value.

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

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

With only two parameters and no output schema, the description covers the purpose, behavior, and use cases completely. It specifies that the output is a single text blob ready to deploy, which compensates for the lack of an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant extra meaning beyond the schema: it mentions 'any URL' for the url parameter but doesn't elaborate on max_links.

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 and resource. It mentions use cases but does not explicitly differentiate from sibling tools, missing the top tier.

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 useful scenarios (getting a client's site indexed, drafting, auditing) which implies when to use, but it provides no explicit guidance on when not to use or alternatives, resulting in adequate but not strong direction.

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, etc. Description adds value by listing returned fields, confirming non-destructive nature. No contradictions.

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

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

Two concise sentences, front-loaded with purpose. Every sentence adds value with no redundancy.

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

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

Simple tool with one optional boolean parameter. Description covers return fields sufficiently for a list operation. No missing context given the schema and 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% and parameter 'include_inactive' already has a description in the schema. Description does not add extra meaning beyond what schema provides, so baseline 3 applies.

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

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

Description clearly states the tool lists active subscriptions and specifies exact returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling tools like subscribe/unsubscribe by being a listing operation.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Tells when to use but does not explicitly state when not to use or provide alternatives beyond the implied disambiguation.

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 are all false, so the description carries the full behavioral disclosure burden. It does so by revealing rate-limiting ('Rate-limited to 5 per identifier per day'), quota independence ('Free; doesn't count against your tool-call quota'), and processing cadence ('The team reads digests daily'). It also instructs users not to paste end-user prompts, clarifying what the team expects.

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 front-loaded with purpose, followed by usage scenarios, exclusions, and constraints. Every sentence serves a functional role (e.g., rate limit, quota, prompt-content policy), and the structure flows from what/when to how/limits. Slightly verbose but economical for the complexity of the tool.

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

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

For a feedback tool with no output schema, the description covers all relevant operational details: accepted types, optional context structure, message length limit ('2000 chars max'), rate limit, quota behavior, and scope boundaries. It gives users everything needed to submit useful feedback without unexpected consequences.

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 every parameter described inline. The description enriches this by giving concrete example values for the context object (pack 'fred', tool 'fred_get_series') and by advising users to describe issues in terms of Pipeworx tools/packs, which clarifies how to format the message and context beyond the schema's generic field-level 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 a clear verb-resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the four feedback categories (bug, feature, data_gap, praise) and distinguishes this tool from sibling tools by limiting it to Pipeworx-served tools, not other MCP servers.

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 provides explicit 'when to use' guidance for each feedback type (wrong/stale data → bug, missing tool → feature/data_gap, positive → praise) and clear exclusions: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' It also tells users how to verify tool ownership by checking the connection's tool list.

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

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

The description adds significant behavioral context beyond annotations: it is derived from CF analytics-engine, contains no PII, and is cached 5min-1h. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which are consistent. 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 three sentences, each earning its place: purpose, use cases, technical details. No redundancy or fluff. Front-loaded with the core function.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully covers return values (top tools, packs, volume), data source, privacy, and caching. Nothing needed beyond this.

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% (1 parameter with enum and description). The description adds value by explaining the semantic difference between window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'). This goes beyond the schema's basic description.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It uses specific verbs like 'Returns' and explains the resource (trending usage on Pipeworx). It distinguishes from siblings by focusing on aggregated trending data, not individual tool details.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, seeing alignment) and hints at window selection strategy. However, it does not explicitly state when not to use the tool or mention alternative tools.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavioral context: semantic anchor threshold, partition filter logic, fill check with specific thresholds (realizable_edge_pp ≤ 0 indicates non-tradable). 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 detailed and front-loaded with core purpose and modes. However, it is verbose with technical jargon (monotonicity violations, Jaccard similarity) and internal headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, but a leaner version could improve clarity.

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

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

Despite no output schema, the description fully documents the response structure (opportunities[], partition_check, fill check details) and covers edge cases (skipped_low_similarity, placeholder fraction). It also references a related tool for custom sizing, making it complete for its complexity.

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

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

Schema description coverage is 100%, and the description adds significant value: explains event vs topic modes, provides example slugs and seed questions, and details what each parameter triggers (e.g., event walks child markets, topic searches related events).

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

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

The description clearly states it finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies three modes: no-args for trending scan, event for a specific market, and topic for cross-event scanning, with clear distinctions.

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 recommends when to use each mode (event for specific market, topic for cross-event scanning) and provides a fill-check caveat telling when not to trade. Also references a sibling tool (polymarket_fill_risk) for custom sizing, offering clear guidance on 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?

Beyond annotations (readOnly, idempotent), the description reveals caching (1h KV keyed on knobs), response structure with segments and diagnostics, model families and their assumptions, limitations (Fed bets excluded), and rare-by-design nature of concentrated longshots. 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 very detailed and packed with information, but somewhat dense and could be better structured. It mixes model explanations with parameter guidance, making it slightly overwhelming. Front-loads purpose well, but length may hinder quick scanning.

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

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

Given the complexity (9 parameters, no output schema), the description fully covers the tool's capabilities: model families, response segments, knobs, diagnostics, and caching. Agents can confidently invoke the tool with correct expectations.

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

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

Schema coverage is 100% with descriptions. The tool description adds behavioral context (e.g., min_kelly skips small opportunities, min_partition_leg_kelly applies to per-leg Kelly). This enhances understanding beyond 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 the tool's purpose: scanning Polymarket markets for discrepancies between Pipeworx data and market prices, specifically for 'what should I bet on today'. It differentiates from siblings like polymarket_arbitrage by focusing on edge detection and providing model details.

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

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

The description gives concrete usage guidance, such as adjusting slippage for thin partitions and using knobs like min_liquidity and max_spread_pp. It explains 'tradeable-edge knobs' and diagnostics to understand empty segments. However, it lacks explicit when-not-to-use or comparison to alternatives like polymarket_edge_tracker.

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, and non-destructive. The description adds significant behavioral detail: data sources (daily snapshots), history limits (60-day TTL), decay calculation basis (daily closes), and response structure (tracked, expired, snapshot_dates). No contradictions.

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

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

The description is well-structured with a clear summary first, then detailed response format, and limits. However, it is quite dense and could be more concise without losing meaning.

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 extensively explains the response fields (tracked, expired, snapshot_dates) and their semantics. It also covers limitations and data source details, making it fully informative for agent use.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description adds context about the 'window' parameter as 'snapshot family' and clarifies defaults/clamping for 'days', which provides marginal added 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 provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current snapshots.

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 when to use this tool by contrasting a fresh wide edge with an old one, but it does not explicitly list when not to use it or name alternative tools. The sibling list includes related tools, providing some differentiation.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds substantial behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), includes a verdict (clean|degraded|cannot_fill), and explains dominant loss modes. 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, usage note). While slightly verbose, every sentence serves a purpose. It is front-loaded with essential info. A minor conciseness improvement could be made, but overall it earns its length.

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

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

Despite having no output schema, the description comprehensively explains all return fields for both modes, including edge cases (thin legs, forced directional risk). It covers the full complexity of the tool and provides all necessary information for an AI agent to use it 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?

All 4 parameters have descriptions in the input schema (100% coverage). The description adds meaning beyond the schema by explaining single-market vs. basket modes, interpretation of size_usd (max spend vs. target proceeds vs. settlement notional), and auto side behavior for basket. This provides agents with richer context for parameter selection.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly ties usage to sibling tools like polymarket_arbitrage and polymarket_edges, setting it apart.

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 guidelines: 'REQUIRES one of `market` or `event`' and 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns about partial basket fills converting arb into directional risk, giving clear when-to-use and when-not-to-use 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 declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description goes beyond by detailing behavioral traits like the two modes, how compatibility_warning works in two cases, temporal alignment checks, and skipped comparison counters. It also warns that most pre-mapped topics may not yield tradeable spreads, setting proper expectations.

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

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

The description is verbose but every sentence serves a purpose. It front-loads the core purpose and then details modes, response, and safety fields. While not structured with bullet points, the flow is logical and the length is justified by the tool's complexity.

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

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

Given no output schema, the description covers return values (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It explains edge cases for when spreads are meaningful, making the tool's behavior fully understandable without needing additional context.

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

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

All three parameters are described in the schema with 100% coverage. The description adds value by listing the exact topic shortcuts, explaining the override logic for explicit tickers, and giving examples in the schema. This enhances understanding beyond the basic type declarations.

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 spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and includes detailed explanation of two modes and safety fields.

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 the tool: for comparing prices across venues. It explains the topic shortcuts and explicit ticker modes, and crucially warns when the spread should not be trusted (compatibility_warning, temporal misalignment, skipped pairs). This helps the agent decide when the output is actionable.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds dual behavior (retrieve vs list) and scope, consistent 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?

Four focused sentences: function, use case, scope, pairing. No wasted words. Front-loaded with verb and object.

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 main behavior, scope, and sibling tools. Lacks mention of return value for missing key or empty list, but sufficient for a simple retrieval tool with strong 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% and already explains the key parameter and omission behavior. Description adds no new meaning beyond what schema provides.

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

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

Description clearly states the tool retrieves saved values or lists all keys. It distinguishes from siblings 'remember' and 'forget' by naming them explicitly.

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

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

Provides clear context for use: retrieving stored context without re-derivation. Scoping and pairing with remember/forget is mentioned, though no explicit '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.

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive nature. The description adds behavioral details such as the effect of mark_read on subsequent calls and the polling suitability, which go beyond annotations without contradicting 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 a single paragraph of 5 sentences, each serving a clear purpose (verb, return fields, filters, side effect, alternative access). It is front-loaded with the core action and contains no redundant information.

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

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

The description covers return fields, filtering, side effects, and an alternative endpoint. It does not explain the limit parameter beyond schema, but annotations cover safety. Given no output schema, the description is fairly complete for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds contextual examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains the side effect of mark_read, providing meaning 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 pulls fired events from the subscription feed, specifying the returned fields and filtering options. It does not explicitly differentiate from sibling tools like list_subscriptions or subscribe, but its purpose is clearly distinct as a read operation for alerts.

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

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

The description mentions that polls work fine and provides an alternative REST endpoint for scripts and dashboards, but it does not give explicit guidance on when to use this tool versus alternatives or when not to use it. It lacks context for exclusion or comparison with sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: fans out to three sources, explains fallback logic, mentions USPTO sunset, date format handling, and return structure. 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 example queries and is structured clearly. It is moderately long but each sentence adds value. A slight reduction in detail could improve conciseness, but it remains effective.

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

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

For a tool with three required parameters, no nested objects, and no output schema, the description covers all necessary aspects: purpose, usage, behavior, parameter details, return structure, and sibling comparison. It is complete given the 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 the parameters are documented. The description adds value by explaining the since parameter format with examples ('7d', '30d', '3m', '1y'), the type parameter limitation, and the value parameter accepting ticker or CIK. There is minor additional meaning beyond the schema.

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

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

The description uses specific example queries ('What's new with X', 'latest on Y') and explicitly states it is a change feed for a company in the last N days/weeks/months. It clearly distinguishes itself from the sibling tool entity_profile by specifying when to use that alternative instead.

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

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

The description provides explicit guidance on when to use the tool (for recent changes) and when not to (for static profile, use entity_profile). It also gives alternatives and explains the context for using GDELT vs GNews fallback.

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 provide idempotentHint=true (write once) and destructiveHint=false. Description adds scoping by identifier, persistence (24hr for anonymous, permanent for authenticated), and pairing hints, going 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?

Four efficient sentences, front-loaded with main purpose, no fluff, clearly structured with usage then pairing.

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 key-value store with 2 params, no output schema, and good annotations, the description fully covers purpose, usage, transparency, and parameter context.

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

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

Input schema has 100% coverage with descriptive names and inline descriptions for key and value. Description adds examples and context (key-value pair, scoped by identifier), but does not significantly extend schema meaning.

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

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

Description clearly states the tool saves data for later reuse, with specific examples (resolved ticker, target address, user preference) and distinguishes from sibling tools 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 says when to use ('when you discover something worth carrying forward'), mentions alternatives (recall, forget), and covers scope and retention periods.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally,' explains auto-disambiguation, and details the specific identifiers and citation URIs returned for each entity type. 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 well-structured and front-loaded with examples, then purpose, then usage guidance, then type details. Every sentence contributes unique information with 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?

With no output schema, the description thoroughly covers return values for both supported types, including citation URIs, and explains the internal cascading behavior. It is sufficiently complete for an agent to understand what the tool does and what it returns.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond schema by explaining the exact return fields per type (e.g., ticker + 10-digit CIK + company_name) and noting auto-disambiguation, adding meaningful context to the 'value' parameter.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete example queries and enumerates supported types (company, drug), distinguishing it from sibling tools like entity_profile and compare_entities.

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

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

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to invoke the tool. However, it does not explicitly mention alternatives or when not to use it, so it lacks the full when/when-not contrast.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density. No contradictions. Does not cover rate limits or auth beyond the _apiKey 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?

Three concise sentences. Front-loaded with the primary action ('Compare AI visibility across multiple entities side-by-side'). 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?

No output schema, but description covers return format (ranked list with score, confidence, signal density). All 4 parameters are documented in schema and reiterated in context. Adequately complete for this tool.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds minor extra context: first entity is treated as subject. Baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them by score, and surfaces which is most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by its specific focus on competitive AI-marketing audits.

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 it is useful for competitive AI-marketing audits and gives an example question. While it does not state when not to use it, the context is clear and the sibling list provides 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses partial failure behavior, timing for bundlephobia (5-30s first measurement), and that sources_failed will list timeouts.

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 fairly long but each sentence adds value. It is front-loaded with purpose and then details. Slightly verbose but justified by complexity.

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

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

Despite no output schema, the description lists all return fields and covers usage, constraints, and failure modes. It is complete for an agent to make informed decisions.

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 description adds context: explains that version defaults to latest, accepts scoped packages, and summarizes all return fields giving meaning to parameter outcomes.

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 what the tool does: a composite check for npm packages using deps.dev and bundlephobia, with the specific verb 'scan' and resource 'dependency'. It distinguishes from siblings by noting the npm ecosystem limitation.

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 when to use: when asked about safety, popularity, size, or cost of adding a package. Also states when not: for non-npm ecosystems (PyPI, Maven, etc.), directing to deps.dev directly.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds: embedding model (BGE-base-en), scoring (cosine), windowing (500-char overlapping), input cap (200K chars with truncation+flag), output format (passages with offsets and similarity). 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?

Single paragraph with no wasted words. First sentence states core purpose, second provides usage guidance and pairing, third gives technical details. Every 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?

No output schema, but description covers what is returned (passages with offsets and similarity scores), limits (200K chars, 1-20 passages), and technical specifics. 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 100%. Description adds: natural-language query examples ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies 'text' is previously fetched record, explains 'limit' default (5) and range (1-20). Adds significant value 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 states 'Semantic search INSIDE a fetched record' with specific examples of what to search (SEC 10-K, article, long tool result). Distinguishes from sibling ask_pipeworx_grounded by explaining pairing. Verb+resource+scope clear.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes benefit (saves context, returns only relevant passages). Also mentions pairing with ask_pipeworx_grounded as a complementary workflow.

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 provides extensive behavioral details beyond annotations: creation of subscription, idempotent hint from annotations is consistent, and description adds auth requirements, type-specific filtering, delivery constraints (SMS cap, webhook signing, auto-disable on failure). 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 bullet points and clear sections. It front-loads the main purpose. Minor redundancy could be trimmed, but each part adds necessary context for proper tool 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 tool's complexity (3 params, nested objects, 5 enum values, multiple delivery channels, and no output schema), the description covers all necessary context: authentication, type-specific parameter structures, delivery options with limitations, and edge cases. No gaps for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% and the description enriches every parameter with examples and constraints (e.g., type enum explained with specific scenarios, params object detailed per type, delivery options with validation rules). This far exceeds the schema's minimal descriptions.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the return value ('Returns the new subscription id') and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of subscriptions.

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

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

The description explains when to use this tool (proactive monitoring), prerequisites (requires Pipeworx OAuth account), and lists supported subscription types and delivery channels. It does not explicitly state when not to use or mention alternatives, but the context of sibling tools provides enough differentiation.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds useful behavioral context: it returns category-bucketed example questions with tool+argument shapes from the live catalog, and it is intended for onboarding. 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 informative but lengthy as a single paragraph. It front-loads example questions and then explains functionality. Could be slightly more concise without losing clarity, but it is not overly 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?

The description explains the return format (category-bucketed examples with tool+argument shape) and the appropriate usage context (onboarding). Since there is no output schema, the description adequately compensates by specifying what the tool returns. It is complete for this 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?

The single parameter (topic) is fully described in the schema with a clear enumeration of possible values and default behavior. The description repeats this information without adding new meaning, so the baseline score of 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool is the onboarding entry point for discovering what can be asked of Pipeworx, with specific examples and a verb (suggest, show). It distinguishes itself from sibling tools like ask_pipeworx by focusing on generating question ideas rather than answering 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?

The description explicitly says to use this tool first when unfamiliar with Pipeworx's capabilities and to learn how to call meta-tools. It also explains the two calling patterns (no args or with a topic). Although it does not explicitly list alternatives, the context is clear.

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

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

The description adds significant behavioral details beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events. 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?

Two sentences efficiently convey purpose, ownership, and behavioral effects 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?

Given the simple input schema (one parameter), no output schema, and provided annotations, the description adequately covers all necessary contextual information for correct agent invocation.

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

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

The input schema has 100% description coverage for the 'id' parameter. The description does not add additional meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'cancel' and the resource 'subscription by id', effectively distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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 provides context on ownership enforcement and deactivation behavior, but lacks explicit guidance on when to use this tool versus alternatives like 'subscribe' or 'list_subscriptions'.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds significant context: dual processing paths, verdict types, return fields (verdict, value, citation, reasoning), and efficiency gain (replaces 4-6 calls). No contradictions.

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

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

Description is front-loaded with examples and well-structured. Slightly long but every sentence adds value; could be trimmed slightly without losing meaning.

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

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

Despite no output schema, description fully explains return values (verdict, actual value, citation, reasoning) and covers both processing paths. None missing.

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

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

Schema has 100% coverage with clear descriptions. Description adds guidance that tolerance_pct overrides implied tolerance and suggests values for hallucination detection, providing extra utility.

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 verifies factual claims with natural-language examples. It distinguishes between company-financial claims (using SEC EDGAR) and other claims (grounded pipeline), differentiating from sibling tools like ask_pipeworx_grounded or search tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes two pathways but does not specify when not to use it or name alternative sibling tools for edge cases.

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