Open Corporates

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

Annotations indicate read-only, open-world, idempotent, non-destructive operations. The description adds context: it scores visibility per model, returns fields (score, confidence, signals, raw_response), and notes that probing Anthropic requires a BYO key with direct payment to Anthropic. This adds value beyond the annotations without contradiction.

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

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

The description is efficient (~80 words), front-loaded with the core function in the first sentence, and includes examples and parameter guidance without redundancy. 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?

Despite no output schema, the description explains the return format (per-model score, confidence, signals, raw_response + combined view). It covers all 4 parameters and provides sufficient context for an agent to understand the tool's purpose 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 description coverage is 100%, baseline 3. The description adds meaning: provides examples for 'entity', explains 'models' supported values, clarifies '_apiKey' is only needed for Anthropic, and describes 'context' as disambiguation aid. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's action ('probe LLMs'), resource ('what they know about a business / brand / product / topic'), and output ('score visibility 0-100 per model'). It uses specific verbs and nouns, and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on multi-model probing and scoring.

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

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

The description provides explicit usage scenarios: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use optional parameters (e.g., `_apiKey` for Anthropic). However, it does not explicitly state when not to use this tool versus 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, openWorldHint, idempotentHint, and destructiveHint false. Description adds context: 'one fast call', 'works on every tier', returns structured answer with stable pipeworx:// citation URIs. Does not contradict annotations.

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

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

Description is fairly long but front-loaded with key instruction 'PREFER OVER WEB SEARCH'. Every sentence adds value: lists domains, examples, directs to alternatives. Could be slightly tightened 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?

No output schema, but description explains return format (structured answer with citation URIs). Covers type of questions, sources, relationship to siblings, and example questions. Complete for a tool with a simple input.

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

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

Schema covers all 6 parameters (100% coverage) with descriptions. Description adds value by explaining that the tool routes the question to appropriate sources and that multiple aliases (q, text, input, query, prompt) are accepted for the question field.

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 it routes questions to 4,476 tools across 1,127 sources for authoritative structured data with citations, distinguishing from siblings like ask_pipeworx_grounded and deep_research. It also provides a clear preference over web search.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', lists specific domains, and directs when to step up to ask_pipeworx_grounded (for hallucination-resistant single answer) or deep_research (for broad multi-part questions). Includes example questions.

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 substantial detail: the routing mechanism, extraction logic, return format (including evidence and confidence), and explicit refusal reasons. 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 well-structured and front-loaded: it starts with the core purpose, then provides use-case guidance, cost trade-off, and detailed return format. Every sentence serves a purpose, and there is no redundancy or fluff.

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

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

Despite lacking an output schema, the description fully explains the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also covers the underlying routing logic and the fact that it selects from 4,476 tools. This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with all 6 parameters documented as aliases for 'question'. The description reiterates that 'question' accepts natural language with aliases, adding no new semantics. The description adds minimal value over the schema, 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 clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads', explaining it routes queries to the appropriate tool, extracts answers strictly from tool results, and returns explicit refusals when data is insufficient. It distinguishes itself from the sibling 'ask_pipeworx' by highlighting the extra cost and stricter factuality guarantees.

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 specifies when to use this tool (high-stakes reads, quotes, citations, financial/legal/medical verdicts) and when to prefer the sibling 'ask_pipeworx' (casual lookups), citing the extra LLM call cost. It provides clear context for 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 declare readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds extensive behavioral context: short-circuits on low-confidence matches, closed markets, wide spreads, resolution-rule risk, cancellation rules, and error handling (GDELT 429s). No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). Every sentence adds unique value. Slightly verbose but justified by tool complexity. Front-loaded with main purpose.

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

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

No output schema exists, but description thoroughly explains return shapes (result.market, result.analysis, result.evidence), confidence levels, parent event extraction, news fields, safety mechanisms, and resolution rules. Covers edge cases like low-confidence, closed markets, wide spreads, and cancellation rules. Very complete.

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

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

