Virustotal

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

Annotations already indicate a safe, read-only, idempotent tool. The description adds valuable behavioral context: default model is free, Anthropic requires user's API key and billing, return structure includes per-model and combined views, and the scoring range 0-100.

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 that is concise and front-loaded with the main action. Every sentence adds value, though a slightly more structured format (e.g., bullet points) could improve readability while remaining 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?

Despite no output schema, the description fully explains return values (per-model {score, confidence, signals, raw_response} + combined view). It covers billing responsibility for Anthropic, disambiguation via context, and default behavior, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with all parameters described. The description adds further meaning: explains default model behavior, clarifies when _apiKey is needed, and notes that context helps disambiguate common names.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility. It specifies the default model and optional Anthropic probe, and distinguishes itself from sibling tools like ask_pipeworx which focus on single queries rather than multi-model visibility audits.

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

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

The description explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use but does not explicitly say when not to use or name alternative sibling tools, though the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context: it routes to 3,745 tools, returns structured answers with pipeworx:// citation URIs. No contradictions.

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

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

The description is well-organized with a strong first sentence, a list of domains, usage patterns, and examples. It is slightly long but efficient, with no wasted sentences.

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

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

Given the lack of an output schema, the description could explain the response format more thoroughly. It mentions 'structured answer with citation URIs' but not the structure or variability. Adequate for a single-parameter tool but could be more 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 description coverage is 100%, so baseline is 3. The description only says 'natural language' and lists aliases, which the schema already documents. No additional semantic value beyond the schema.

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

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

The description clearly states it answers factual questions using structured data from many sources, and includes a strong preference over web search. However, it does not distinguish from sibling tools like ask_pipeworx_grounded or deep_research, which slightly reduces clarity.

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 'PREFER OVER WEB SEARCH' and provides a long list of applicable domains, along with examples. It gives clear when-to-use guidance but does not mention when not to use it or alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral details: refusal reasons, grounding mechanism, cost (one extra LLM call), and exact return structure (answer, evidence, confidence, etc.). 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 densely informative but slightly long. Every sentence serves a purpose (usage, behavior, return format, trade-offs). Could be tightened by removing redundant phrases like 'Same routing as ask_pipeworx' but overall 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 (grounded answering, multiple refusal reasons, high-stakes context), the description is exceptionally complete. It explains the return format, refusal scenarios, data sources (3,745 tools across 884 sources), and cost, compensating for the lack of an output schema.

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

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

Schema coverage is 100%, so the description need not add parameter details. It notes that all six parameters are aliases for 'question', which is already implied by the schema. No additional semantic value beyond the schema.

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

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

The description clearly states the tool's unique value: hallucination-resistant answering for high-stakes reads. It specifies the verb 'extracts answer using ONLY what the tool result contains' and explicitly contrasts with its sibling 'ask_pipeworx', making the purpose distinct.

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

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

