Oxylabs

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by stating it 'probes' LLMs, returns per-model scores, and passes the API key directly to Anthropic. 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 a single paragraph with clear front-loading of the main action. It includes necessary details without extraneous text. Could be slightly more structured with bullet points, but it is still concise and readable.

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 fully explains the return format ('per-model {score, confidence, signals, raw_response} + a combined view'), compensates for the lack of an output schema, and covers the API key usage. It is complete given the tool's complexity 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 description coverage is 100% with detailed parameter descriptions. The description adds minimal extra semantics beyond summarizing the default model and API key usage. According to guidelines, with high coverage, baseline is 3, and the description does not significantly elevate it.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It names the default model and explains the API key requirement for Anthropic. This is specific and distinguishes from sibling tools like scan_competitor_ai_presence.

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 specifies use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to provide an API key. However, it does not explicitly state when not to use this tool or provide alternatives, though the context of siblings implies it.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. Description adds context about routing to tools, filling arguments, and returning citation URIs. No contradictions, but could mention rate limits or source variety.

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 somewhat verbose but well-structured with clear sections, examples, and bullet points. Every sentence contributes to understanding, but could be slightly trimmed.

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

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

For a complex tool routing to 5,011 tools, the description is remarkably complete. It explains when to use, how it works, what it returns, and contrasts with siblings. No output schema, but return format is described.

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 detailed descriptions and multiple aliases. Description provides real-world examples that illustrate parameter usage, adding 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?

The description clearly states the tool routes questions to appropriate specialized tools and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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: prefer over web search for factual questions, start here for most questions, step up for grounded or broad queries. Includes concrete examples and alternative tool names.

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

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

Annotations (readOnlyHint, idempotentHint) already provide safety profile; description adds experimental nature, source-preference ranking, and that it's a full working router. 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?

Front-loaded with key identity, each sentence adds value. Slightly dense but appropriate for the complexity; could be tightened slightly.

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

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

Given no output schema, description explains response shape (same as ask_pipeworx) and routing behavior. Lacks explicit return value details but adequate for a routing tool with sibling reference.

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, 100% coverage. Description notes same arguments as ask_pipeworx but doesn't add new parameter meaning beyond schema.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router for 5,011 tools, with the same function but experimental routing. It distinguishes from siblings ask_pipeworx (stable) and ask_pipeworx_grounded.

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

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

States 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the source-preference feature. No explicit when-not-to-use, but the context implies stable routing is served by ask_pipeworx.

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 non-destructive. The description adds detailed behavioral traits: returns structured {answer, evidence, confidence, source, fetched_at, refusal_reason:null} on success or explicit refusals with specific reasons. Also mentions cost (one extra LLM call) and reliance on tool result only. 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 the key concept ('Hallucination-resistant answer mode for high-stakes reads'), then efficiently explains mechanism, return format, and usage guidance in a dense but clear paragraph. Every sentence provides necessary information, 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?

Despite no output schema, the description comprehensively details the return format including success and refusal cases. It also covers usage context, cost trade-offs, alternative tool, and behavioral constraints. For a tool with many parameters (6 aliases) and high-stakes usage, the description is complete and well-rounded.

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

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

Schema description coverage is 100% with detailed alias descriptions. The description does not add new parameter semantics beyond stating 'Your question in natural language.' Baseline 3 is appropriate as the schema sufficiently documents parameters.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: picks the right tool, fetches data, extracts answer using only the result. It distinguishes from ask_pipeworx by noting the extra LLM call cost and intended use case, making the purpose highly specific and distinct.

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

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

Explicitly advises when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with examples like financial verdicts, legal claims, medical lookups. Also provides exclusion: 'prefer ask_pipeworx for casual lookups'. This provides 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?

