Decodo

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, no destructiveness. Description adds cost implications (free default, BYO Anthropic), return structure (per-model {score, confidence, signals, raw_response} + combined view), and API key passthrough. 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?

One paragraph, front-loaded with purpose and key details. Efficient but could use bullet points for return structure; still clear and 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?

No output schema, but description explicitly lists return fields (per-model + combined view). Covers entity, models, auth (API key), optional context. No missing information for a probing/scoring 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 good descriptions. Description adds value: default model, when _apiKey is needed, context disambiguation purpose. Enhances schema without redundancy.

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?

Clear verb 'probe' and resource 'LLMs' with specific purpose: score visibility for businesses/brands/products/topics. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on direct LLM probing and scoring.

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

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

Explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Default model and optional API key explained. No explicit when-not-to-use or alternatives, but context is sufficient.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. This goes beyond annotations to disclose output format and performance characteristics.

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

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

The description is relatively long but well-structured with a clear hierarchy: directive, domain list, examples, alternatives. Every sentence adds value, though a slight reduction in length 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 adequately covers input format, usage context, data sources, and result format (structured with citations). It lacks details on error handling or rate limits but is sufficiently complete for most use cases.

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

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

Schema coverage is 100%, with all parameters describing aliases for the 'question' field. The description adds value by providing diverse example queries and clarifying that natural language is accepted, which supplements the schema's alias list.

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

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

The description clearly states that the tool routes questions to over 5,000 tools across 1,319 sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

Explicitly advocates preferring over web search, provides extensive examples (SEC filings, FDA data, stocks, etc.), and gives clear instructions on when to use alternatives (grounded for confidence, deep_research for multi-part questions, and notes on breaking news). This offers comprehensive usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds value by explaining the source-preference ranking, experimental nature, and that it's a full working router, without contradicting 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 core purpose and is structured to convey the beta nature, routing improvement, and usage guidance. Slightly verbose but each sentence adds necessary context.

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

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

Given the tool's complexity, the description covers what it does, how it differs from the stable version, how to use it, and its fallback behavior. No output schema needed as it references the same response shape as ask_pipeworx.

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

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

Schema description coverage is 100%, and the description merely reiterates that the tool uses the same arguments as ask_pipeworx. No additional semantic information beyond the schema, meeting 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?

Clearly states it's a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. Distinguishes from sibling ask_pipeworx (stable version) by highlighting the experimental edge and source-preference ranking.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. Also clarifies fallback: 'Falls back to nothing — this IS a full working router.'

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral details beyond annotations: costs one extra LLM call, performs extraction, returns explicit refusal reasons. 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 sentences plus return format. Front-loaded with purpose, then mechanism, then usage guidelines. Slightly verbose but efficient. Every sentence adds value. Could be slightly tighter but good.

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

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

Given the complexity (5K+ tools, high-stakes use), the description covers purpose, mechanism, use cases, cost tradeoffs, and refusal reasons. No output schema but return format is described inline. Complete.

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

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

Schema coverage is 100%, each parameter already has description (e.g., 'Alias for question'). The description mentions aliases but doesn't add new semantic meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes from ask_pipeworx by explaining that it extracts answers using only tool results and returns explicit refusals. The verb 'extracts' and resource 'answer from tool result' are specific.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'the agent must not invent facts.' Also provides alternative: 'prefer ask_pipeworx for casual lookups.' Clear when-to-use and when-not.

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 richly discloses behavioral traits: fan-out logic, resolver contract details, parent event extraction, news fallbacks, low-confidence shorts, closed market handling, wide spread notes, and resolution rule risk. This far exceeds what annotations provide and adds critical context for correct tool invocation.

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

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

The description is thorough but very long (multiple paragraphs). While it is well-structured with clear sections and examples, it could be more concise. The core purpose and key usage are front-loaded, but the extensive detail may overwhelm an agent. It balances completeness with a need for brevity.

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

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

Given the tool's complexity and lack of output schema, the description covers the response shape (result.market, result.analysis, result.evidence), resolver contract, parent event extraction, news fields, and safety mechanisms. It is comprehensive but could still be more exhaustive (e.g., exact field names in analysis). Overall, it provides sufficient context for most use cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant value by explaining the depth parameter with 'quick' vs 'thorough' semantics, the include_raw parameter with payload size implications, and the market parameter with examples of multiple input formats. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and lists classifiers and fan-out examples, making it distinct from sibling tools that are more specific (e.g., polymarket_edges) or general (ask_pipeworx).

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

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