Schema coverage is 100% with descriptions. The description adds significant value beyond schema: explains market input formats (slug, URL, question), depth enum defaults, and include_raw size implications. Examples in schema are complemented by description's behavioral context.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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 statements ('Use for...') and gives detailed fan-out examples per category (e.g., BTC bet, Fed bet). However, it does not explicitly state when NOT to use this tool or suggest alternative tools for specific scenarios, 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds significant context: it explains the data source (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and that results are sorted. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with common query patterns. Every sentence adds value—examples up front, then technical details. No fluff or repetition.

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

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

Given the complexity (two entity types, different data sources) and no output schema, the description is remarkably complete. It covers what data is returned for each type, ordering, citation URIs, and even estimates the number of sequential lookups it replaces.

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

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

Schema coverage is 100% with descriptions, but the description adds meaning: it explains that 'company' pulls latest 10-K financials and 'drug' pulls adverse-event counts/FDA approvals/trials. It also clarifies that values for companies are tickers/CIKs and for drugs are names, and imposes a max of 5 items.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, pulling financial data for companies and adverse event data for drugs. It distinguishes from siblings like entity_profile or get_company which are single-entity lookups. Example queries ('Compare X and Y', 'head to head') make the purpose immediately clear.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong when-to-use guidance. It also explains the data pulled for each type and that results are sorted by primary metric, helping the agent choose correctly.

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 significant behavioral traits beyond annotations: account requirement, paid plan for 'thorough' depth, parallel decomposition into facets, output format (findings packet with evidence, confidence, source, citation, gaps), and expected response time (15-60s). 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 comprehensive but slightly verbose; however, every sentence serves a purpose and is logically structured with key information (sign-in, alternatives) front-loaded. Could be trimmed slightly without losing value.

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

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

Given no output schema, the description fully explains the research process and output format, including the findings packet structure and gaps array. Also covers expected latency and scope limitations, making it complete for a complex tool.

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

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

Schema coverage is 100% and description adds meaning beyond schema: explains depth controls facet count (3/5/8) and paid plan requirement, and advises that questions can be broad/multi-part. All parameters are well-documented.

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 multi-source research across structured data sources (SEC filings, FDA, etc.) in one call, distinguishing itself from open-web search and sibling tools like ask_pipeworx. Uses specific verbs and resource references.

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 this tool vs alternatives: use ask_pipeworx if not signed in, for single lookups, or for breaking/current news. Also notes limitations like empty gaps for topics not in structured catalog, providing clear exclusions.

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

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

Annotations declare readOnlyHint, idempotentHint true and destructiveHint false. The description goes beyond by explaining it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is ready to call directly. No contradictions with annotations.

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

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

The description is appropriately sized with multiple sentences, each adding value. It starts with the core purpose, lists domains, explains return value, and gives usage advice. No wasted words.

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

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

Despite no output schema, the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. It also includes usage examples in the input schema. The description is complete for an agent to understand what the tool does and what it returns.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'query' as a natural language description and lists aliases, but does not add significant semantic value beyond what the input schema already provides.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many domains. It distinguishes from sibling tools like search_companies by saying 'Call this FIRST when you have many tools available and want to see the option set', which explicitly positions it as a discovery tool rather than a data retrieval tool.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and provides strong guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This clearly tells the agent when to invoke 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?

Discloses detailed behavior: fans out across multiple sources, returns specific fields with URIs, notes patent sunset and soft-fail, and specifies input constraints. All beyond what annotations provide (readOnly, openWorld, idempotent). 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 detailed but well-structured: starts with user-centric examples, then states purpose, then enumerates sources and return fields. Every sentence adds value, though slightly verbose for some contexts.

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 provides substantial detail on return fields and their contents (e.g., fundamentals sorting, patent status). Covers most relevant aspects, though minor gaps like error handling are omitted.

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 parameters well (100% coverage), but description adds value by clarifying acceptable values (ticker or CIK, names not supported) and explains that type currently only supports 'company' with future plans. This aids correct parameter selection.

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

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