The description extensively covers behavioral traits beyond annotations: fan-out parallelism, response shapes, resolver contract (match confidence, alternatives, suggestions), parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed markets, illiquid spreads), and resolution-rule risk. This far exceeds the minimal annotation coverage (readOnlyHint, idempotentHint) and provides a comprehensive behavioral model.

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 long and detailed, which provides completeness but sacrifices conciseness. It is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. However, the length may reduce readability for 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 tool's complexity (multiple inputs, no output schema, varied behaviors), the description is remarkably complete. It covers inputs, processing logic, response fields (market, analysis, evidence), error states (low_confidence_match, market_closed_or_inactive), and edge cases (wide spreads, cancellation rules). It compensates for the lack of an output schema by detailing response shapes.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use the market parameter (slug, URL, or question text), the difference between 'quick' and 'thorough' depth, and when to set include_raw to true. This enhances the agent's understanding beyond the schema's type and 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's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb 'research' and resource 'Polymarket bet'. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the context is sufficient for an agent to identify its primary function.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of classifiers and fan-outs. However, it lacks explicit guidance on when NOT to use this tool or comparisons to alternative sibling tools, leaving the agent to infer 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals critical behaviors: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. 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 query examples and uses bullet-style formatting. Every sentence adds value—usage guidance, data sources, sorting behavior, and efficiency claim. Slightly verbose but well-structured for an AI agent to parse quickly.

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 covers what data is returned, sorting, and citation URIs. Given strong annotations and simple parameter structure, the description provides sufficient context for correct invocation and result interpretation.

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%, providing baseline meaning for parameters. The description adds context: for 'type' it specifies exact data pulled (revenue, net income, etc. for companies; adverse-event counts for drugs), and gives examples for 'values' (tickers/CIKs vs drug names). This enhances parameter understanding beyond schema descriptions.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs, with numerous query examples ('Compare X and Y', 'rank these companies', etc.). It clearly distinguishes from sequential lookups, making the purpose unmistakable.

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

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

The description strongly advises preferring this tool over sequential single-pack lookups when comparing entities, providing clear when-to-use guidance. However, it does not explicitly mention alternatives for single-entity lookups (like entity_profile), though the preference statement implies exclusion.

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, and non-destructive. The description adds extensive behavioral context: parallel routing, gap recovery, contradiction scanning, hop field, citation URIs, semantic excerpting of large records, and expected latency (15-90s). 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 long but well-structured: account requirement and alternative first, then core functionality, usage guidance, detailed behavior, and return format. Every sentence adds value, though could be slightly more concise. The length is justified by tool 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 the tool's complexity, the description is remarkably complete. It covers purpose, prerequisites, alternatives, parameter details, execution behavior (decomposition, parallel routing, hops, gap recovery, contradictions), return format (findings with evidence, confidence, source, citations), limitations (empty gaps for non-structured topics), and latency expectations. There is no output schema, but return values are well explained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the depth enum behavior (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and that question expects broad/multi-part natural language. This goes beyond the simple 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 it performs 'grounded multi-source research across Pipeworx's 1319 STRUCTURED data sources' and decomposes questions into facets routed to 5,011 tools in parallel. It distinguishes from siblings like ask_pipeworx by specifying it is for broad/multi-part questions over structured data, while ask_pipeworx is for single lookups or breaking news.

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: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx', 'If you are not signed in, use ask_pipeworx instead', and notes that depth:'thorough' needs a paid plan. It also mentions that deep_research is best for broad/multi-part questions over structured data.

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

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

Annotations already mark it as readOnly, idempotent, non-destructive. Description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' which is valuable behavioral context beyond annotations.

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

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

Description is front-loaded with key purpose and lists domains, but the domain list is lengthy and somewhat redundant. 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?

Tool has 6 params (many aliases), no output schema. Description explains what the output contains (names, descriptions, schemas, examples) and that results are call-ready. Lacks details on pagination or behavior if limit exceeded, but overall 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 describes all 6 parameters with 100% coverage. Description adds examples and notes aliases, but the schema already covers those. No new semantic depth beyond what the 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 'Find tools by describing the data or task' and lists many domains. It distinguishes the tool's role as a discovery tool but does not explicitly differentiate from sibling search tools like 'search_within' or 'entity_profile'.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a list. Also advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context but no 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?