The description explicitly states when to use the tool: 'Use for...' and provides scenarios. It also includes safety information (low-confidence resolutions, closed markets, wide spreads) that imply when not to rely on results. However, it does not explicitly mention alternatives or when to avoid this tool in favor of a sibling, so it is slightly lacking in exclusions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant behavioral context: it pulls from SEC EDGAR/XBRL for companies (with off-calendar fiscal year handling), FAERS/FDA for drugs, sorts results by primary metric, and provides citation URIs. No contradictions.

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

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

The description is front-loaded with user queries and is fairly concise. Every sentence adds value, though some redundancy exists (e.g., repeating the entity count). It could be slightly tightened but is generally 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 the tool's complexity and lack of output schema, the description covers entity types, data sources, sorting, and citation URIs. It could detail the output format more, but the 'paired data' and sorting info suffice for an agent to understand what to expect.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description adds meaning by explaining what data is pulled for each 'type' value and giving examples for 'values' (tickers/CIKs for companies, drug names). This complements the schema 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 performs side-by-side comparison of 2-5 companies or drugs. It specifies verbs like 'compare', 'rank', 'head to head', and explicitly differentiates from siblings by saying 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description provides explicit trigger phrases ('compare X and Y', 'X vs Y', etc.) and guidance to prefer this tool over sequential lookups. However, it does not explicitly state when not to use this tool, though the context implies it's only for side-by-side comparisons.

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 JSON output format, required API key (BYOK), and that it parses specific fields, which is valuable 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 plus an example. Front-loaded with the core purpose, then parameter details. No wasted words; every sentence adds value.

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

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

No output schema exists, but the description mentions the key fields (title, pricing, rating, etc.) and that the output is JSON. With annotations covering idempotency and read-only, it provides adequate completeness 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%, so baseline is 3. The description adds an example and clarifies relationships (url vs asin), and explains the _apiKey credential format, providing additional meaning.

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

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

The description clearly states 'Get structured Amazon product data' with a specific verb and resource. It distinguishes itself from sibling tools like decodo_scrape and decodo_google_search by focusing on Amazon products and parsing specific fields.

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

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

Provides clear context on when to use (for Amazon product data) and how to pass parameters (URL or ASIN). Does not explicitly exclude alternatives but gives sufficient guidance for correct invocation.

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 valuable behavioral context: rotating proxies, returns structured results including related searches, and BYOK requirement. 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?

One efficient paragraph, front-loaded with purpose. Every sentence adds value, including the example. No redundancy or fluff.

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

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

Adequately covers return structure (position, title, url, snippet), authentication, and geotargeting. Lacks mention of error cases or rate limits, but given annotations and schema richness, it's mostly complete.

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

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

Schema coverage is 100% so baseline is 3. Description adds value by explaining the _apiKey format as 'username:password' and providing an example call, which clarifies usage beyond the schema.

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

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

Clearly states verb 'scrapes' and 'runs a Google search', resource 'Google search results', and returns structured organic results with position, title, url, snippet. Distinguishes from siblings like decodo_amazon_product and decodo_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?

Provides example and explains authentication, but does not explicitly state when to use this tool versus alternatives like decodo_scrape or other search tools. No when-not-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations: rotating proxies, anti-bot handling, headless browser rendering, and BYOK credential requirement. 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?

Two well-structured sentences plus an example. Each sentence adds essential information, and the most important details are 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?

The description covers main functionality and return options (HTML vs markdown). While no output schema exists, it explains content type. Minor gap: no mention of error handling or rate limits, but acceptable for a scraping tool.

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

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

Schema coverage is 100%, but the description adds value by explaining the format of _apiKey, the effect of render_js and markdown, and providing an example. This goes beyond the schema properties.

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 (scrape), resource (web page), and method (via Decodo rotating proxies). It distinguishes from sibling tools like decodo_amazon_product and decodo_google_search, which are site-specific.

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 guidance on when to use render_js:true for JavaScript-heavy sites and markdown:true for LLM-ready content. However, it does not explicitly state when not to use this tool or suggest alternatives like the site-specific 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 show readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds account requirement, not open-web search, returns gaps[] and contradictions[], hop field, citation_uri, and expected latency. 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 lengthy but dense with useful information. Front-loaded with critical account requirement and alternative. Every sentence contributes, though could be more structured with bullet points for readability.

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

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

