Feeds

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds critical behavioral context: it probes multiple models, returns per-model data including raw responses, and requires the user to pass their own API key for Anthropic (with direct payment). 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 four sentences long, front-loaded with the main purpose and result, then provides details on defaults, optional parameters, and return structure. 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?

With 4 parameters (1 required) and no output schema, the description gives enough detail: it explains what the tool returns (per-model fields and combined view). It covers all parameters and provides context for their use. No gaps noted.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models' parameter and clarifying that '_apiKey' enables Anthropic and is passed directly. It also explains 'context' helps disambiguate, which is not in the schema.

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

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

The description uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility 0-100'). It clearly defines the entity parameter and lists use cases like AI-marketing audits and brand checks. It differentiates from siblings by its focus on a single entity's visibility, whereas 'scan_competitor_ai_presence' likely targets competitors.

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

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

The description explicitly states when to use the tool (e.g., pre-launch brand checks, competitive monitoring) and explains default behavior (Workers AI) and optional Anthropic probe. However, it does not explicitly mention when not to use it or compare with similar sibling tools like 'scan_competitor_ai_presence', which is a minor gap.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds that the tool works on every tier, is fast, returns structured answers with citations, and routes to appropriate tools. No contradiction with annotations.

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

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

Description is front-loaded with the key recommendation, then explains functionality, provides examples, and transitions to sibling tools. Every sentence is necessary and well-organized, despite length.

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

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

Given the tool's complexity (many siblings, no output schema), the description covers purpose, usage, expected output (structured answer with citation URIs), and examples, making it complete for agent invocation.

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

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

Schema has 100% coverage with descriptions indicating all parameters are aliases for 'question'. The description adds value by providing examples and clarifying the natural language request format, enhancing 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?

Description explicitly states that the tool routes questions to 4,552 tools across 1,160 verified sources and returns structured answers with citation URIs. It distinguishes from siblings like ask_pipeworx_grounded and deep_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?

Provides clear guidance: 'START HERE for most questions' and 'Step up only when needed' with specific alternatives for hallucination-resistant answers (ask_pipeworx_grounded) or broad queries (deep_research). Also instructs to prefer over web search.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds behavioral details like hallucination resistance, extra LLM call cost, return format with evidence and refusal reasons. These additions are valuable but not essential given annotations.

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

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

The description is moderately long but well-structured. It starts with the core purpose and then provides detailed behavioral and usage information. Every sentence adds value, though could be slightly more concise.

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

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

Given the tool's complexity (6 parameters, no output schema), the description covers purpose, usage, behavior, return format, refusal reasons, and cost trade-off comprehensively. It is complete enough for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional semantic meaning beyond what the schema provides (parameter aliases and natural language description). 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 defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by noting extra cost and preference for casual lookups. It specifies the verb (extract answer) and resource (tool results).

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: high-stakes reads where answers will be quoted, cited, or acted on (financial, legal, medical, public statements) and when not to use: casual lookups (prefer ask_pipeworx). Provides 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing internal behavior: fan-out logic, classifier categories, response shapes with warnings (24h move, wide spread), resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market blocking), and resolution-rule risk. This comprehensive disclosure clearly explains what the tool does under the hood.

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 section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and bullet-like formatting. Every section adds necessary details for a complex tool. However, it could be more concise; some parts like the detailed fan-out examples could be summarized. Overall, it is appropriately structured for a research tool with many facets.

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 (multiple classifiers, fan-out to data sources, various response fields including warnings and error conditions), the description covers all essential aspects: inputs, output shapes, error handling (low-confidence match, closed market, wide spread, resolution rule risk), and even examples for different bet types. Without an output schema, the description fully explains return values and usage context.

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

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

The input schema already covers 100% of parameters with descriptions and an enum for depth. The description adds further clarity by explaining the 'market' parameter accepts slugs, URLs, or question text, and the 'include_raw' parameter's impact on response size. The examples in the schema are also helpful. This provides additional context beyond the schema, justifying a 4.

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

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