Discloses fan-out across multiple APIs (SEC EDGAR, XBRL, USPTO, news, GLEIF), return fields (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset date, news fallback, LEI), and soft-fail behavior. Annotations already indicate read-only, idempotent, non-destructive; description adds rich 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 dense but well-structured, starting with example queries and then detailing capabilities. Slightly verbose in enumerating all data sources and fields, but every sentence adds value for a complex 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?

Despite no output schema, the description comprehensively lists all return fields and behaviors (multi-source aggregation, fallbacks, sunset dates, limitations). It covers input requirements, usage preferences, and caveats thoroughly.

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, but the tool description adds crucial context: type must be 'company', value can be ticker or CIK (zero-padded), and names are not supported. This goes beyond what the schema enum and property descriptions provide.

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

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

The description uses specific verbs like 'full cross-source profile' and provides concrete examples ('Tell me about X', 'research Acme'). It clearly distinguishes from sibling tools like resolve_entity by specifying the input types and directing name-based queries elsewhere.

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 chaining single-pack SEC/XBRL/news lookups' and advises to use resolve_entity if only a name is available, providing clear decision rules.

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

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

Description indicates destructive behavior ('Delete'), matching annotations. Adds context about clearing sensitive data. Does not mention idempotentHint (true) or behavior on missing key.

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: action, use cases, pairing. Front-loaded with verb. 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?

Simple tool with one parameter. Description covers use cases and pairing. Lacks details on return value or error handling, but acceptable for a straightforward deletion 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%, and description adds no additional meaning beyond 'by key'. 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?

Clearly states verb 'Delete' and resource 'memory by key'. Distinguishes from siblings 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 lists three use cases (stale context, task done, clear sensitive data) and suggests pairing with remember and recall. Lacks explicit when-not scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and explains the output format. 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 at around four sentences, with the main action stated first. Every sentence adds value, though it could be slightly more terse without losing 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?

Given the low complexity (2 parameters, no output schema), the description fully explains the tool's purpose, parameters, output format, and use cases. No gaps remain for an AI agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so both parameters are already well-documented. The tool description adds no new parameter-level information beyond what the schema provides, resulting in a baseline score of 3.

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

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

The description uses specific verbs ('generate', 'fetch', 'extract', 'emit') and identifies the resource ('llms.txt file for any URL'). It clearly distinguishes from sibling tools by focusing solely on generating an llms.txt file, which is unique among the listed 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 explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. It provides clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds return fields and default scope (active only), but no detail on pagination or edge cases. Moderate added value beyond annotations.

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

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

Two sentences: first states action and return fields, second gives usage guidance. No wasted words, well-structured.

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

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

Given single optional parameter and no output schema, description covers purpose, return fields, and common use cases. Lacks detail on ordering or pagination but adequate for a simple list 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?

Single parameter include_inactive has full schema description (100% coverage). Tool description does not add new information about the parameter beyond what 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?

Clearly states verb 'List' and resource 'the caller's active subscriptions'. Differentiates from siblings like subscribe/unsubscribe by specifying reading existing 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?

Explicitly advises using to review before adding more subscriptions or to find an ID to cancel, giving clear context for when to invoke 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 indicate read-only and idempotent behavior. The description adds valuable behavioral context: synchronous proxying, 10-30 second latency, and the need for credentials. 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 two sentences plus an example, with no wasted words. The first sentence immediately conveys purpose, and the second adds latency and credential info. Well-structured and front-loaded.

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 3 parameters and no output schema, the description covers inputs, latency, credential format, and usage example. It lacks output format details, but annotations imply safe read behavior. Adequate for a simple tool.

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

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

Schema coverage is 100%, but the description adds an example call and explains the _apiKey format ('username:password'), which is not in the schema. This provides practical guidance beyond schema definitions.

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

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