Given the complexity (2 params, no output schema), the description fully explains the process, limitations, return fields (findings packet with evidence, confidence, source, etc.), and latency. No gaps.

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

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

Schema has 100% coverage. Description adds meaning: explains depth options (quick=3, standard=5, thorough=8) and that question can be broad/multi-part. 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?

The description states 'Grounded multi-source research across Pipeworx's 1319 STRUCTURED data sources' and 'Decomposes your question into focused facets...returns a findings packet'. It explicitly distinguishes from sibling tools like ask_pipeworx and advises 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: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', 'If you are not signed in, use ask_pipeworx instead'. Also explains depth levels and second-hop iteration.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: returns top-N most relevant tools with schemas ready to call, no second lookup needed. No contradictions with annotations.

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

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

The description is three concise sentences with clear structure: purpose, use-case with domain examples, and output details with action guidance. Every sentence adds value and is 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?

Given the tool's discovery role, safe annotations, and full schema, the description is complete. It explains output format (names, descriptions, schemas) and usage timing. No missing necessary 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 coverage is 100%, so baseline is 3. The description mentions 'natural language description' for the query and lists many example domains, but it does not add significant detail beyond the schema's parameter descriptions and aliases.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the domains covered (SEC filings, financials, etc.) and what is returned (names, descriptions, schemas). This distinguishes it from sibling tools that perform specific tasks.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available...' This guides the agent to use discovery before domain-specific tools, but it does not name specific sibling 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 indicate read-only, open-world, idempotent, non-destructive. Description adds specifics: fans out across sources, returns filings with URIs, sorted fundamentals, patent sunset note, news fallback, LEI. No contradictions.

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

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

Description is a single dense paragraph with example queries. Efficient but slightly packed; could be split for clarity, but no waste.

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

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

No output schema, so description must detail returns. It lists specific fields and data sources, mentions limitations and fallbacks. Comprehensive for a multi-source profile tool.

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

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

Schema coverage is 100%; description reinforces value parameter (ticker/CIK, not names) and adds note that type only supports 'company' with future plans. 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 the tool provides a holistic company profile from multiple sources, with specific verb examples like 'profile' and 'research'. It distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack' lookups, gives example queries, and advises using resolve_entity if only a name is available.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. Description adds context about deleting by key and clearing sensitive data, enhancing transparency without contradiction.

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

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

Two focused sentences: first defines action, second gives usage context. No superfluous information, well-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 one required parameter, no output schema, and annotations covering safety, the description is sufficient. It mentions sibling tools, completing the 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 single parameter 'key' with description. Description mentions 'by key' but adds no new meaning beyond schema. Baseline 3 due to high coverage.

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

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

Clearly states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings by mentioning pairing with '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?

Provides explicit when-to-use conditions (stale context, task done, clear sensitive data) and mentions pairing with related tools. Lacks explicit when-not-to-use, but guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which is helpful behavioral context. However, it does not disclose potential limitations (e.g., handling of dynamic content, robots.txt, or paywalls) that could affect usage.

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, clear paragraph that front-loads the purpose. At ~80 words, it is relatively concise and free of fluff, though it could be slightly more terse without losing meaning.

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

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

Given the tool's simplicity (2 parameters, no output schema, and strong annotations), the description adequately explains the output format ('single text blob ready to drop at site-root/llms.txt') and usage scenarios. It could mention error handling (e.g., unreachable URLs) but is otherwise 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 description coverage is 100%, so the schema already fully documents both parameters. The description mentions 'Full URL' for the url parameter and 'default 25, max 50' for max_links, but these are already in the schema description. Thus, the description adds no new parameter-level information 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 generates a 'production-ready llms.txt file' for any URL, specifying the action (generate), resource (llms.txt), and value proposition. It distinguishes itself from sibling tools like decodo_scrape or scan_competitor_ai_presence by focusing specifically on llms.txt generation.

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

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