Provides explicit when-to-use guidance ('high-stakes reads, when answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including a cost trade-off. This fully equips an agent for correct selection.

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, etc. The description adds extensive behavioral details: resolver contract (match confidence, alternatives), parent event extractor, news fallback mechanisms, safety short-circuits for low-confidence matches and closed markets, wide spread handling, and cancellation rule parsing. This goes far 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 very long and contains many technical details (e.g., resolution-rule risk, audited arb-bot ledgers). It is structured with labeled sections but could be more concise. Critical information is front-loaded, but overall it is verbose.

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

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

Given the tool's complexity (multiple fan-out categories, response shapes, edge cases), the description is extremely complete. It covers safety, resolution, news fallback, parent events, and cancellation rules. Without an output schema, the description adequately explains all return fields.

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 baseline is 3. The description adds value by explaining the effect of the depth parameter (quick vs. thorough) and include_raw (response size control). It also provides examples for the market parameter. This exceeds baseline.

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

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

The description states a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines inputs (slug, URL, question) and outputs (evidence packet, comparison). It distinguishes this tool from siblings by focusing on comprehensive bet research, while siblings like polymarket_edges are more specialized.

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

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

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides fan-out examples for different bet categories. However, it does not explicitly mention when not to use this tool versus alternatives, though the 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: for companies it pulls specific financial metrics from EDGAR/XBRL with correct fiscal year handling; for drugs it pulls FAERS counts, FDA approvals, and trial counts. It also notes sorting by primary metric and citation URIs.

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

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

The description is information-dense but slightly lengthy. It uses clear structure with examples, explicit instructions, and bullet-point style details. It could be trimmed slightly without losing meaning, but it remains efficient and well-organized.

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 of two entity types and no output schema, the description explains return format (paired data + citation URIs), data sources, and sorting behavior. It provides all necessary context for an agent to determine when and how to use the tool.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: it explains what each type (company/drug) retrieves, acceptable input formats (tickers/CIKs for company, drug names), and the expected count range (2-5). This fully compensates for any potential ambiguity in the schema.

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

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

The description uses specific verbs ('Compare') and resources ('2–5 companies or drugs'), and explicitly distinguishes from siblings like entity_profile (sequential single lookups). It states the tool's purpose with examples like 'X vs Y' and 'rank these companies'.

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

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

The description provides clear when-to-use instructions: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains the types and what data each pulls, giving sufficient context for an agent to choose this tool over 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 behavioral traits beyond annotations: decomposes question into sub-questions, runs in parallel, returns verbatim evidence with confidence, source, fetched_at, and a stable pipeworx:// citation. It explicitly states gaps for unanswered facets and that facts are never invented. This adds significant context beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is a single paragraph that front-loads the core purpose and then provides supporting details. It is dense but not overly long; however, it could benefit from bullet points or better structuring for easier parsing. Still, 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 tool's complexity (multi-source, parallel research), the description covers all essentials: what it does, how it works, when to use, prerequisites, costs, and expected output format (structured findings packet). No output schema is needed as the description adequately explains return values.

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 meaning of the depth enum values: 'quick=3, standard=5 (default), thorough=8 (paid plans).' This detail is not present in the schema's enum descriptions, making the description more helpful than 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 performs 'Grounded multi-source research in ONE call', decomposing questions into sub-questions and routing to 3,745 tools across 884 sources. It explicitly distinguishes itself from sibling tool ask_pipeworx by stating it is for broad/multi-part questions, whereas ask_pipeworx is for single 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 guidance: use for broad or multi-part questions, and use ask_pipeworx for single lookups. It also mentions requirements (Pipeworx account, sign up via GitHub) and cost implications (depth:'thorough' requires a paid plan), and expected processing time (15-60s).

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, idempotentHint, and destructiveHint. The description adds critical context: it returns top-N tools with 'names, descriptions, and full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.' This goes 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 moderately sized but efficient. It front-loads the purpose, gives domain examples, and details the return value. Every sentence contributes. Minor redundancy in listing aliases that are already in schema.

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

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

Given no output schema, the description explains the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It covers the use case of tool discovery well. Could be more explicit about output structure (e.g., JSON array), but is sufficient.

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 described (query, q, task, limit, search, description). The description adds value by explaining the primary parameter accepts 'natural language description' and provides examples like 'analyze housing market trends'. It also lists aliases, which the schema already does, but the description consolidates understanding.

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 action (find), the resource (tools), and the method (via description). It distinguishes itself from sibling tools by being the discovery interface for the entire tool suite.

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

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

The description gives explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lists use cases like 'browse, search, look up, or discover.' It does not mention when not to use it, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it details the fan-out across multiple sources, describes return fields, and notes the patents sunset soft-fail. This goes beyond the annotations without contradicting them.

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

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

The description is a single paragraph but well-organized with bulleted return fields and prerequisites. It is informative without excessive verbosity, though it could be slightly more concise by grouping similar information.

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

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

Despite no output schema, the description thoroughly explains return values (filings, fundamentals, patents, news, LEI) and limitations (patents sunset, name requirement). It covers the essential information for a complex tool, though minor details like pagination or rate limits are absent.

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

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

The schema covers all parameters, and the description adds practical meaning: 'type' is restricted to 'company', and 'value' can be ticker or zero-padded CIK with a clear note that names are not supported. This enriches the schema documentation.

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

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

The description uses strong verbs ('profile', 'fan out') and specifies the exact entity type (US public company). It provides example queries and clearly distinguishes from sibling tools like 'resolve_entity' and 'compare_entities', making the tool's scope 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?

The description explicitly states 'ALWAYS PREFER over chaining single-pack lookups' when a holistic view is needed. It also warns that names are not supported and directs users to 'resolve_entity' first, providing clear guidelines for correct tool selection.

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 destructiveHint=true and idempotentHint=true. The description adds context about why deletion is appropriate (stale, done, sensitive). 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?

Two sentences: first states purpose, second gives usage guidance. No wasted words.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, usage guidance, and pairing. Complete.

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

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

Schema coverage is 100% and the description does not add semantics beyond the schema's description of 'key' as 'Memory key to delete'. Meets baseline.

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

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

The description clearly states the verb 'Delete', resource 'memory', and method 'by key'. It distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use ('context is stale, task is done, clear sensitive data') and suggests pairing with 'remember' and 'recall'.

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 consistent. Description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown format. 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, front-loaded with purpose, no wasted words. Concise 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?

Describes output format (single text blob for site-root/llms.txt) and process. Lacks error handling or invalid URL behavior, but given tool simplicity and annotations, it is largely complete.

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

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

Schema description coverage is 100%. Description does not add significant parameter info beyond schema; mentions extraction process but not new constraints or defaults beyond what schema already provides (e.g., max_links default 25).

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 generates a production-ready llms.txt file for any URL, with specific verb and resource. It distinguishes from siblings by focusing on AI crawler indexing and listing specific use cases.

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

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

Provides explicit use cases (client site indexing, own project drafting, competitor auditing) but lacks when-not-to-use guidance or alternatives comparison. Still clear enough for appropriate selection.

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 full safety profile (readOnly, idempotent, non-destructive). Description adds moderate value by specifying caller scope and active/inactive filtering, but no major behavioral disclosure 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 efficient sentences, front-loaded with purpose and returns, followed by usage guidance. No fluff or redundancy.

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

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

Covers purpose, scope, return fields, and usage guidance. Lacks mention of pagination or limits, but acceptable for a simple list tool with comprehensive annotations.

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

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

Schema coverage is 100% and fully describes the single parameter. Description does not add additional information about parameters, so baseline score of 3 applies.

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

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

Description explicitly states 'List the caller's active subscriptions' with a specific verb and resource, lists returned fields, and is clearly distinguishable from sibling tools like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel', providing direct context for alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description's addition of what the tool returns (stats, categories, DNS records, etc.) provides useful behavioral context 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 two sentences long, front-loads the purpose, and contains no extraneous information. Every word earns its place.

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

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

With a single required parameter, comprehensive annotations, and an output schema (present), the description fully covers the return values, making it complete for a lookup tool.

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

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

Schema coverage is 100% and the single parameter 'domain' is well-described in the schema as 'FQDN (no scheme)'. The description does not add further parameter guidance, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb-resource combination ('Look up a domain') and lists distinct return contents (last-analysis stats, categories per vendor, DNS records, popularity ranks, reputation score), clearly differentiating it from sibling tools like lookup_file, lookup_ip, lookup_url.

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

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

The description implies usage for domain lookups but provides no explicit guidance on when to use this tool versus alternatives (e.g., lookup_ip, lookup_url), nor does it mention when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it returns 'last-analysis stats' and other fields, which is useful but does not disclose additional behavioral traits like rate limits or caching behavior.

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

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

Two concise sentences: first defines action and return fields, second provides usage context. No fluff.

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

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

For a simple lookup tool with one parameter and output schema, the description covers what the tool does, what it returns, and a typical use case. No missing critical information.

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

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

Schema has 100% coverage with a description for the hash parameter. Description repeats accepted hash types but adds no new semantic meaning. Baseline 3 is appropriate.

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

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

Description clearly states action: 'Look up a file by hash' and lists specific resource (file) and identifiers (sha256, sha1, md5). It distinguishes from sibling tools like lookup_domain and lookup_ip by targeting files.

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

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

Provides explicit use case: 'Useful for triaging hashes seen in alerts or logs.' While it doesn't state when not to use or compare with alternatives, the context is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by detailing the returned fields (last-analysis stats, ASN, etc.), but could mention any rate limits or data freshness. Still, it provides useful behavioral context beyond annotations.

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

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

The description is a single sentence, front-loaded with the action, and no wasted words. It efficiently communicates what the tool does and what it returns.

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 (one required parameter, output schema exists), the description is complete. It covers the purpose, parameter, and return value content without needing additional context.

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

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

Schema description coverage is 100% (the 'ip' parameter has a description and examples). The tool description does not add additional meaning beyond confirming it's an IPv4 address. Baseline 3 is appropriate since the schema already does the job.

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 'Look up' and the resource 'IPv4 address', and lists the specific data returned (stats, ASN/owner, country, network range, reputation score). This differentiates it from sibling tools like lookup_domain or lookup_url.

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

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

The description implies usage when you have an IPv4 address and want detailed information. While it does not explicitly exclude other scenarios or name alternatives, the sibling tools (e.g., lookup_domain) cover different resource types, so the context is clear.

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

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

The description adds valuable behavioral details beyond annotations: URL canonicalization before lookup and no submission step required. Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description enriches understanding of the tool's behavior.

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 purpose and key outputs, followed by behavioral notes. Every sentence adds value with no redundancy.

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

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

Given the simple single-parameter input and existing output schema, the description completely covers the tool's purpose, return value, and behavioral traits. An agent can confidently assess when to invoke this tool.

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

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

The input schema already describes the 'url' parameter as 'Full URL including scheme' with 100% coverage. The description mentions canonicalization but doesn't add significant parameter-level meaning beyond the schema.

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

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

The description clearly states the tool looks up a URL's reputation, listing specific outputs (last-analysis stats, categories, redirect info). This differentiates it from sibling tools like lookup_domain and lookup_ip, which target different entity types.

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

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

The description implies usage for reading existing URL reports without submission, but lacks explicit guidance on when to use this tool versus alternatives like lookup_domain or lookup_file. It provides clear context but no 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?

Discloses rate limit (5 per identifier per day), free usage, and that it doesn't count against quota. No contradiction with annotations (readOnlyHint=false implies write operation).

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?

Compact yet comprehensive, front-loaded with purpose, then guidelines, then constraints. Every sentence serves a purpose.

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

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

For a simple feedback tool with 3 parameters (2 required) and no output schema, the description fully covers usage, constraints, and expected content.

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 3. Description adds value by explaining context parameter usage and giving guidance on message content (specific, 1-2 sentences, 2000 chars max).

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

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

Description clearly states verb 'Tell' and resource 'Pipeworx team' with specific types of feedback. Distinguishes from siblings as no other tool is for feedback.

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 use cases (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Explains how feedback is used and rate limits.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that data is 'self-aggregating', sourced from CF analytics engine, contains no PII, and is cached 5min-1h. This provides clear behavioral context 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?

The description is concise (5 sentences) and front-loaded: first sentence gives the core purpose, followed by a bullet-like list of use cases, then data source and caching. Every sentence adds value without redundancy.

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

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

The description explains the tool's output (top tools, packs, total call volume) and caching behavior. While no output schema is provided, the description gives enough context for an agent to understand what to expect. Minor detail: the structure of the output (e.g., sorted list, counts) could be more explicit.

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

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

The schema covers the single parameter 'window' with enum and description. The description adds semantic context on how window length relates to use case (hot vs. steady-state), which is valuable but not essential given the schema's completeness.

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

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

The description clearly states the tool returns top tools, packs, and call volume over recent windows. This distinguishes it from sibling tools like ask_pipeworx (for specific questions) and discover_tools (for discovery), as it focuses on aggregate trending data.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming popular tools, and seeing alignment. It also explains window choices with guidance on short vs. long windows, giving clear when-to-use context.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral details: fill check against live CLOB depth, semantic anchor for similarity, partition filter for placeholders, and warnings against trading when realizable edge is non-positive. This goes well beyond what annotations provide.

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

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

The description is lengthy but well-structured with clear sections (REQUIRES, event mode, topic mode, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the requirement and overview. Every sentence provides necessary information for a complex tool.

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

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

Despite no output schema, the description enumerates return fields (opportunities[], gap_pp, suggested_trade, reasoning, partition_check) and explains the fill check logic. It covers edge cases like low similarity and placeholder filtering. The description is comprehensive for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description adds more context: example slugs for event and seed questions for topic, and explains the behavioral difference between modes. This adds meaningful value beyond the schema.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with two distinct modes (event and topic). It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage 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 explicitly requires one of event or topic, recommends event for specific markets and topic for cross-event scanning, and mentions using polymarket_fill_risk for custom sizing. It provides clear context but does not list exclusions or when to avoid using this tool entirely.

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?

Goes far beyond annotations by explaining internal logic of three segments, response structure, diagnostics, and edge cases like Fed bets. No contradiction with readOnlyHint and idempotentHint.

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

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

Description is long but front-loaded with purpose and well-structured with bold headers and bullet points. Every sentence adds value, though 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?

Comprehensively covers output structure, internal logic, parameter effects, and diagnostic information. Compensates for lack of output schema with detailed behavioral explanation.

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 value by explaining rationale (e.g., slippage_pp context, min_partition_leg_kelly behavior). Adds 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 the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from siblings by focusing on data disagreement.

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 extensive guidance on when to use, including model families, tradeable-edge knobs, and caching behavior. However, it does not explicitly contrast with alternatives like 'polymarket_arbitrage' or 'polymarket_kalshi_spread'.

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

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

The description extensively elaborates beyond the annotations (readOnlyHint, etc.). It details the response structure (tracked[], expired[], snapshot_dates[]), explains fields like trend, decay_pp_per_day, lifespan_days, and notes limitations (60-day TTL, snapshot start date, decay from daily closes not intraday). This provides full behavioral context.

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

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

The description is detailed but well-structured: purpose sentence, then args, then response layout with capitalized sections (RESPONSE:), and a LIMITS section. While lengthy, every sentence adds value and it is front-loaded with the core purpose.

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

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

With no output schema, the description fully explains the return values and their meanings, including edge_pp_net time-series, first_seen, trend types, decay calculation, and snapshot gaps. It also covers limitations, making it complete for a tool with simple inputs and complex outputs.

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 both parameters documented (days and window). The description restates defaults and limits but does not add significant new meaning beyond the schema. The baseline of 3 is appropriate as the schema already provides sufficient parameter semantics.

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.' It answers the specific question of how long an edge has existed and whether it's shrinking, distinguishing it from sibling tools like polymarket_edges (current edges) by focusing on time-series 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 provides explicit guidance on when to use this tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It implies using this for historical decay analysis rather than just current edges, and specifies args with defaults and limits (days lookback, window family).

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, confirming a safe, read-only, idempotent operation. The description adds significant behavioral context: it checks live order book depth, returns fields like top_of_book, vwap_fill_price, slippage, verdict, and warns about forced directional risk and thin legs. This covers behavioral traits 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 moderately long but well-structured: it starts with the core purpose, then separates single-market and basket modes clearly, and ends with usage guidance. Every sentence adds value, though it could be slightly more concise without losing clarity. The structure aids quick scanning.

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

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

Given the tool's complexity (two modes, no output schema, multiple return fields), the description is remarkably complete. It explains both modes, parameter behavior, return fields (including verdict, profit_usd, thin_legs, forced_directional_risk), and contextual warnings. No critical gaps are apparent.

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 each parameter has a description. The tool description adds further meaning: for size_usd, it clarifies interpretation per mode (spend on buys, target proceeds on sells; for basket, settlement notional per leg). It also explains the auto-behavior of side in basket mode. This enriches the schema without being redundant.

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

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

The description explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool (before acting on signals or trades above ~$500).

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround on thin books not capturable, partial fills causing directional risk), which helps the agent decide between 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?

The description adds extensive behavioral context beyond annotations: explains two modes, response fields like compatibility_warning, temporal_alignment, and skipped counters. It matches readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and no contradictions exist.

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?

While the description is lengthy, it is well-structured with clear sections for modes, response fields, and safety notes. Every sentence adds value. Could be slightly more concise but remains efficient for the 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?

Covers all critical aspects: two usage modes, response structure (spreads, compatibility warnings, temporal alignment, skip counters), and edge cases. Even without an output schema, the description provides sufficient detail 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?

Schema coverage is 100% with each parameter described. The tool description further clarifies the interaction between parameters (topic vs explicit overrides), adding meaning beyond the schema. A slight deduction because the schema itself is already quite descriptive.

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: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit parameters) and distinguishes itself from sibling tools (no other spread tool exists).

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

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

Explicitly describes when to use the tool (for comparing same-outcome probabilities across venues) and when not (when compatibility_warning fires, e.g., non-equivalent bet shapes or semantically unrelated events). It also notes that pre-mapped topics often return warnings, setting realistic expectations.

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 confirm read-only, idempotent, non-destructive. Description adds listing behavior and scoping details (IP, key hash, account ID), enhancing transparency 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, front-loaded with action and resource, then context and pairing. No wasted words.

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

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

Complete for a simple retrieval tool: explains functionality, usage scenario, parameter, scoping, and related tools. No output schema needed for such a 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 covers 100% of the single parameter with same semantics as description. Description reinforces but adds no new detail beyond the schema.

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

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

Description clearly states the tool retrieves a value or lists keys, with specific verb and resource. Distinguishes from siblings 'remember' and 'forget' by name and function.

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

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

Provides clear context for when to use (look up stored context) and scoping (identifier-based). Implicitly pairs with remember/forget, but lacks explicit exclusions or when-not usage.

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

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

The description says setting mark_read:true flags returned events read, which is a write operation. However, annotations declare readOnlyHint: true, indicating the tool does not modify state. This is a direct contradiction, so score is 1.

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

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

The description is two sentences long, front-loaded with the main action, and every word adds value. No redundancy.

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

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

The description explains the return value structure (source, citation_uri, raw payload), the effect of mark_read on subsequent calls, and the pagination behavior with limit. Despite the contradiction, it is complete for understanding the tool's function.

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 meaningful context for three parameters (type, since, mark_read) beyond the schema, but does not mention limit or unread_only. This extra value justifies a higher score.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed'. It distinguishes itself by mentioning the alternative GET endpoint for scripts, and it is specific about what is returned, setting it apart from sibling tools.

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

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

The description explains when to use the tool (polls work fine) and provides an alternative access method (GET endpoint for scripts/dashboards). However, it does not explicitly state when not to use this tool, but the 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?

Annotations already declare readOnlyHint and destructiveHint, so safety is covered. The description adds important behavioral details: fan-out to multiple sources, fallback from GDELT to GNews on errors, USPTO soft-fail, and parameter format details. This adds significant context.

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

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

The description is moderately long but well-structured with front-loaded examples. Every sentence provides useful information without redundancy. A minor improvement could be slightly more conciseness, but overall 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?

Given the complexity (multiple sources, fallbacks, no output schema), the description is remarkably complete. It explains return structure (changes[], total_changes, citation URIs), parameter behavior, and even provides the alternative tool. No gaps identified.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds value by explaining `since` parameter formats (ISO date and relative shorthand) with examples, and clarifying that `type` is currently limited to 'company' and `value` accepts ticker or CIK.

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

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

The description clearly states the tool returns a change feed for a company in a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It includes specific query examples like 'What's new with X' and distinguishes itself from sibling tool entity_profile.

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

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

The description provides explicit guidance on when to use this tool (for recent changes) vs when to use entity_profile (for static profile). It also explains the fan-out behavior and fallback mechanism for news sources.

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 idempotent, non-destructive write. Description adds: scoped by identifier, persistent for authenticated users, 24-hour for anonymous. This reveals important behavioral traits beyond annotations. No contradiction.

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

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

Three sentences, each carrying distinct info: purpose, usage, behavioral details. Efficient, front-loaded, no redundancy.

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

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

Given simple 2-param schema, no output schema, and annotations, the description fully equips an agent: purpose, when/why, persistence scope, key-value format, and link to sibling tools.

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 valuable examples for key (subject_property, target_ticker) and value (findings, addresses), enriching meaning beyond the schema descriptions.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions. It distinguishes itself from sibling tools like recall and forget by specifying its role as storing data, and it uses specific verbs ('save', 'reuse') and resource ('data the agent will need to reuse later').

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 discovering something worth carrying forward (e.g., resolved ticker, target address). Provides examples and mentions pairing with recall and forget. Lacks explicit when-not-to-use, but overall gives clear 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, and idempotentHint, indicating safe, read-only, idempotent behavior. The description adds value by disclosing that the tool 'cascades through several lookup endpoints internally' and 'replaces 2-3 manual lookups,' providing operational insight beyond annotations. No contradictions.

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

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

The description is a single, well-structured paragraph that front-loads the purpose with examples. Every sentence adds value: it explains when to use, supported types, return values, and internal behavior. No unnecessary words.

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

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

For a tool with no output schema, the description comprehensively explains return values for each entity type, including citation URIs and auto-disambiguation for companies. Given the complexity of internal cascading, it provides sufficient context for an AI agent to understand inputs, outputs, and behavior.

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 meaning by explaining what each parameter returns for different types (e.g., 'company' returns ticker + 10-digit CIK + company_name, 'drug' returns RxCUI + ingredient + brand). 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 defines the tool's purpose: resolving user-spoken names to official identifiers. It provides specific examples ('What's the ticker for...', 'find the CIK for...') and explicitly states 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools by positioning it as the first step for name-to-ID 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 gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types and what each returns, providing clear context for when to invoke. While it doesn't explicitly list when not to use it or mention alternatives, the purpose is sufficiently narrow to avoid ambiguity.

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 significant behavioral detail beyond annotations: explains probing each entity, ranking by score, and return structure (score, confidence, signal density). Annotations already indicate safety, but description enriches understanding.

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 description with main purpose upfront. Two sentences plus a use case and return format. No fluff, but slightly more structure could improve scannability.

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?