The description begins with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which clearly states the verb (research) and specific resource (Polymarket bet via Pipeworx data). It distinguishes from sibling tools by focusing on Polymarket betting research, while siblings like 'ask_pipeworx' or 'deep_research' have different scopes.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides when-not-to-use scenarios via blocking conditions like low-confidence matches and closed markets. However, it does not mention alternatives among the sibling tools or when to prefer them over this tool.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + 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 densely packed with useful information but is a single long paragraph. It front-loads common query patterns, making it efficient. Minor improvement could be breaking into sections.

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 comprehensively covers inputs, behavior, output format (paired data + citations), data sources, and sorting. No missing elements for a tool with 2 parameters.

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 descriptions are generic. The main description adds rich semantics: for 'type', it details exactly what financials (revenue, net income, cash, debt) or drug counts are pulled. For 'values', it specifies tickers/CIKs for companies and drug names for drugs.

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 in one call, with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from siblings by explicitly preferring over sequential single-entity lookups.

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

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

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Lists example queries (e.g., 'which is bigger', 'head to head') that signal when to use.

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

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

Annotations already indicate readOnlyHint=true. The description adds detailed behavioral context: decomposes questions into facets, routes to parallel tools, never invents, returns gaps[], latency 15-60s, and account limitations. 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 thorough but front-loaded with critical info (account requirement, alternative). Every sentence adds value, though slightly verbose. Could be condensed slightly without losing clarity.

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

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

Despite no output schema, the description fully covers return values (findings packet with evidence, confidence, source, citation, gaps). Also addresses edge cases (empty gaps for topics not in catalog) and expected latency. Complete for the tool's complexity.

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

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

Schema coverage is 100%. Description adds significant meaning: depth enum maps to number of facets (quick=3, standard=5, thorough=8), question parameter is clarified as natural language and suited for broad/multi-part queries. 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 it performs grounded multi-source research across structured data sources in one call, distinguishing it from ask_pipeworx (single lookup) and open-web search. It specifies the output (findings packet with citations and gaps) and best use cases.

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

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

Explicitly provides when to use (broad/multi-part questions over structured data) and when not to use (breaking/current news, single lookups). Directs to ask_pipeworx as alternative for those cases. Also notes account requirements and paid plan for 'thorough' depth.

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, so the tool is safe. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context beyond annotations.

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

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

The description is front-loaded with purpose, followed by examples and usage instruction. It is concise but could be shortened slightly without losing meaning. Every sentence contributes value.

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

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

Despite no output schema, the description explains what is returned (names, descriptions, schemas, ready to call) and the limit (top-N). It covers the essential context for an agent to use the tool effectively.

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

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

Schema coverage is 100% with all parameters described. The description provides example queries and notes aliases, adding marginal value over the schema. Per rubric, baseline is 3 when coverage is high, and the description does not exceed that.

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 'Find tools by describing the data or task,' providing a specific verb and resource. It lists many concrete examples (SEC filings, financials, FDA drugs, etc.) and explains the tool's role as a discovery mechanism. This clearly distinguishes it from siblings like 'deep_research' or 'validate_claim' which are for specific tasks.

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

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

The description explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives clear when-to-use guidance. While it doesn't state when not to use, the positive framing is sufficient for an exploration tool.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: it fans out across multiple sources in parallel, returns specific data (CIK, filings, fundamentals, patents with sunset note, news via GDELT→GNews fallback, LEI). It also discloses the USPTO API sunset limitation and name-not-supported constraint, going well beyond annotation hints.

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 dense paragraph but front-loads examples and purpose. It packs a lot of information efficiently, though a bulleted list of return fields would improve scanability. No wasted words, but structure could be tighter.

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

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

For a tool with 2 parameters and no output schema, the description is remarkably complete. It explains what each parameter accepts, the scope (US public company), which sources are used, what data is returned (including URIs for filings), known limitations (USPTO sunset, name rejection), and fallback behavior. No gaps remain for an agent to select and invoke correctly.

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

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

Input schema covers 100% of parameters with descriptions. The description reinforces the meaning of 'value' (ticker or zero-padded CIK) and 'type' (currently only company), and clarifies that names are not accepted. This adds practical nuance beyond the schema (e.g., the CIK format, restriction to company type), making it more helpful for correct invocation.

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

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

The description clearly states it provides a full cross-source profile of a US public company, listing specific data sources and return fields. It distinguishes from siblings like resolve_entity (for name resolution) and deep_research (for deeper analysis), and gives examples of natural language queries that trigger this 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?

Explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and notes that for names (not tickers/CIKs), users should use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's mention of deletion aligns. No contradictions, but the description adds no extra detail 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?

Two concise sentences: first states the action, second provides usage guidance and links to related tools. 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 a single required parameter, good annotations, and no output schema, the description fully covers what the agent needs to know: purpose, when to use, and relationship to siblings.

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

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

Schema coverage is 100% with a good description for the key parameter. The description does not add meaning beyond the schema, so 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 action (delete) and resource (memory by key). It distinguishes itself from siblings like remember and recall by specifying it is the deletion operation.

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

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

Provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with remember and recall.

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

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

The description adds behavioral context beyond annotations by explaining the internal process: fetching the page, extracting title/description/key links, and emitting standard markdown. It also clarifies that the output is a single text blob. This complements the annotations which already indicate read-only, idempotent behavior.

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

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

The description is three sentences: first states purpose and output, second explains process, third lists use cases. It is front-loaded with the most important information and contains no unnecessary words. Every sentence adds value.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers essential aspects: input (URL), process (fetch and extract), and output (text blob). It mentions default max_links via schema. Minor gaps like error handling or network requirements are acceptable for a straightforward read-only tool.

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

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

Schema coverage is 100% with both parameters well-described. The description does not add new meaning beyond the schema, only reinforcing the purpose of the url and hinting at link count. Baseline score 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 that the tool generates a production-ready llms.txt file for any URL, which is a specific verb-resource combination. It distinguishes itself from sibling tools by focusing on llms.txt generation for AI crawlers, a unique capability not offered by other tools in the list.

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 use cases: getting a client's site indexed, drafting llms.txt, or auditing competitor sites. While it does not mention when not to use or alternatives, the clear use cases effectively guide an agent on appropriate scenarios.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description adds context by specifying that it lists the caller's subscriptions and the default active-only behavior, enhancing transparency.

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

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

The description is concise with three sentences: one for purpose and output, one for usage guidance. No unnecessary words, front-loaded with key information.

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

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

For a simple tool with one optional parameter and no output schema, the description provides sufficient context: purpose, output fields, default behavior, and usage guidance. It is complete enough for effective use.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). The tool description does not add new parameter details but reinforces the default 'active subscriptions' behavior, meeting the baseline.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the returned fields, differentiating it from siblings like subscribe and unsubscribe.

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

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

The description explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use it. However, it does not explicitly state when not to use it or compare to alternatives.

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

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