The description provides explicit usage examples ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context on when to use it. It does not mention when not to use or explicitly compare to alternatives, but the context is sufficient for most agents.

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 return fields beyond annotations ('Returns id, type, params, created_at, last_fired_at, fire_count for each'); annotations already confirm read-only, idempotent, non-destructive behavior, so description adds valuable detail.

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 with no wasted words: purpose first, then returned fields, then usage guidance; highly efficient and scannable.

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 list tool with one optional parameter and no output schema: describes what it returns, when to use, and accounts for the sole parameter via 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 coverage is 100% with parameter description already clear; tool description does not add extra meaning beyond what the schema provides, meeting 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly says use this 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to invoke, though no direct exclusions or alternative tool mentions.

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?

Adds rate limit (5 per identifier per day) and free quota hint, which extends 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?

Five sentences with no waste, front-loaded with purpose, and structured to guide usage.

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

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

Covers all necessary aspects for a feedback tool: when to use, constraints (rate, quota), and how to write feedback. No output schema needed.

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 reinforces enum meanings and message formatting but doesn't materially add 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?

States verb 'Tell' and resource 'the Pipeworx team', specifies feedback types (broken, missing, praise), and clearly distinguishes from sibling tools (research-oriented).

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 when to use (bug, feature, data_gap, praise) and what not to do (don't paste user prompt), though no direct alternatives mentioned.

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 self-aggregating signal, no PII, caching behavior (5min-1h), and notes that it derives from CF analytics-engine. Adds value beyond readOnlyHint and other annotations.

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

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

Well-structured with front-loaded summary, but could be slightly more concise. However, every sentence provides value, so no major waste.

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

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

Fully covers caching, PII, use cases, and return values despite no output schema. Complete for a simple tool.

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

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

Adds meaningful nuance to the single parameter by explaining trade-offs between short and long windows, beyond the schema's enum 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?

Clearly states it returns top tools, top packs, and total call volume over a window. The specific verb 'calling' and resource 'Pipeworx' with distinction from sibling tools makes it unambiguous.

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

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

Provides three explicit use cases with context (discovery, confirmation, alignment), but lacks explicit when-not-to-use or alternatives. Still strong guidance.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: scans top ~200 markets, walks child markets, checks ordering, computes partition sum, filters placeholders, includes fill check via CLOB depth, and warns 'do not trade it' if realizable edge ≤0. No contradiction with annotations.

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

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

The description is detailed and well-structured with paragraphs and bold labels, front-loading the purpose. It is long but each section adds necessary value for a complex arbitrage tool. Minor redundancy could be trimmed.

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

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

Despite no output schema, the description fully details the response shape: opportunities array with fields and partition_check object in event mode. It covers fill check logic. Missing error handling or rate limits, but given complexity, it is quite complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant context beyond the schema, such as 'event' accepting full URLs and 'topic' accepting seed questions. It explains the modes in detail, justifying above baseline 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and explains each, setting it apart from sibling tools like polymarket_edges and polymarket_fill_risk.

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 for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains why to use cross-event mode ('catches ... patterns that single-event misses'), but does not explicitly state when not to use the tool.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds extensive behavioral details: caching at KV level (1h), edge calculation methodology, response structure with diagnostics, and limitations for Fed bets. 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 efficiently packed with valuable information. It is front-loaded with purpose and structured by segments and knobs. Every sentence adds unique value given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), caching, edge calculations, and all parameter effects. It also notes unreliable Fed signals, making it highly complete for agent use.

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

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

Schema covers all 9 parameters with descriptions. The description adds substantial context for each, explaining tradeable-edge knobs, Kelly filters, and best practices (e.g., slippage_pp default 0.3). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically for daily bet discovery. It distinguishes from sibling tools like polymarket_arbitrage by focusing on multiple model families and edge detection.

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

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

The description positions the tool for 'what should I bet on today' and explains the segments and knobs, providing clear context. However, it does not explicitly mention alternatives or when not to use this tool versus others like polymarket_fill_risk.

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

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

The description adds significant behavioral context beyond annotations, explaining data source (daily snapshots), computation of trend and decay, handling of expired opportunities, and limitations (snapshot gaps, TTL, decay based on daily closes). No contradiction with annotations.

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

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

The description is well-structured with front-loaded purpose, parameter details, response structure, and limitations. It is somewhat lengthy but each sentence adds value.

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

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

Given no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) with detailed fields. It also covers limitations and parameters, making the tool completely understandable.

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

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