The description clearly states the verb 'fetch' and resource 'structured Amazon product data by ASIN', listing specific output fields (title, price, etc.). It distinguishes from sibling tools like oxylabs_google_search and oxylabs_scrape by focusing on Amazon product data.

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

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

The description provides clear usage context: synchronous, 10-30 second latency, requires API key, and includes an example. It does not explicitly state when not to use or compare to alternatives, but the context is sufficient for typical 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 read-only, idempotent, non-destructive behavior. The description adds beyond annotations by disclosing synchronous nature and expected latency (10-30 seconds), which is valuable for agent planning. 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 concise (3 sentences) yet packs essential information: purpose, output format, performance, authentication, and an example. Front-loaded with the core action.

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 no output schema, the description adequately explains return value structure (position, title, url, description). It covers behavior, auth, performance, and provides an example, making it self-contained for agent usage.

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% (all parameters have descriptions). The description adds minor extra context (e.g., free trial includes up to 2K results) but does not significantly enhance parameter understanding beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool runs a Google search via Oxylabs API and returns structured organic results. It specifies key details like output fields (position, title, url, description) and geo-targeting, distinguishing it from siblings like oxylabs_amazon_product or oxylabs_scrape.

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 usage context: synchronous proxying, 10-30 second latency, API key format, and example. However, it does not explicitly state when to prefer this tool over siblings or provide when-not guidance.

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

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

Discloses synchronous proxying, timing (10-30s), and authentication method. Annotations already indicate readOnly, idempotent, openWorld, non-destructive; description adds useful behavioral details beyond that.

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

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

Four sentences, front-loaded with purpose, then key features, timing, auth, and example. No redundant information; every sentence contributes 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?

Covers purpose, usage, timing, auth, and example. With no output schema, it describes the return (HTML+status). Could mention error handling or rate limits but overall sufficient given 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%. Description adds meaning: absolute URL, credentials format with dashboard link and trial info, render_js explanation, geo_location as optional proxy origin. Includes a concrete example.

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 scrapes any URL via the Oxylabs Web Scraper API and returns HTML with status code. It differentiates from sibling tools like oxylabs_amazon_product and oxylabs_google_search which are specialized.

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 context on when to use render_js (for JS-heavy sites) and mentions synchronous nature with 10-30s timing. Does not explicitly state when not to use, but the example and context are clear.

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

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

The description adds behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily, and signal directly affects roadmap. Annotations only indicate non-read-only and non-destructive, so the description provides rich additional transparency.

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 about 90 words, highly informative, and well-structured. Every sentence adds value, covering purpose, use cases, guidelines, and traits without any 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?

Given the tool has 3 parameters, no output schema, and annotations are present, the description is complete. It covers what the tool does, when to use it, how to format the feedback, constraints (rate limit, free), and context about team processing. An AI agent can correctly select and invoke this tool based solely on the 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?

Schema coverage is 100% (all parameters described). The description adds guidance on how to write the message (be specific, 1-2 sentences typical, 2000 chars max) and explains the enum values further, adding value 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 is for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It specifies the exact use cases and distinguishes itself from siblings by being a feedback submission tool, not a data retrieval or action tool.

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

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

The description explicitly says when to use this tool (bug, feature/data_gap, praise) and provides explicit guidance on what not to do (don't paste the end-user's prompt). It also mentions the rate limit (5 per identifier per day) and that it's free and doesn't count against the tool-call quota.

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?

Description adds helpful context beyond annotations: mentions it's derived from CF analytics-engine, no PII, cached 5min-1h. No contradiction with annotations.

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

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

Description is concise, front-loaded with purpose, then use cases in a list, then additional notes. 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?

Given low complexity, description covers input, use cases, and behavioral notes. Lacks detail on output format, but sufficient for the simple return type.

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 describes the window parameter with enum and explanation. Description reinforces by explaining implications of shorter vs longer windows, adding 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?