The description discloses rate limiting ('5 per identifier per day') and quota impact ('Free; doesn't count against your tool-call quota'). It also explains how feedback is processed (digests, roadmap influence). Annotations are all false, which is consistent with the description.

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, starting with the core purpose. At 6 sentences, it is appropriately sized but could be slightly more concise. Every sentence adds value, though some information (like rate limits) could be more compact.

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

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

The description covers all relevant aspects: when to use, what to include, constraints (rate limits, quota), and behavioral expectations. Given no output schema, it sufficiently explains the tool's operation and handles complexity well.

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 schema already provides detailed descriptions for all parameters. The description adds minimal additional semantics beyond the schema, such as context on when to use each type. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific types (bug, feature, data_gap, praise) and distinguishes it from sibling tools, which focus on research, AI visibility, etc.

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 the tool: for bugs, features, data gaps, and praise. It also provides guidance on what not to do ('don't paste the end-user's prompt'), and mentions rate limits and quota. This clearly differentiates it from other tools.

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

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

Annotations declare readOnly, idempotent, non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, caching (5min-1h). This goes beyond annotations and fully informs behavior.

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

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

Three concise, well-structured sentences. Front-loaded with main purpose, then use cases, then technical details. 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?

No output schema, but description mentions return fields (top tools, top packs, volume). For a simple 1-param tool with rich annotations, it is mostly complete. Missing exact return format, but sufficient for selection.

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

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

Schema covers the single parameter with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances meaning beyond the schema alone.

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

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

Clearly states it returns trending tools, packs, and call volume over a window. The verb 'returns' and resource 'top tools, top packs, total call volume' are explicit. Distinguishable from siblings like 'discover_tools' by focusing on aggregate usage 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?

Lists three explicit use cases (hot sources, canonical choice, alignment). While not stating when not to use or alternatives, the use cases provide clear context for appropriate invocation. Sibling differentiation is implied through the unique aggregative purpose.

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

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

The description explains algorithms (monotonicity, partition checks), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check (CLOB depth). Annotations indicate read-only, idempotent, open-world, and the description aligns perfectly, adding significant behavioral context beyond the annotations.

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

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

The description is long but well-structured: front-loaded purpose, then modes explained with clear labeling. Every sentence serves a purpose, though some technical details (e.g., Jaccard threshold) could be more succinct. Still, it's efficient for a complex tool.

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

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

Despite no output schema, the description thoroughly explains response fields (opportunities[], partition_check, fill check results) and edge cases (placeholder filters, low similarity). It also references sibling tools, making it complete for a tool with two optional parameters and 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?

Input schema has 100% coverage with good descriptions, but the description adds substantial value: recommends event mode for specific markets, provides example slugs, explains the difference between event and topic modes, and details the response structure. This far exceeds 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct modes (trending scan, event mode, topic mode), each with a clear purpose, and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending, event for specific market, topic for cross-event scanning. It also explains when not to trade (fill check) and references sibling tools for custom sizing. This provides comprehensive 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 indicate a safe, read-only operation. The description goes far beyond that, detailing caching (1h KV-level), model families (e.g., crypto_price, news_momentum), edge calculation (slippage, Kelly fractions), 24h move warnings, and diagnostics. This comprehensive disclosure surpasses the minimal requirements.

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 excessively long (over 250 words) with detailed exposition on model formulas, segments, and filter logic. While structured with clear sections, it could be condensed significantly for faster agent parsing. The core purpose is front-loaded, but the verbosity reduces overall conciseness.

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

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

Despite having no output schema, the description fully describes the response structure (by_segment, fed_candidates, _diagnostics) and explains edge cases like empty segments and filter_skips. Given the tool's complexity (9 parameters, no output schema), the description provides complete context for an agent to understand inputs, behavior, and outputs.

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

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

All 9 parameters are fully described in the input schema (100% coverage). The description adds value by explaining how knobs like min_liquidity and max_spread_pp filter opportunities and how min_partition_leg_kelly operates differently from min_kelly. This contextualizes parameters beyond their schema descriptions.

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

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

The description starts with a precise verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's output and distinguishes it from sibling tools like 'polymarket_arbitrage' by focusing on Pipeworx disagreement and daily bet discovery.

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 the tool is for 'what should I bet on today' and mentions alternative data limitations (e.g., fed_note excluded due to unreliable signals). It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for 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?

Annotations already declare readOnly, openWorld, idempotent, not destructive. The description adds significant behavioral context: details the response structure (tracked, expired, snapshot_dates), explains decay computation (from edge_pp_net daily closes, not intraday), and notes history depth bounded by 60-day TTL and snapshot gaps. 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: core purpose first, then response fields, then limitations. Every sentence adds value, no fluff. Length is appropriate 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 no output schema and moderate complexity, the description covers output structure, edge cases (expired, snapshot gaps), and limitations (60-day TTL, daily data). It provides sufficient information for an AI to understand what the tool returns.

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

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

Schema coverage is 100%, baseline 3. The description adds context: explains days as lookback (clamp 2-30, default 14) and window as snapshot family (with common values and default 1wk), and ties these to the tool's functionality. This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly formulates the question answered ('how long has this edge existed and is it shrinking?') and distinguishes between fresh and old edges, differentiating it from siblings like polymarket_edges.

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

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

The description provides implicit guidance on when to use the tool—for historical context of edge persistence—but does not explicitly state when not to use it or directly compare to alternatives. However, the context from sibling names and the clear differentiation in purpose aids selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds rich behavioral context: 'walks the ladder', returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and forced_directional_risk. 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 detailed but well-structured: front-loaded with purpose and requirements, then mode-specific details, then return fields, and finally usage guidance. Every sentence adds value. Slightly verbose but 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?

Given no output schema, the description comprehensively covers both modes, return values, and behavioral warnings (e.g., forced_directional_risk). It enables an agent to correctly invoke the tool and interpret results. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema: explains size_usd differently for single-market vs basket, default side auto behavior, and how return values relate to parameters. This is good but not exceptional.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from siblings like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on those signals.

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

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

Provides explicit instructions: 'REQUIRES one of market or event', explains single-market vs basket usage, describes default behaviors and size_usd interpretation, and gives a concrete threshold ('above ~$500') for when to use this tool before trading signals. Also warns about partial basket fills converting arb into unhedged positions.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds rich behavioral detail: two operational modes, compatibility warnings with specific triggers (bet shape mismatches, semantic mismatch, temporal misalignment), and counters for skipped comparisons. 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 information-dense and well-structured with clear sections, but it is somewhat long. Every sentence adds value, though the detailed enumeration of response fields might be streamlined. Overall, it is appropriately sized for the tool's complexity.

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

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

Despite the lack of an output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spreads, safety fields like compatibility_warning and temporal_alignment). Parameter coverage is complete, and the tool's complexity is fully addressed, making it complete for an AI agent.

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

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