Schema coverage is 100%, but the description adds value by explaining the role of 'window' as 'snapshot family' and clarifying the clamp for 'days'. The description provides context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tool polymarket_edges by focusing on time-series analysis and decay.

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 for when to use the tool (to analyze edge persistence and decay) and notes limitations such as 60-day TTL and snapshot gaps. However, it does not explicitly state when not to use it or provide alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail: it walks the order book ladder, returns specific fields like slippage and fill quality, and highlights forced 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 dense but well-structured with clear section headers for SINGLE-MARKET and BASKET. It covers all necessary details without redundancy, though it is somewhat lengthy. Every sentence adds value, but brevity could be improved for an agent parsing time.

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

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

Despite no output schema, the description thoroughly enumerates all return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. Also explains risks and failure modes, making it complete.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds value beyond the schema by explaining default behaviors (side auto-detection for basket, interpretation of size_usd in single vs basket modes), and notes clamping range (10–1,000,000). This additional context justifies a score above baseline 3.

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

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

The description clearly identifies the tool as an edge check against live order book depth for Polymarket. It distinguishes between single-market and basket modes with detailed explanations, and explicitly tells the agent to use this before acting on polymarket_arbitrage or polymarket_edges signals, differentiating from sibling tools.

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

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

Provides explicit when-to-use guidance: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. Also explains when not to rely on theoretical overround and warns about partial fills converting arb into unhedged positions. Clear usage context.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully disclosed. The description adds rich behavioral details: response structure (leg-by-leg prices, spread, compatibility_warning), temporal alignment, skipped counters, and caveats like 'pre-mapped ≠ tradeable.' No contradiction with annotations.

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

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

The description is moderately long but well-structured with bold topic headers and clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value. Minor improvement would be to tighten some redundant caveats.

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 explains the response structure, safety fields, and edge cases. It covers temporal alignment, compatibility warnings, and skipped cross types. All three parameters are explained with examples. The description is fully self-contained.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining the two usage modes and providing example valid topics. While schema already covers each parameter's meaning, the description enriches it with real-world usage context.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons. The two modes (topic and explicit) further specify its scope.

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

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

The description explains when to use (comparing prices across venues for the same question) and provides explicit conditions when spreads are meaningless (compatibility_warning, temporal_alignment). It does not directly contrast with sibling tools but the usage context is clear. Lacks a clear 'when not to use' statement but the warnings serve that purpose.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds scoping detail (by identifier) and confirms read behavior. No contradictions.

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

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

Two sentences, front-loaded with core purpose, then context. No wasted words. Efficient and well-structured.

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

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

Simple tool with one optional param and no output schema. Description covers retrieval, listing, scoping, and companion tools. Slight lack of return format info, but not critical.

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

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

Schema coverage is 100% and describes the key parameter. Description reiterates omitting key lists all keys, but adds no new parameter-level 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?

Description clearly states the tool retrieves values saved via 'remember' or lists keys when omitted. It uses specific verbs (retrieve, list) and distinguishes from siblings like 'remember' and 'forget'.

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

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

Provides explicit usage context: look up stored context without re-deriving. Mentions pairing with 'remember' and 'forget'. Lacks explicit when-not-to-use but sufficient for a simple 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, idempotent, non-destructive. Description adds useful context: mark_read behavior for marking events read, and mention that polling works fine.

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, no wasted words, front-loaded purpose. Every sentence adds value.

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

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

All 5 parameters are described with behavior and constraints. Return fields are outlined. No output schema needed for this simple read operation.

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

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

Schema coverage is 100%, but description adds meaning: explains filtering by type and since, and the effect of mark_read. Exceeds baseline 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 clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies the verb and resource but doesn't explicitly differentiate from sibling tools.

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

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

Implied usage: polling works, and the feed is also available via URL for scripts/dashboards. No direct comparison with alternatives like list_subscriptions or search_within.

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 hints. Description adds detailed behavioral context: multiple-source fan-out, GDELT→GNews fallback logic, USPTO soft-fail, return structure with grouped changes, total count, and citation URIs. No contradictions.

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

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

Single paragraph is information-dense but front-loaded with examples. Minor improvement possible with bullet points, but no wasted sentences. Every sentence adds value.

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

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

Despite no output schema, description fully explains return structure (changes grouped by source, total_changes, URIs). Covers all sources, fallbacks, and error handling (soft-fail). Sufficient for an AI agent to understand input, behavior, and output.

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 significant value: explains 'since' ISO/relative shorthand with examples, clarifies 'type' enum limitation, and provides ticker/CIK examples for 'value'. Goes beyond schema 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?