Explains return values (ranked list with metrics) despite no output schema. Covers constraints (2-8 entities, first as subject). Lacks mention of rate limits or error cases, but overall adequate.

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: first entity treated as subject, context disambiguates common names, models omitted defaults to workers-ai. This adds useful nuance beyond schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check for each. It distinguishes from sibling ai_visibility_check by specifying multi-entity comparison and 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?

Provides a clear use case ('competitive AI-marketing audits') and implicit context for when to use it. Does not explicitly state when not to use or differentiate from compare_entities sibling, but the specific AI focus is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds crucial details: NPM-only constraint, bundlephobia first-measurement delay (5-30s), graceful degradation with sources_failed, and return structure (summary, advisories, links, alternatives). No contradictions.

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

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

Description is front-loaded with the main purpose in a single sentence, followed by concise details on use cases, limitations, and return values. Every sentence adds unique information with no redundancy.

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

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

Given the tool's complexity (composite check across two services) and lack of output schema, the description fully covers return fields, edge cases, and limitations. An agent has sufficient information to 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 covers both parameters with descriptions (100% coverage). Description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted and that version defaults to the latest. This extra context justifies a score above baseline.

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

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

The description clearly states the composite check for npm packages, specifying the verb ('scan'), resource ('dependency'), and the scope ('should I add this npm package'). It distinguishes from siblings by explicitly noting NPM-only in v1 and directing other ecosystems to deps.dev:version directly.

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

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