The description clearly states it returns top tools, packs, and call volume over recent windows. It distinguishes itself from siblings like 'discover_tools' by focusing on what other agents are calling, providing a specific verb and resource.

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

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

Three explicit use cases are given, such as discovering hot data sources and confirming canonical tools. Window selection guidance is provided, but no direct when-not-to-use or comparison with siblings.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral details: walking child markets, computing partition checks, applying Jaccard similarity, filtering placeholders, and performing fill checks against CLOB depth. 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 long but well-organized with sections for each mode and additional details like semantic anchor, partition filter, and fill check. Every sentence adds value, though slight condensation could improve conciseness.

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 compensates thoroughly by detailing the response structure (opportunities array with fields, partition_check object, fill check results). It also mentions error conditions (low similarity, placeholder filtering) and references related tools. 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 provides descriptions for both parameters (event and topic). The description adds significant meaning beyond the schema by explaining the mode behavior, example inputs, and what the tool does with each parameter. Schema coverage is 100%, so baseline is 3, but the added context justifies a 4.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no-args, event, topic) and specifies what each does, leaving no ambiguity about the tool's purpose.

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

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

Explicitly states when to use each mode: call with NO args for a trending scan, pass event for a specific market, pass topic for cross-event scanning. Also explains when not to trade (realizable_edge_pp ≤ 0) and references sibling tool polymarket_fill_risk for custom sizing. Differentiates from alternatives clearly.

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, idempotent, and non-destructive behavior; the description does not contradict. It adds useful context like 1h KV caching, 24h-move warnings, and output diagnostics, but annotations already cover the safety profile sufficiently.

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 highly detailed and structured with sections, but it is verbose. It front-loads the purpose and key output structure, but could be more concise to improve readability for an AI agent.

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

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

Given 9 parameters and no output schema, the description thoroughly explains the output structure (by_segment, _diagnostics) and why segments might be empty (filter_skips). It provides sufficient context for an agent to use the tool effectively.

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

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

Schema coverage is 100% for all 9 parameters, and the description adds extra context beyond field descriptions, such as slippage_pp explaining Polymarket fees and max_spread_pp suggesting values. This compensates well above the baseline.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and details the three model families. It distinguishes from sibling tools by specifying its unique focus on edge detection and output structure.

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 it's built for 'what should I bet on today' and explains tradeable-edge knobs like min_liquidity and max_spread_pp. It notes Fed bets are excluded from ranking but does not explicitly compare to sibling tools for when to use 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: reads from daily snapshots, TTL bound (60 days), decay from closes not intraday, and response structure. No contradiction.

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

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

The description is detailed but efficiently organized. It front-loads the core purpose and question answered, then explains parameters, response structure, and limits. Every sentence provides useful information, though slightly verbose.

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

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

For a time-series telemetry tool with no output schema, the description thoroughly explains the response: tracked[] with time-series, first_seen, trend, decay; expired[] with lifespan; snapshot_dates[]. It also covers limits (TTL, startup time, intraday vs. close). This is highly complete.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by specifying defaults (14 for days, '1wk' for window), clamping (2-30), and the meaning of window as 'snapshot family'. This enhances schema info.

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

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

The description explicitly defines the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It distinguishes from siblings like polymarket_edges by focusing on time-series and decay, not just current edges.

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

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