Description uses specific verbs ('fans out to', 'returns') and identifies exact resources (SEC EDGAR, GDELT, GNews, USPTO). Differentiates from sibling 'entity_profile' by contrasting use cases. Example queries clearly convey 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?

Clearly states when to use (latest news/changes for a company) and contrasts with 'entity_profile'. Provides explicit guidance on input format (since shorthand). Could improve by stating when NOT to use, but sibling distinction serves that function.

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 idempotentHint=true and destructiveHint=false. The description adds scoping by identifier, 24-hour retention for anonymous, and that data persists across sessions for authenticated users, which goes 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 main purpose, then details. Slightly long but each sentence adds value. Could be tightened but effective.

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

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

For a simple KV store, it covers all needed context: purpose, usage, parameter semantics, persistence, and relations to siblings. No output schema needed.

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 both parameters with descriptions. Description adds naming conventions ('subject_property', 'target_ticker') and notes value can be any text, providing useful examples 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 stores data for reuse, with specific examples like ticker, address, preference. It differentiates from siblings recall and forget by mentioning them, giving a clear 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 says when to use ('when you discover something worth carrying forward'), provides persistence details for authenticated vs anonymous, and instructs to pair with recall/forget for retrieval/deletion.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds that each call cascades through several lookup endpoints internally and auto-disambiguates input, which are useful behavioral details beyond the annotations.

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

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

The description is well-structured, starting with query examples and then detailing supported types and their outputs. It is moderately sized and every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description completely covers return values (ticker, CIK, company name; RxCUI, ingredient, brand) and includes citation URIs. It also explains the tool's role in reducing manual lookups, making it fully informative 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%, but the description adds valuable context: for 'company' type, value can be ticker, CIK, or name; for 'drug', brand or generic name. It also explains the output format (ticker+CIK+name, RxCUI+ingredient+brand), enhancing parameter meaning.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to a canonical/official identifier. It provides specific examples (ticker, CIK, RxCUI) and distinguishes its scope from other tools by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear context for when to use this tool. It also explains that it replaces 2-3 manual lookups, but does not explicitly state when not to use it or mention alternatives.

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

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

The description details the return format (ranked list with score, confidence, signal density) and the process (probes each entity with ai_visibility_check). This adds significant context beyond annotations, which already indicate read-only, idempotent, non-destructive behavior. 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 front-load the purpose, explain mechanics, and give a concrete use case. Every sentence adds value without redundancy. Efficient and well-structured.

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

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

Given the moderate complexity (4 parameters, composite behavior) and no output schema, the description fully explains what the tool does, how it works, and what it returns (ranked list with metrics). Sufficient for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning by explaining the 'entities' array ordering (first entry is subject) and providing examples for 'context'. This enriches understanding 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 compares AI visibility across multiple entities, using specific verbs ('Compare', 'Probes') and resources ('AI visibility'). It distinguishes itself from sibling tool 'ai_visibility_check' by performing a comparative, aggregated analysis.

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

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

The description explicitly recommends use for competitive AI-marketing audits, and implies when to use this over alternatives by noting it probes each entity with ai_visibility_check. It could be stronger by explicitly stating when not to use (e.g., single entity analysis).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: composite behavior, partial failure handling, and potential latency for bundlephobia first measurement. No contradiction with annotations.

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

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

Description is a single paragraph but front-loads purpose and usage. Each sentence adds value, though it could be slightly more structured. Still clear and efficient.

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

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

Given 2 parameters, no output schema, but rich annotations, the description covers purpose, usage, behavioral traits, error handling, and return types completely. Leaves no significant gaps.

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

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

Schema coverage is 100%, so schema describes both parameters well. Description adds context like scoped packages accepted and defaulting to latest version, and implies meaning through usage examples.

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

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

The description states a specific verb ('scan') and resource ('dependency') with a clear goal: checking if an npm package should be added to a project. It distinguishes itself among siblings as the only npm package analysis 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?

Provides explicit when-to-use examples ('is X safe...', 'what does adding lodash cost me') and clearly states limitations ('NPM ecosystem only in v1') with an alternative mentioned for other ecosystems.

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?

Adds rich behavioral detail beyond annotations: embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and output details (character offsets, similarity scores). 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?