Description clearly states the tool provides a holistic cross-source profile of a US public company, with concrete examples ('Tell me about X') and distinguishes from sibling tools by explicitly preferring this over chaining individual lookups for holistic queries.

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

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

Explicitly advises when to use (holistic view) and when not (names not supported, recommending resolve_entity). Also notes to prefer over chaining single-pack lookups, providing clear usage context.

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

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

Annotations already indicate destructive and idempotent. Description adds context about why to delete (clear stale/sensitive data), going beyond annotations without contradiction.

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

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

Two concise sentences with no wasted words. Purpose is front-loaded, then usage guidance and sibling references follow efficiently.

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?

Completely describes tool behavior, usage context, and sibling tools for a simple single-parameter, no-output-schema tool. No gaps.

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

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

Schema covers parameter fully with description 'Memory key to delete'. Description adds no new info about the parameter, meeting baseline for complete schema coverage.

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

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

Clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. Mentions sibling tools 'remember' and 'recall', distinguishing itself.

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

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

Explicitly lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with 'remember and recall', implicitly stating 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, idempotentHint=true, destructiveHint=false. Description adds behavioral details like fetching the page, extracting title/description/links, and emitting markdown format. This adds 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?

Description is concise at about 4 lines, front-loaded with the main purpose, and each sentence serves a clear function. 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 the tool's simplicity (no output schema, 2 parameters), the description sufficiently covers behavior, output format, and use cases. Annotations provide safety context. Nothing major missing.

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

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

Schema description coverage is 100% (both url and max_links are described). Description repeats schema details without adding new meaning beyond defaults. 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 the verb 'generate' and the resource 'llms.txt file for any URL'. It specifies the purpose for AI crawlers, distinguishing it from sibling tools that perform other tasks like search or research.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor audit). No explicit exclusion criteria, but the context is clear enough for an AI agent to decide when 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?

Adds context beyond annotations by listing returned data categories (registration, officers, filings, industry codes). No contradictions with annotations.

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

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

Two sentences, no filler, front-loaded with the action and parameters.

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

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

Fully covers the tool's functionality given its simplicity and presence of 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 already describes parameters fully (100% coverage). Description adds an example but no new semantic details.

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 tool retrieves full company details by jurisdiction and number, distinguishing it from search tools.

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

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

Provides an explicit usage example and implies when to use based on having a specific identifier, but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and implies default filtering, but no additional 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 sentences: first defines purpose, second adds usage context and output fields. No fluff, front-loaded, 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?

Simple read-only tool with one optional parameter and no output schema. Description sufficiently covers return format and usage context, meeting needs for selection and invocation.

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

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

Schema coverage is 100% with clear description of 'include_inactive'. Description does not elaborate on parameters beyond what's in schema, so baseline score 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?

Clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from write-oriented siblings like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Does not mention alternatives but context from siblings implies use case.

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 (which are neutral), the description discloses rate limits (5 per identifier per day), quota impact (free, doesn't count against tool-call quota), and the feedback's impact (read daily, influences roadmap). No contradiction with annotations.

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

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

The description is a single focused paragraph that logically flows from purpose to usage guidelines to behavioral notes to parameter guidance. Every sentence is informative and necessary, with no redundancy or fluff.

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

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

Given the tool's moderate complexity (3 params, nested objects, enums), the description covers all essential aspects: types, usage boundaries, rate limiting, quota, and specific formatting advice. No output schema exists, but the return value is trivial; the description is complete for correct tool invocation.

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

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

Although schema coverage is 100%, the description adds significant value: it explains the enum values in practical terms (e.g., 'bug = something broke or returned wrong data'), encourages specificity in 'message', and clarifies that 'context' is optional. This goes well beyond the schema's descriptions.

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

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

The description explicitly states the tool's purpose: reporting bugs, requesting features, noting data gaps, or giving praise. It clearly identifies the resource (Pipeworx team) and the action (tell/bug/feature/praise). This distinguishes it from sibling tools which are analytical or data retrieval tools.

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

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

The description provides precise when-to-use instructions for each category (bug: wrong/stale data; feature/data_gap: missing tool; praise: working well). It also explicitly advises against pasting end-user prompts, giving clear usage boundaries.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching window (5min-1h). No contradiction with annotations.

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

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

The description is moderately concise, with a clear structure: first sentence states output, then use cases, then data origin. Slightly longer than necessary but still efficient.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers purpose, usage, behavior, and caching. It is complete and leaves no major gaps.

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

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

Schema coverage is 100% with one parameter having an enum and description. The description adds meaning beyond schema by explaining that shorter windows surface hot trends and longer windows show steady-state demand, aiding parameter selection.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It specifies the resource ('Pipeworx trending') and verb ('returns'), and distinguishes from siblings by focusing on real-time agent usage on Pipeworx.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming popular tool, seeing alignment with use case) and mentions caching behavior. While it does not explicitly state when not to use, it provides sufficient context for an agent to decide.

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

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