The description provides clear context on when to use: to assess edge history and decay, contrasting fresh vs. old edges. It does not explicitly name alternatives or when not to use, but the purpose is clear enough for an agent to decide.

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 behavior. The description adds rich behavioral context: details on the output fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk for basket), and warns about partial fills and directional risk. 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 effective but verbose (over 500 words). It front-loads purpose well, but the detailed output descriptions could be more structured (e.g., bullet points) or omitted if an output schema existed. Given no output schema, the verbosity is somewhat justified but still not concise.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It covers all input parameters, explains the calculation logic (walking the ladder, VWAP), lists all output fields for both modes, and provides practical context (why theoretical edge may not be capturable, the risk of partial fills). No gaps identified.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds significant meaning beyond schema, e.g., explaining that `size_usd` in basket mode is 'settlement notional S (shares per leg; each share pays $1)' and clarifying default side logic for basket mode. This enhances understanding of parameter behavior.

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 differentiates from siblings like polymarket_arbitrage and polymarket_edges by instructing when to use this tool before acting on those signals.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial basket fills create unhedged directional positions) and implies when not to use (small trades).

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, etc.), the description discloses critical behavioral aspects: compatibility_warning for non-equivalent bet shapes, temporal_alignment checks, and skipped counters for unmatched legs. It sets realistic expectations that spreads may be rare and provides safety fields for interpreting results.

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?

Despite its length, the description is well-structured and front-loaded. It begins with the core purpose, clearly separates modes, response format, and safety fields. Each sentence adds information without redundancy, making it efficient 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?

There is no output schema, so the description must explain the response, which it does thoroughly: it details leg-by-leg prices, matched spread with top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases like non-equivalent bet shapes and temporal mismatches, leaving no critical gaps.

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

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

The input schema already documents all three parameters with descriptions (100% coverage). The description adds value by explaining the interaction between topic and explicit parameters (override behavior) and listing the valid topic values. This provides context beyond the schema definitions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by specifying that it compares two platforms, while siblings like 'polymarket_arbitrage' likely focus on intra-venue strategies. The two modes (topic and explicit) and response structure are clearly outlined.

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 usage context, such as when to use topic shortcuts vs explicit pairing, and warns that pre-mapped topics often yield compatibility warnings. However, it does not explicitly compare this tool to alternatives like 'polymarket_arbitrage' or 'compare_entities'. The guidance is clear for the tool itself but lacks differentiation from siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the retrieval mechanism (from remember), listing behavior when key omitted, and scoping to identifier.

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 front-loaded sentences with zero wasted words. Each sentence earns its place: main action, use case, scoping and 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?

Complete for a simple read tool with one optional parameter and no output schema. Covers use cases, scoping, and sibling relationships.

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

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

Schema covers 100% of the one parameter. Description adds context that omitting the key lists all keys, complementing the schema description effectively.

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

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

Clearly states it retrieves a saved value or lists all keys. Distinguishes from siblings 'remember' and 'forget' by naming them and describing the pairing relationship.

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 describes when to use (look up stored context) and pairs with remember/forget. Lacks an explicit 'when not to use' but the context is well implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds valuable behavioral detail (returned fields, mark_read effect, polling suitability) 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?

Every sentence adds distinct value—purpose, return fields, filtering, read-state flagging, and alternative access. No fluff, well-structured.

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

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

No output schema, but description adequately explains what is returned (source, citation_uri, raw payload) and covers all key behaviors. Combined with rich annotations, it provides a complete picture for an agent.

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 individual parameter descriptions. The description adds meaningful context (e.g., 'Filter by type (e.g. 'sec_8k') and/or since (ISO timestamp)') beyond the schema, though not all params are explicitly mentioned.

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 'Pull fired events from your subscription feed' and specifies what each alert carries, distinguishing it from sibling tools like 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?

Provides usage context (e.g., 'Polls work fine; the same feed is also at...') and hints about when to use parameters like mark_read, but does not explicitly contrast with alternatives.

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

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

The description adds detailed behavioral context beyond annotations, including fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback mechanisms, and known limitations (USPTO PatentsView API sunset). Annotations already indicate readOnly and idempotent, which are 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 slightly lengthy but well-structured with examples up front, clear separation of sources, and a concise recommendation for alternative tool. Every sentence adds value, though could be trimmed slightly without loss.

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

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

Given the tool's complexity (multiple data sources, fallback logic), the description fully covers what the tool does, how it behaves, what it returns (structured changes grouped by source), and relevant limitations. No output schema exists, but description compensates adequately.

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

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