Concise 3-4 sentence description, front-loaded with purpose, then usage, then technical details. Every sentence contributes meaning without redundancy.

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

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

Given no output schema, the description adequately explains return values (top-N passages with character offsets and similarity scores) and covers cap/truncation behavior. Completely sufficient for agent invocation.

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

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

Schema coverage is 100% (all params described). Description adds examples for query, default for limit (5), and max chars for text, providing extra 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 states 'Semantic search INSIDE a fetched record' with specific verb and resource, and distinguishes from sibling ask_pipeworx_grounded by explaining how they pair.

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: 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, but no explicit exclusion of 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 indicate idempotentHint=true, readOnlyHint=false, etc. The description adds behavioral details: returns subscription id, phone verification requirement, 10 SMS/day cap, webhook auto-disable after 10 failures. However, it does not clarify idempotency behavior (e.g., whether duplicate calls create multiple subscriptions).

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: first sentence states purpose, then requirements, then supported types with examples, then delivery channels with constraints. Every sentence adds value without unnecessary 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 no output schema, the description adequately states return value (subscription id). It covers all key aspects: auth requirement, type-specific params, delivery options with constraints, and sibling tools context. Complete for a subscription 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?

Schema coverage is 100%, but the description adds significant value with concrete usage examples for each type (e.g., items:['5.02'] for sec_8k), detailed delivery channel options, and HMAC signing for webhooks—far 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?

The description clearly specifies the action (create a subscription), the resource (live-data event stream), and distinguishes from siblings like list_subscriptions, unsubscribe, recent_alerts by focusing on creation.

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 requires a Pipeworx OAuth account and notes that anonymous/BYO accounts cannot persist subscriptions. It implies usage for setting up proactive monitoring but could better contrast with one-off queries (e.g., ask_pipeworx) or pulling feeds (recent_alerts).

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 behavioral context: it returns category-bucketed example questions with tool shapes, and does not mention any destructive or side effects. 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?

Description is front-loaded with example queries and is detailed, but every sentence earns its place. Slightly long but still concise relative to 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 simple input schema and annotations, the description is complete: it explains purpose, usage, output (category-bucketed examples), and topic parameter. No output schema expected, but return value is sufficiently 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?

Only one optional parameter 'topic' with 100% schema description coverage. Description adds value by listing allowable values (finance, pharma, etc.) and clarifying that omitting gets a cross-category spread.

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

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

Description clearly states the tool is the onboarding entry point for a new agent, returning example questions categorized by topic. It uses specific verb 'returns category-bucketed example questions' and distinguishes itself from siblings by being the first call when unsure.

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 to use this FIRST when you don't know what Pipeworx can do, and explains how to use it with or without the topic parameter. No explicit when-not-to-use, but context is clear enough.

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 (idempotentHint, destructiveHint), it reveals ownership enforcement and soft-deletion behavior, adding useful context that annotations alone don't provide.

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

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

Two concise sentences, front-loaded with the action, no unnecessary words. Every sentence adds value.

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

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

Given the simple one-parameter tool with no output schema, the description is sufficient. It covers purpose, ownership, and effect on data. Minor omission: could mention idempotency, but that is covered by 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 already provides 100% coverage for the single parameter with a clear description. The tool description adds no additional semantic information beyond what the schema states.

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 resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly states ownership enforcement ('you can only cancel your own subscriptions') and a key behavioral trait ('row is deactivated not deleted') that guides correct usage, though it doesn't explicitly name alternative tools.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: replaces 4-6 sequential calls, uses SEC EDGAR for financial claims, returns specific verdicts with citations, and explains the pipeline. This goes well beyond annotations.

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

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

The description is front-loaded with trigger phrases and covers all aspects without wasted words. While somewhat long, every sentence adds important details. Good structure.

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 values (verdict, actual value, citation) and the pipeline. Given the tool's complexity and two parameters, the description is complete and covers all needed 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 coverage is 100% with clear descriptions for both parameters. The description adds value by explaining tolerance_pct defaults and override behavior, and provides meaningful examples for the claim parameter.

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

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

The description clearly states the tool's purpose: verifying factual claims using authoritative sources with examples of natural-language queries. It details the specific pipeline for financial vs. other claims, distinguishing it from sibling tools like search or research tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes the automatic routing and fallback behavior. While it doesn't explicitly state when NOT to use or name alternative tools, the context of siblings makes it clear enough.

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