Annotations already show readOnly, openWorld, and idempotent. The description adds behavioral details like fill check logic, semantic anchor (Jaccard similarity ≥0.30), partition filter, and response structure. No contradiction with annotations.

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

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

The description is comprehensive but somewhat verbose and could be more structured (e.g., separate sections). However, every sentence adds value and it is front-loaded with the requirement.

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

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

Despite lacking an output schema, the description thoroughly explains response fields (opportunities, partition_check, fill_check) and covers edge cases (similarity threshold, placeholder filtering, fill check). It is complete for such a complex 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?

Both parameters have schema descriptions, but the tool description adds significant context: examples of valid slugs, advice on when to use each, and details on what each mode does. This goes well 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, with two explicit modes (event and topic). It distinguishes itself from sibling tools like polymarket_fill_risk by referencing it only for custom sizing.

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

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

Provides explicit guidance on when to use each mode: event mode for a specific market, topic mode for cross-event scanning. It also warns that calling with no args fails and references an alternative tool for custom sizing.

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, so the tool is clearly non-destructive. The description goes far beyond this by detailing the three model families, edge calculation (edge_pp_net after slippage, kelly fractions), filtering knobs (min_liquidity, max_spread_pp), response diagnostics, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and a 24h-move warning. This provides deep transparency into how the tool operates and what callers can expect.

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

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

The description is well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and bullet-like formatting. It front-loads the core purpose and then provides detailed explanations. However, it is quite verbose with long paragraphs and some redundant phrasing (e.g., detailed model explanations could be shorter). It earns its length given the complexity but could be tightened slightly.

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

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

With 9 parameters, no output schema, and complex nested response structure, the description is remarkably complete. It explains the entire output hierarchy (by_segment, fed_candidates, diagnostics), including diagnostic details like funnel counters and filter_skips. It also covers edge cases (Fed bets excluded from ranking, placeholder-slug filters) and caching. An AI agent has all needed context to invoke this tool and interpret its results without additional documentation.

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 100% of parameters, so baseline is 3. The description adds significant value beyond the schema by providing usage suggestions (e.g., 'Set to 2 to require tight books' for max_spread_pp, 'Skips opportunities that are too small to bet sensibly' for min_kelly), explaining how parameters interact (e.g., min_kelly vs min_partition_leg_kelly), and offering context on Polymarket fees. This extra detail meaningfully aids an AI agent in selecting and invoking parameters correctly.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with explicit segmentation into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx's proprietary signals and providing a comprehensive edge-scanning interface. The verb 'scan' and resource 'Polymarket markets' are specific and 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 the tool is 'Built for "what should I bet on today"' and that agents can 'discover opportunities without paging hundreds of markets.' This provides clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives like polymarket_arbitrage or polymarket_fill_risk, leaving room for potential confusion. Nonetheless, the guidance is strong and actionable.

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

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

Annotations already declare readonly and idempotent. The description adds valuable behavioral context: data history is bounded by a 60-day TTL, decay numbers are from daily closes (not intraday), and gaps exist when no scan occurred. No contradiction with annotations.

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

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