The description supplements the 100% schema-covered parameters by explaining the interaction between topic and explicit tickers (topic sets defaults, explicit tickers override) and listing the pre-mapped topic values. This adds meaning beyond the schema descriptions, earning a 4.

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

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

The description clearly specifies the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains the two modes (topic shortcuts and explicit ticker pairing), which distinguishes it from siblings like polymarket_arbitrage that focus on internal 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 context for when to use each mode, warns that pre-mapped topics often yield compatibility warnings, and explains key response fields like compatibility_warning and temporal_alignment. However, it does not explicitly state when not to use this tool in favor of alternatives, leaving some guidance implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: scoping to user identifier and the ability to list all keys. 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?

Three sentences with no waste. The most critical information (purpose, usage, scoping) is front-loaded. 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?

For a simple lookup tool with good annotations and schema, the description covers purpose, usage, scoping, and relationships with siblings. No output schema exists, but the description implies the return value (the stored value or list of keys) which is sufficient.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description explains the effect of omitting the key (list all), but this is already in the schema description. Adds marginal value beyond what's in the schema.

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

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

The description specifies the verb (retrieve/list) and resource (saved values/keys), clearly distinguishing from sibling tools 'remember' and 'forget'. It states the tool's dual behavior: retrieving a specific key or listing all keys when omitted.

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

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

Explicit guidance on when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with 'remember' and 'forget' for a complete memory workflow.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description goes beyond by detailing what the tool returns (source, citation_uri, raw payload) and explaining the effect of mark_read:true on subsequent calls. It also implies idempotency by noting 'polls work fine.' 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 at three sentences, effectively front-loaded with the core purpose in the first sentence. Every sentence adds value: stating purpose, detailing filterable fields, explaining mark_read and polling suitability. No redundant or unnecessary information.

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

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

Despite lacking an output schema, the description adequately explains return values (source, citation_uri, payload) and covers all parameters. Combined with annotations that confirm read-only, idempotent, and non-destructive behavior, the tool is well-described for an agent to use correctly. The additional note about the HTTP endpoint provides completeness for alternative access.

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

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