Explicitly states when to use: when questions about safety, popularity, size, or cost of adding a package arise. Provides clear exclusion for non-NPM ecosystems and mentions alternative tool ('deps.dev:version'). Also explains partial failure handling, aiding agent decision-making.

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. The description adds extra behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char windows, character offsets, similarity scores, truncation cap at 200K chars with a flag. 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 5 sentences, front-loaded with purpose, then usage, then technical details. Every sentence adds value without redundancy. Highly concise 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?

Despite no output schema, the description informs about return values: top-N passages with character offsets and similarity scores. It also covers truncation behavior and embedding model. Completes the picture for an agent to use 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 already describes all 3 parameters with 100% coverage. The description adds value by providing examples for query (e.g., 'supply-chain risk') and context for text (e.g., 'SEC 10-K body'). This exceeds baseline but is not essential.

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

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

The description clearly states it performs semantic search inside a fetched record, provides concrete examples (SEC filings, articles), and distinguishes from sibling tools like ask_pipeworx_grounded, which is used for grounding answers. The verb 'search within' and resource 'fetched record' 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 when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also mentions pairing with ask_pipeworx_grounded, suggesting an alternative workflow. This gives clear context for choosing this tool over others.

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?

Exceeds annotations by detailing OAuth requirement, channel limits (10/day SMS), webhook HMAC signing, and auto-disable after 10 failures. 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?