The description is relatively long but well-structured, with a clear breakdown of the response fields (tracked, expired, snapshot_dates). Each sentence serves a purpose, though some redundancy exists with parameter defaults.

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?

Without an output schema, the description fully explains the return format: tracked arrays with time-series and trend metrics, expired array with lifespan, and snapshot dates. It also covers edge cases like data gaps and TTL limits, making it self-contained.

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

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

Schema coverage is 100% for both parameters. The description repeats the default and max for 'days' and the default for 'window', but does not add significant new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and whether it's shrinking. This effectively distinguishes it from the sibling 'polymarket_edges' tool, which likely provides raw edge 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 implies usage context by contrasting fresh vs. old edges, suggesting this tool helps assess edge longevity before trading. However, it does not explicitly mention when not to use it or name alternative tools like 'polymarket_edges' for simple edge queries.

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

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

The description discloses behavior beyond annotations: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, and a verdict (clean|degraded|cannot_fill). It also mentions forced_directional_risk for basket mode. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false).

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 sections for single-market and basket modes. Every sentence adds value, covering requirements, defaults, return fields, and warnings. A slight reduction could improve conciseness, but the detail is justified given the tool's complexity.

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

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

Given the complexity of the tool (two modes, four parameters, no output schema), the description is remarkably complete. It explains return fields for both modes, covers edge cases like partial fills and thin books, and addresses risks. No output schema means the description must carry the full burden, which it does thoroughly.

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

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

The description adds significant meaning beyond the input schema: it explains that one of market or event is required, details side defaults and interpretations for each mode, clarifies size_usd for buys vs sells, and notes clamping (10-1,000,000). The schema already has descriptions, but the description enriches them substantially.

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

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

The description clearly identifies the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools polymarket_arbitrage and polymarket_edges, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also explains why (theoretical overround not capturable, partial fills create directional risk), providing clear usage boundaries.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details safety fields like compatibility_warning with two cases, temporal_alignment, and skipped_cross_type/subtype counters. It honestly states that real spreads are rarer than macro shortcuts suggest.

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

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

The description is well-structured with clear headings (TWO MODES, RESPONSE, SAFETY FIELDS) and very informative, though somewhat verbose; could be slightly trimmed without losing value.

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

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

No output schema exists, so description fully explains the response format (leg-by-leg prices, matched spread, safety fields) and temporal alignment. It covers all necessary context for agent to understand tool behavior and output.

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

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

With 100% schema coverage, the description adds significant meaning: explains that topic parameter provides 10 pre-mapped shortcuts, and that explicit tickers override the topic side. Gives example values and clarifies mutual exclusivity.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on two-venue comparison.

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 two modes (topic shortcuts vs explicit tickers), clarifies when spreads are meaningful ('when the bet shapes are equivalent'), and warns that most pre-mapped topics return compatibility warnings, guiding the agent to expect limited tradeable results.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds scoping detail: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID),' which goes beyond annotations.

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

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

Three sentences, front-loaded with action, no superfluous words. 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?

Given the simplicity (1 param, no output schema, annotations present), the description fully covers behavior: retrieval vs listing, scoping, and pairing with related 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%, and the description echoes the schema's note omitting the key lists all keys. Little additional parameter meaning is added beyond what schema provides, earning a baseline score.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument),' providing a specific verb and resource. It distinguishes from siblings 'remember' and 'forget' by explicitly naming them.

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

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

Description explains when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions pairing with 'remember' and 'forget' as alternatives, but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral insight: the mark_read parameter flags events read, affecting subsequent calls (changing state). It also mentions that polling is safe and provides an external endpoint, going beyond annotation information.

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

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

The description is concise, with about 5 sentences covering purpose, returned fields, filtering, mark_read behavior, and alternative access. No redundant information; 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 lack of an output schema, the description sufficiently explains what is returned (source, citation_uri, raw payload). It covers filtering, mark_read behavior, polling suitability, and an external alternative. The tool's complexity is well-addressed.

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

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