All parameters have descriptions in the schema (100% coverage). The description adds value by providing an example for 'type' (e.g., 'sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the consequence of setting 'mark_read:true' (next call returns only newer events). This enriches the understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull events). The sibling list includes list_subscriptions which is related but different, and the description distinguishes by focusing on events from the feed, not the list of subscriptions. The purpose is 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 provides guidance on when to use the tool: it mentions that polling works fine, and it notes that the same feed is available via an HTTP endpoint for scripts and dashboards, offering an alternative. However, it does not explicitly state when not to use this tool versus siblings or other methods. The context is clear but lacks explicit exclusions.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable behavioral details: parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and output format. While annotations lower the burden, description still provides rich context.

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

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

One well-structured paragraph starting with example queries, then core function, sources, parameter details, output, and alternative tool. Every sentence adds value with no redundancy.

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

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

Given the complexity (multi-source fan-out, fallback, soft-fail), the description fully explains behavior, parameter formats, output structure, and distinguishes from sibling. Annotations cover safety. 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?

With 100% schema coverage baseline is 3, but description adds significant meaning: explains since accepts ISO dates or relative shorthand (e.g., '7d', '30d'), value can be ticker or CIK, and type enum limitation. This goes well 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's purpose as a change feed for a company, listing example user queries and summarizing core function. It also distinguishes from sibling tool entity_profile.

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

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

Explicitly provides usage context with example queries and directly advises when to use entity_profile instead ('Use entity_profile instead when you want the static profile...'), offering clear guidance on alternative.

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 behavioral context beyond annotations: scoping by identifier, persistence for authenticated users (permanent) vs anonymous (24 hours). No contradictions.

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

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

The description is concise (about 4 sentences), front-loaded with purpose. It is well-structured with no wasted words, though slightly verbose in explaining pairing.

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

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

Given the tool's simplicity (2 required params, no output schema), the description covers purpose, usage, behavioral traits (scoping, persistence), and mentions sibling tools. It is fully adequate for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds high-level context (e.g., examples for key like 'target_ticker') but does not significantly enhance parameter semantics beyond what schema provides.

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

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

The description starts with a clear verb and resource: 'Save data the agent will need to reuse later' and distinguishes from sibling tools like 'recall' and 'forget' by stating it is for storage that pairs with them.

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

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

The description explicitly states when to use ('when you discover something worth carrying forward') and provides guidance by mentioning paired tools for retrieval and deletion. No explicit when-not-to-use, but clear context.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds behavioral details: cascading through multiple lookup endpoints, replacing 2-3 manual lookups. 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?

Efficiently front-loaded with examples, but slightly verbose in listing return details. Still, every sentence adds value and 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?

Comprehensive coverage of both entity types, internal behavior, and return values despite no output schema. Sufficient for an agent to use correctly without additional context.

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

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

Schema coverage is 100%, and the description adds significant meaning: details return fields per type (ticker, CIK, RxCUI, etc.) and auto-disambiguation, far beyond the schema descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, using specific verbs like 'resolve' and examples for each entity type. It distinguishes from siblings by focusing on identifier lookup.

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 'Use FIRST whenever you have a name but need an ID.', providing clear when-to-use guidance. However, it does not explicitly mention when not to use it or contrast with specific sibling tools like entity_profile.

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 state the tool is read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: it probes each entity, ranks by score, and returns a list with score, confidence, and signal density. This aligns with the annotations and provides context beyond them.

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

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

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

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

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

No output schema exists, but the description explains the return format (ranked list with score, confidence, signal density). For a tool with 4 parameters and a clear action, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by stating the first entity is treated as the 'subject' for narrative, which the schema does not convey. The other parameters (models, _apiKey, context) are not elaborated beyond the schema, but this added nuance justifies a 4.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It distinguishes from siblings like ai_visibility_check (a probe to check a single entity) and compare_entities (likely general 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 explicitly mentions the use case 'competitive AI-marketing audits' and provides an example question. However, it does not explicitly say when not to use or list alternatives among siblings, though it implies that for single entity checks, one should use ai_visibility_check 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 safe, read-only, idempotent behavior. Description adds critical details: partial failures degrade gracefully, bundlephobia first measurement latency (5-30s), sources_failed error reporting. No contradictions.

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

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

Two sentences, each dense with information. First sentence covers purpose and method; second covers usage, limitations, and output. No fluff, logically 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 fully details return structure: summary fields, per-advisory details, links, alternative versions. Also covers error handling and partial failures. Complete for decision-making.

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

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

Schema already describes both parameters (100% coverage). Description adds useful nuance: scoped package syntax accepted for package, default to latest version for version. Value-add beyond schema.

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

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

Description clearly defines a composite check for npm packages, specifying data sources (deps.dev, bundlephobia) and output fields. Differentiates from siblings by scope (NPM only) and specific use case ('should I add this package').

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

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

Explicitly states when to use ('when agent asks is X safe/popular/small'), hints at alternatives for non-NPM ecosystems ('fall under deps.dev:version directly'). Provides clear context for invocation.

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

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

Beyond annotations (readOnly, idempotent), the description discloses implementation details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and return format (passages with offsets and scores). No contradiction with annotations.

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

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

Front-loaded with core purpose, then usage, then technical details. Every sentence adds value, though the technical details could be slightly condensed. Efficient but not maximally concise.

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

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

Covers purpose, usage, behavior, return format, and pairing with a sibling tool. No output schema, but return elements are described. Lacks error handling details, but overall complete for a search tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context like the 200K cap in text and example queries for the query parameter, but the schema already covers defaults and limits. Extra value is moderate.

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 semantic search inside a fetched record, using specific verbs and resources. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching the whole document.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description adds significant behavioral details beyond annotations: account requirement, idempotent creation, delivery channels, webhook signing and auto-disable. Annotations (readOnlyHint=false, idempotentHint=true) are consistent and enhanced.

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

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

The description is front-loaded with purpose and covers all aspects, but it is lengthy. Every sentence adds value, but a more structured format (e.g., bullet list of types) could improve scannability.

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

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

Despite lacking an output schema, the description clearly states the return value (subscription id). It covers account prerequisites, all supported types, delivery options, and webhook protocol details. 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 coverage is 100% and descriptions already present, but the tool description provides richer context for each type (e.g., 'sec_8k' with item codes, 'polymarket_edge' with topic). This adds meaning beyond the schema.

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

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

The description starts with a clear verb-resource pair: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This distinguishes 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 states a prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It provides context but does not explicitly mention when not to use it or compare with alternatives like 'recent_alerts'.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by detailing that it returns category-bucketed examples from a live catalog, and that it is the onboarding entry point. No contradictions.

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

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

The description is a single dense paragraph, front-loaded with alternative user queries, and provides all necessary information without redundancy. Slightly longer than minimal but each sentence earns its place.

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

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

Given the tool's role as an onboarding guide, the description covers purpose, input parameter, output nature (example questions with tool shapes), and usage context. It is fully adequate even without an output schema.

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

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

The single optional parameter 'topic' has 100% schema coverage. The description expands by listing acceptable values (finance, pharma, etc.) and default behavior (cross-category spread when omitted), adding significant meaning.

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

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

The description clearly states it returns category-bucketed example questions with exact tool+argument shapes, serving as the onboarding entry point. It uses specific verbs and resources, and distinguishes from siblings by advising to use this first before meta-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 states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also specifies calling with no arguments or topic to focus, providing clear when-to-use guidance.

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

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

Annotations indicate mutation (readOnlyHint false), idempotency (true), and non-destructive (destructiveHint false). Description adds ownership enforcement and deactivation behavior, which are critical beyond annotations. No contradiction.

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

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

Two sentences, front-loaded with the core action. Every sentence adds value: cancel action, ownership, and effect on historical data. No waste.

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

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

Given a single required parameter and no output schema, the description covers the action, constraint, and side effect. Annotations cover safety aspects. Complete 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 parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' Description does not add extra semantics beyond stating 'by id', so score is at baseline 3.

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

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

Description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from sibling tools like subscribe (which creates) and list_subscriptions (which lists), and adds ownership enforcement and deactivation behavior.

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

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

Explicitly says 'Ownership is enforced — you can only cancel your own subscriptions', telling when to use. Also explains that the row is deactivated not deleted, implying when to expect historical data retention. Lacks explicit when-not-to-use, but provides solid 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 declare readOnly, idempotent, openWorld, non-destructive traits. Description adds specifics: returns verdict (confirmed/refuted/etc.), structured form, actual value with citation, and percent delta. Also notes version scope (v1 company-financial claims). 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 compact (~100 words), front-loaded with example triggers, and organized with scope, return details, and value proposition. Every sentence contributes to clarity without redundancy.

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

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

Despite no output schema, description thoroughly explains the verdict options and return structure. For a single-parameter tool with rich annotations, the description is complete, covering purpose, usage, behavior, and limitations.

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 for the single parameter 'claim' already covers the type and gives an example. Description reinforces with more natural-language examples and explains the parameter's role in claim verification, adding moderate value beyond the schema.

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

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

Description starts with clear example queries ('Is it true that...', 'fact check'), then states verb 'verify' against authoritative sources. Distinguishes the tool's focus on company-financial claims via SEC EDGAR, setting it apart from sibling research tools like deep_research or bet_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 says 'Use whenever the agent needs to check whether something a user said is factually correct.' Notes it replaces 4-6 sequential calls, indicating efficiency. Lacks explicit when-not-to-use or alternative tools, but sibling list provides implicit differentiation.

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