Schema coverage is 100%, but the description adds useful details like accepted formats for 'since' (ISO date or relative shorthand) and value formats (ticker or padded CIK). Examples and recommendations enhance 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 returns a change feed for a company over a time window, with specific examples like 'What's new with X' and explicitly distinguishes from sibling 'entity_profile' which provides a static profile.

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

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

Provides explicit guidance on when to use this tool vs 'entity_profile', and includes recommendations for parameter values such as 'Use "30d" or "1m" for typical monitoring.'

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

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

Beyond annotations (idempotent, not destructive), the description adds critical behavioral details: scoped by identifier, persistence depends on authentication, and 24-hour TTL for anonymous sessions. No contradiction with annotations.

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

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

Description is four sentences, each adding value, but could be slightly more concise. Well-structured with purpose first.

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 two params and no output schema, the description covers all necessary context: behavior, scope, persistence, lifetime, and pairing with siblings.

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 usage examples for keys but does not enhance parameter meaning beyond schema. Adequate but not exceptional.

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: 'Save data the agent will need to reuse later.' It uses a specific verb and resource, and distinguishes itself from sibling tools like recall and forget.

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

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

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also mentions context (session vs persistent) and pairs with recall/forget as 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds that the tool cascades through multiple internal lookup endpoints, providing extra context beyond annotations. No contradictions.

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

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

The description is well-structured with examples and clear usage guidance. While somewhat lengthy, every sentence adds value, including return details and internal behavior.

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

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

Despite no output schema, the description fully explains return values and citation URIs for both entity types. It covers all necessary context for an 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%. The description adds meaning by specifying what is returned for each entity type (e.g., ticker + CIK + URI for company, RxCUI + ingredient + brand + URI for drug), going beyond the schema's parameter descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples (ticker, CIK, RxCUI) and supported types. It distinguishes itself from siblings by noting it replaces 2-3 manual 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 says 'Use FIRST whenever you have a name but need an ID.' It details supported entity types and input formats, but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already declare read-only, idempotent, open-world. Description adds behavioral context: probes each entity with ai_visibility_check, ranks by score, surfaces extremes. Output fields specified. No contradiction.

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

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

Three concise sentences: core action, then process detail, then use case. No redundant words. Front-loaded with main 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?

Covers core behavior, input constraints (2-8 entities), output fields. No output schema but description lists return info. Missing details on error handling (e.g., probe failures), but sufficient given annotations and param coverage.

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

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

Schema coverage is 100%, but description adds critical semantics: 'First entry treated as subject for narrative' for entities, and 'Omit for just workers-ai' for models. This clarifies ordering and default behavior 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 uses specific verb 'compare' and resource 'AI visibility across multiple entities'. It distinguishes from sibling 'ai_visibility_check' by focusing on side-by-side comparison and ranking. Concrete use case and output described.

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?

Clearly states usage for competitive AI-marketing audits with example. Implicitly contrasts with single-entity probe (ai_visibility_check). No explicit when-not-to-use or alternative sibling comparisons, but context is strong.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and lists sources_failed in case of timeout. No contradiction with annotations.

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

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

Description is front-loaded with the main purpose and then provides detailed behavior and return structure. Though long, every sentence adds value. Minor redundancy with schema descriptions.

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 specifies the return format: summary block fields, per-advisory detail, links, and alternative versions. Also covers error handling and partial failures, making it complete for an agent.

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% description coverage for both parameters. The description repeats that version defaults to latest and accepts scoped packages, but does not add new information beyond what is already 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?

Description clearly states it's a composite check for npm packages, using specific verbs ('scan' and 'check') and identifies the resource ('npm package'). It distinguishes from siblings by specifying the scope (NPM only) and integration of multiple sources.

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 use cases: 'when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also clarifies scope limitations (NPM only in v1) and directs other ecosystems to a different tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds concrete implementation: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. 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?