Single paragraph is dense but clear; could benefit from bullet points for readability, but overall efficient and front-loaded with the core action.

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

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

Given no output schema, description covers return value, prerequisites, all types, delivery options with constraints, and channel behavior. Highly complete for a complex subscription 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 has full coverage; description adds concrete usage examples for each subscription type and delivery field, explaining type-specific params and verification requirements 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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id.' Distinguishes from siblings like unsubscribe, list_subscriptions, and recent_alerts by its specific creation 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?

Provides explicit requirements (Pipeworx OAuth account), supported types with examples, and delivery channels. Does not explicitly state when not to use, but context implies alternatives exist for pulling alerts (recent_alerts). Still very helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context that it's an onboarding entry, returns examples, and has optional topic focus, with 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 paragraph, front-loaded with common queries, and clear. Could be slightly more structured but is efficient.

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

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

For a tool with 1 optional param and no output schema, description comprehensively explains purpose, behavior, and usage, needing no further detail.

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 further explains the topic parameter with examples of values and meaning, adding that omitting it gives 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?

The description clearly states the tool is an onboarding entry point for a new agent to learn what questions to ask Pipeworx. It explicitly says it returns category-bucketed example questions with exact tool+argument shapes, distinguishing it from siblings like discover_tools or ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use guidance. Also mentions alternative topic filtering.

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 that rows are deactivated, not deleted, and historical events remain available. Adds context beyond annotations (idempotent, not destructive).

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 that are front-loaded and directly informative. No unnecessary words.

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

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