Schema coverage is 100% with brief descriptions. The description adds meaning by explaining that 'type' filters subscription type, 'since' expects an ISO timestamp, 'limit' caps at 200, and 'mark_read' flags events as read. It also describes return fields, enriching the 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly stating what the tool does. It details the returned fields (source, citation_uri, raw event payload) and filtering options, distinguishing it from siblings like list_subscriptions by focusing on event retrieval.

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

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

The description provides context on when to use the tool ('Polls work fine') and explicitly notes an alternative: the same feed is available at a direct URL for scripts and dashboards. It mentions filtering by type and since, but does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: fan-out to multiple data sources with fallback, soft-fail for USPTO, accepted date formats, and return structure (changes grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is comprehensive and front-loaded with purpose and examples. It is slightly long but necessary given the tool's complexity. Could be slightly more structured but is still highly 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 tool's complexity (multiple sources, date handling, fallbacks) and no output schema, the description provides enough context about returns (changes grouped by source, total_changes, citation URIs), fallbacks, and PatentsView sunset. It is complete.

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

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

Schema description coverage is 100%, and the description adds additional context: explains 'since' format with examples, mentions that 'value' accepts ticker or CIK, provides guidance on typical monitoring ('30d' or '1m'), and describes the enum for 'type'. Adds value beyond schema.

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

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

The description clearly states the tool returns a change feed for a company (SEC filings, news, patents) for a given time window. It provides example queries and distinguishes itself from the sibling tool 'entity_profile' which is for static profiles.

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

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

The description explicitly says to use 'entity_profile' for static profiles, provides usage examples, explains parameter formats, and notes fallback behavior (GDELT to GNews). It gives clear guidance on when to use this tool versus alternatives.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds critical behavioral details: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This goes beyond annotations without contradiction.

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

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

The description is concise and well-structured: starts with core purpose, then usage guidance, then technical details. Every sentence is informative, 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?

For a simple tool with 2 parameters and no output schema, the description is fully complete. It covers purpose, usage, behavior, retention policy, and sibling relationships.

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

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

With 100% schema description coverage for both parameters, the baseline is 3. The description adds value by contextualizing 'key' and 'value' as a pair and providing example keys, but it largely reiterates schema examples.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It specifies the verb (save) and resource (data/memory) and distinguishes from sibling tools like recall and forget.

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

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

The description provides clear usage guidance: 'Use when you discover something worth carrying forward...' and mentions pairing with 'recall' and 'forget'. It lacks explicit when-not-to-use but effectively covers context and alternatives.

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

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

Beyond readOnly, idempotent, and open-world hints, the description reveals internal cascading lookups and that it replaces 2-3 manual calls. It fully describes output for each type, adding behavioral context the annotations don't cover.

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 efficiently structured: opening with example queries, then usage priority, then detailed type-specific behavior. Every sentence adds value, and the important directive is front-loaded.

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

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

Without an output schema, the description thoroughly covers return values for both types (ticker, CIK, RxCUI, citation URIs) and explains it replaces multiple lookups. This fully addresses the tool's moderate 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%, but the description enriches both parameters: 'type' gets enumeration context, 'value' gets input formats per type (e.g., 'AAPL', '0000320193', or name for company) and mentions auto-disambiguation for company names, going 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 resolves user-spoken names to canonical identifiers, exemplified by queries like 'What's the ticker for…'. It distinguishes from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID', which sets it apart from profile or comparison tools.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID', providing a clear decision rule. It details supported types (company, drug) with input formats, further guiding proper usage without 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?

Annotations already declare read-only, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check and returns ranked results with scores, confidence, and signal density. No contradictions; adds 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?

Three sentences, front-loaded with main action. Every sentence adds value: purpose, mechanics, use case. No wasted words; well-structured for quick parsing.

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

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

No output schema, but description fully covers return structure (ranked list with score, confidence, signal density). Explains internal process (probing with ai_visibility_check) and usage context. Complete for a comparison tool with rich annotations.

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

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

Schema coverage is 100%, but description adds key semantic details: first entity is treated as 'subject', models parameter has free default and usage note, explains that context disambiguates common names. These enrich understanding beyond bare 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 compares AI visibility across multiple entities side-by-side, using specific verbs ('compare', 'probes', 'ranks') and resource ('AI visibility'). Distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (different comparison type).

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') with an example query. Lacks explicit when-not-to-use or alternatives, but the context is strong enough for an agent to infer appropriate 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?

Discloses partial failure behavior, 5-30s delay for first bundlephobia measurement, and graceful degradation via sources_failed. 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?

Dense but well-structured: purpose first, then mechanism, usage, scope, behavior. Every sentence earns its place; 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?

Without output schema, description fully specifies return values (summary block fields, per-advisory detail, links, alternative versions). Also covers ecosystem, performance, failure modes.

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 fully describes both parameters (package, version). Description adds scoped package acceptance detail but essentially repeats schema info. Baseline 3 is appropriate.

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

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

Clearly states composite check for 'should I add this npm package' in one call, listing specific data sources (deps.dev, bundlephobia) and output fields. Distinct from all 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?

Explicitly says when to use (agent asks about safety/popularity/size/cost) and notes NPM-only in v1 with alternatives for other ecosystems (deps.dev:version directly).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable behavioral context: coverage of 140+ jurisdictions and the returned fields. No contradictions.

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

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

Three concise sentences with no filler. Front-loaded with purpose and output, then scope, then example. 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 low complexity (2 params), rich annotations, and existence of output schema, the description is complete. It covers purpose, scope, output fields, and example usage. No missing elements.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces with an example but adds no new semantic meaning beyond what the schema provides. Baseline score is appropriate.

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

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

The description clearly states the verb (search), resource (global company registries), and specific output fields (name, jurisdiction, status, type, incorporation date, address). Distinguishes from siblings like get_company (specific lookups) and search_officers (different entity).

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 by specifying it searches by name and includes an example. Implicitly guides usage against get_company (detailed lookup). No explicit when-not-to-use, but the example and scope are sufficient.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds value by specifying the exact return fields (officer name, position, company, dates, nationality), which goes 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 extremely concise: two sentences plus an example. Every word adds value, and the structure is clear and front-loaded.

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

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

For a single-parameter, read-only search tool, the description provides sufficient context. The output schema exists (not shown but implied) and annotations cover behavioral aspects. No additional details are needed.

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

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

The single parameter 'query' is fully documented in the schema with a description and example. The tool description reinforces the parameter's purpose without adding new information. With 100% schema coverage, this is an adequate 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 tool searches for company officers and directors by name, and lists the specific fields returned. It distinguishes itself from sibling tools like search_companies, which search for 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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., search_companies, search_within). The use case is implied by the name and description, but clearer directives would improve 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 safe read-only and idempotent behavior. The description adds valuable technical details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and return structure (passages with offsets and similarity scores). No contradictions with annotations.

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

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

The description is concise and well-structured: front-loaded with purpose, then usage guidance, then technical implementation. Every sentence adds value, and there is no redundancy. Approximately 110 words, efficiently covering all essential aspects.

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 a semantic search tool with no output schema, the description fully explains the purpose, when to use, technical details (embeddings, windowing, limits), return value (passages with offsets and scores), and suggested workflow pairing. An AI agent has all necessary information to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for each parameter (e.g., 'text' examples: SEC 10-K body, article; 'query' examples: supply-chain risk, fiscal year 2024 revenue), and clarifies that 'limit' returns top-N passages. This adds meaningful context beyond the schema.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, using specific examples like SEC 10-K body or article. It effectively distinguishes the tool from siblings by explaining that it is for searching within already-fetched text, contrasting with gateway fetchers or grounded QA tools.

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

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

The description explicitly states when to use: when the record is too big for the prompt. It also mentions pairing with ask_pipeworx_grounded for a workflow. However, it does not explicitly mention when not to use or compare with all alternatives, but the context is clear enough for an AI agent to decide.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: requires OAuth account, not for anonymous/BYO, type-specific configurations, delivery channel limitations, webhook signing secret returned once, auto-disable after 10 failures. No contradictions.

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

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

The description is well-structured, front-loaded with the main action, and organized into types and delivery sections. Every sentence contributes value, with no redundancy. Length is appropriate 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?

Despite no output schema, the description states the return value ('Returns the new subscription id'). It covers all parameter details, behavioral caveats, delivery channel options, and constraints. For a 3-parameter creation tool with nested objects, this is complete.

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

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

Schema coverage is 100%. The description adds meaning beyond schema by providing type-specific examples (e.g., sec_8k with ticker and items, polymarket_edge with topic), clarifying parameter constraints (phone must match verified), and explaining delivery options with detailed behavior (e.g., webhook HMAC signing).

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 creates a proactive monitoring subscription to a live-data event stream. It uses a specific verb ('Create') and resource ('proactive monitoring subscription'), distinguishing it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear context for when to use the tool (proactive monitoring), includes prerequisites (Pipeworx OAuth account, phone verification for SMS), and details delivery options with limitations (10/day SMS cap). It lacks explicit when-not-to-use or alternative tool mentions, but the context is sufficient.

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

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

Annotations already mark it as read-only, idempotent, etc. The description adds context: it uses a live catalog, returns structured examples with tool shapes, and can be focused by topic. No contradiction with annotations.

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

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

The description is informative but slightly verbose with multiple alternative triggers. However, it is well-structured, front-loading intent and usage. 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 no output schema, the description explains what the tool returns (category-bucketed questions with tool+argument shapes) and how to use it. Also includes usage context. It is complete for a simple tool with one optional parameter.

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 examples and context ('focus') to the optional topic parameter, but the schema already explains the values. Minimal added value.

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: it returns category-bucketed example questions with exact tool+argument shapes from a live catalog. It distinguishes itself as the onboarding entry point for new agents, different from sibling tools like discover_tools.

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

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

Explicitly says to use it 'FIRST when you do not yet know what Pipeworx can do' and describes calling without or with a topic. However, it does not explicitly state when not to use it or compare directly to alternatives like discover_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?

Adds value beyond annotations by stating that the subscription is deactivated (not deleted) and that historical events remain available. Consistent with idempotentHint and destructiveHint.

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

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

Two sentences, no wasted words, front-loaded with the primary action. Highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently covers purpose, usage constraints, and behavioral side effects.

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

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

Only one parameter 'id' with schema description covering its source. Description adds no additional meaning beyond the schema, which has 100% coverage.

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

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

Clearly states 'Cancel a subscription by id,' using a specific verb and resource. This distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions.'

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

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

Provides clear context: ownership enforcement means only own subscriptions can be canceled. Does not explicitly state when not to use, but the deactivation behavior is explained, hinting at alternative actions if full deletion is needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return format (verdict categories, structured form, citation, percent delta) and the data source (SEC EDGAR + XBRL). It also mentions it replaces multiple sequential calls, which is useful 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 efficiently front-loaded with query examples and a clear purpose. It is concise, with no redundant information, and every sentence adds value. Slightly longer due to the efficiency note, but still 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 single parameter and lack of output schema, the description fully covers what outputs to expect (verdict, structured form, citation, percent delta), the domain of claims supported, and an efficiency benefit. It is complete for an agent to understand the tool's capabilities.

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

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

The input schema covers 100% of parameter documentation, providing a good description and examples. The tool description does not add additional detail about the parameter beyond what is in the schema, so it meets but does not exceed the baseline of 3.

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

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

The description starts with clear natural-language query examples ('Is it true that...', 'fact check', etc.) and explicitly states it is for verifying factual claims against authoritative sources. It distinguishes itself from sibling tools like deep_research and compare_entities by focusing on claim verification.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the current limitation to company-financial claims, providing context on when it is applicable. While it doesn't explicitly state when not to use, the specificity gives adequate guidance.

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