Four sentences densely packed with useful information. No fluff, but could be slightly more streamlined without losing content.

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 explains return format: 'top-N passages with character offsets and similarity scores'. Mentions cap and truncation. Adequate for a straightforward search 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% with descriptions. Description adds context: 'Pass the text you already pulled... plus a natural-language query', explains limit default and purpose. Adds 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 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). Distinguishes from siblings like ask_pipeworx_grounded by explaining pairing strategy.

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

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

Explicit when-to-use: 'Use when the record is too big to cram into the prompt'. Provides alternatives and pairing advice: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'.

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 important behaviors beyond annotations: requires OAuth account, defines supported types with specific parameters, delivery channels with restrictions (phone verification, SMS cap, webhook auto-disable). No contradiction with annotations (readOnlyHint=false, idempotentHint=true).

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?

Reasonably concise and structured; front-loaded with main purpose. Could be slightly more compact but includes necessary details without excessive verbosity.

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 authentication, types, parameters, delivery channels, and the return value (subscription id). No output schema, but the return is simple. Missing details on exact response structure, but adequate for a creation 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?

Description adds significant value beyond the input schema. Provides concrete examples for each type and delivery channel, and clarifies constraints like phone verification and webhook signing. Schema coverage is 100% but descriptions are minimal; the description compensates well.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb ('Create') and resource ('subscription'), distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides good context on when to use, including authentication requirements (Pipeworx OAuth account) and examples for each type. Does not explicitly exclude scenarios but implies this is for creating subscriptions, not listing or unsubscribing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the return format (category-bucketed examples with tool shapes) but doesn't contradict 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 synonyms, purpose, output description, and usage guidance. Every sentence adds value, though it is somewhat verbose.

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

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

Given the tool's role as an onboarding entry point, the description fully covers its purpose, usage, parameter behavior, and output format, despite lacking 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% but the description adds significant value by listing concrete topics (finance, pharma, etc.) and explaining the effect of passsing a topic versus omitting it.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, and distinguishes it as the onboarding entry point for when the agent doesn't know what Pipeworx can do.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains the optional topic parameter and provides examples of when to omit it.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent. The description adds context: ownership constraint, deactivation behavior, and preservation of historical events. No contradictions.

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

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

Three sentences, each essential. Action, constraint, and effect are front-loaded. No filler or redundancy.

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

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

The description covers purpose, constraint, and effect. It does not describe the return value, but the tool is simple and the effect is adequately explained. Siblings provide context.

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

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

Schema covers the parameter fully ('Subscription id (uuid) returned by subscribe'). The description adds no additional semantic value 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 action ('Cancel a subscription by id') and the resource (subscription). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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?

Ownership enforcement is explicitly stated, indicating that only the owner can cancel. It also explains the effect (deactivation, not deletion), but does not explicitly state when not to use or provide direct 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds significant detail: the two processing paths, use of exact percent-delta math for financial claims, output structure (verdict, actual value with citation, reasoning), and the fallback behavior. 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 fairly long but front-loaded with the core purpose and examples. It is structured with clear sections for the two paths. Every sentence contributes useful information, and it avoids redundancy. Could be slightly more concise, but the detail is justified for a complex 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?

Despite no output schema, the description fully explains the return format (verdict types, actual value with citation, reasoning). It covers the tool's behavior for both company financial claims and other factual claims. With only 2 parameters and comprehensive annotations, the description is complete and leaves no critical gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples for 'claim' and explaining the purpose of 'tolerance_pct' with suggested usage (1-2 for hallucination detection). This goes beyond the schema alone.

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

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

The description clearly states the tool is for claim verification and fact-checking, with specific verb phrases like 'validate the claim' and examples. It distinguishes from siblings by mentioning it replaces multiple sequential calls and has specialized paths for company financial claims vs other factual claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two internal paths (SEC EDGAR for financial claims, grounded pipeline for others). While it doesn't give explicit 'when not to use' statements, the context is clear and helps the agent decide.

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