Given single parameter and no output schema, the description fully covers purpose, ownership, and side effects. Complete for agent decision-making.

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

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

Schema coverage is 100%, description adds no extra parameter meaning. Baseline score of 3 is appropriate.

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

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

Clearly states the action 'Cancel a subscription by id', with specific verb and resource. Distinct from siblings 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?

Explicitly mentions ownership enforcement, indicating when the tool can be used (only for own subscriptions). Does not list alternatives but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral traits: uses SEC EDGAR + XBRL, returns structured verdict, and replaces multiple sequential calls. No contradiction detected.

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 thorough but front-loaded with examples and purpose. Every sentence adds value; it could be slightly tighter but remains clear and well-organized.

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

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

For a complex tool with one parameter and no output schema, the description fully compensates by detailing the return values, data sources, and use cases. No gaps remain.

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

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

Schema coverage is 100%, providing baseline 3. Description adds value with natural-language examples, expected format, and context on what constitutes a valid claim, exceeding the schema's 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 like 'validate', 'verify', 'confirm or refute' and clearly identifies the resource as natural-language factual claims, with domain specialization (company-financial via SEC EDGAR + XBRL). It distinguishes from sibling tools by addressing a unique niche.

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

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

Explicitly states when to use ('whenever the agent needs to check factual correctness') and provides trigger phrases. Lacks explicit when-not-to-use or alternatives, but the context from siblings implies this tool is the go-to for claim verification.

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