wikipedia

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 value by detailing the return structure (per-model and combined), noting that Anthropic calls require a BYO API key and that users pay Anthropic directly, and explaining the default model. This 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 three sentences long, front-loaded with the core purpose and output, then covering parameters and use cases. 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?

Despite lacking an output schema, the description fully explains what is returned: per-model objects with score, confidence, signals, raw_response, and a combined view. It also covers parameter behavior and typical use cases, making it complete for an agent to invoke correctly.

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

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

With 100% schema description coverage, the schema already documents each parameter. However, the description adds context about the default model for the 'models' parameter, the necessity of _apiKey for Anthropic, and how the 'context' parameter helps disambiguate. This enriches 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 clearly states the tool probes LLMs for knowledge about a subject and scores visibility (0-100). It gives concrete examples like 'Pipeworx', 'OpenInvoice', and specifies the output structure. This distinguishes it from sibling tools like 'ask_pipeworx' or 'compare_entities' which have different purposes.

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 explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use the _apiKey parameter (for Anthropic). However, it does not explicitly state when not to use this tool or provide direct comparisons to siblings, though the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds that the tool returns structured answers with stable citation URIs, which is useful context beyond the annotations.

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

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

The description is two sentences, front-loaded with the key usage preference. The second sentence is dense but informative. Minor verbosity could be trimmed, but overall well-structured and efficient.

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

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

Despite lacking an output schema, the description explains the return format (structured answer with citations) and the routing mechanism. For a tool with broad scope, this provides sufficient completeness for an agent to understand what to expect.

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

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

Schema coverage is 100%, all parameters are aliases for the same core parameter. Description clarifies that 'question' accepts natural language and lists aliases, but adds limited new meaning beyond the schema examples. 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's function: answering factual questions using structured data from many sources. It distinguishes from siblings with 'PREFER OVER WEB SEARCH' and provides specific use case categories (SEC filings, FDA data, 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?

Explicitly tells when to prefer this tool over web search, lists suitable query types and examples (e.g., 'current US unemployment rate'). Provides strong guidance on 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds rich context: return format (answer, evidence, confidence, source, fetched_at, refusal_reason), refusal reasons, and cost of one extra LLM call. 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 dense but well-structured: front-loaded purpose, then behavior, output, and usage. It is informative without being overly verbose, 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 param aliases, structured output, refusal reasons), the description covers purpose, behavior, output format, usage guidelines, and refusal reasons comprehensively, compensating for missing output schema.

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

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

Schema coverage is 100% with descriptions for each alias. The description does not add meaning beyond the schema; it merely repeats that question accepts aliases. 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers only from tool results, distinguishing it from its sibling ask_pipeworx. It uses specific verbs and resource (answer mode, high-stakes reads).

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 an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to guidance, including an 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?

The description goes far beyond the annotations (readOnlyHint=true, idempotentHint=true) by detailing behavioral traits: low-confidence resolution short-circuiting, closed market handling, wide-spread illiquid flag, cancellation rule parsing, news fallback mechanisms, and response shape. 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 very long (multiple paragraphs) but uses capital-letter headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) to structure information. While every section adds value, the sheer length reduces conciseness; a more distilled version could be more 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 complexity (3 parameters, no output schema), the description is remarkably complete. It covers input handling, classifier categories, fan-out examples, response shapes, resolver contract, parent event extraction, news fallbacks, safety mechanisms, and cancellation rule risks. No missing information.

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

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

Schema coverage is 100%, but the description adds significant value: explains market can be slug, URL, or question; clarifies depth parameter with examples; describes include_raw default and when to override. This enriches the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (a Polymarket bet), and input types (slug, URL, question text), distinguishing it from sibling tools like polymarket_edges or ask_pipeworx.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs for different bet categories. While it lacks explicit exclusions, the intended use cases are well-defined.

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 data sources (SEC EDGAR/XBRL for company, FAERS for drug), handling of off-calendar fiscal years, and that results are sorted by primary metric. No contradiction with annotations which mark it as readOnly and idempotent.

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 every sentence serves a purpose. Front-loaded with natural language queries. Efficiently packs purpose, usage guidance, behavior, and parameter details in a compact format.

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

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

Comprehensively covers the tool's functionality: entity types, data sources, number of entities, sorting, and return format (paired data + citation URIs). No output schema but description is sufficient for an AI agent to invoke correctly.

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

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

Adds significant meaning beyond the input schema: explains what data type='company' pulls (revenue, net income, cash, debt) and type='drug' pulls (adverse-event counts, FDA approvals, active trials). Provides concrete examples for 'values' parameter.

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

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

Description starts with common query patterns like 'Compare X and Y' and states it provides side-by-side comparison of 2-5 entities. It clearly distinguishes itself from siblings by recommending preference over sequential lookups.

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

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

Explicitly advises to 'ALWAYS PREFER' this tool over sequential single-pack lookups when comparing entities, giving clear context of when to use. It also specifies the number of entities (2-5) and types (company or drug).

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, non-destructive. Description adds substantial context: it never invents, returns explicit gaps for unanswered facets, provides verbatim evidence with citations, and details the parallel decomposition process. This goes beyond the annotations.

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

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

The description is well-structured and front-loaded. Each sentence adds value: core function, methodology, usage guidance, prerequisites, timing. No redundant or filler content, despite its 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 and lack of output schema, the description compensates by explaining the return value (structured findings packet with evidence, confidence, source, citations, gaps). Also covers timing, account requirements, and depth constraints. All necessary context is present.

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

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

Schema coverage is 100%, but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and notes thorough requires paid plan. For the question parameter, clarifies that broad/multi-part is acceptable.

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

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

The description clearly states the tool performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to thousands of sources in parallel. It distinguishes itself from sibling tools like ask_pipeworx by explicitly mentioning when to use each.

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

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

Explicitly says when to use the tool (broad or multi-part questions) and when to use alternatives (ask_pipeworx for single lookups). Also notes prerequisites (Pipeworx account, paid plan for thorough depth) and expected timing (15-60s).

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that it returns top-N most relevant tools with full input schemas and curated examples, ready to call directly. This provides significant behavioral context beyond annotations.

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

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

The description is a single paragraph that is informative and front-loaded. It could be slightly more structured (e.g., bullet points) but is concise and 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?

The description fully explains the tool's purpose, usage, behavior, and parameter semantics. It covers what the tool returns and how to use it, making it complete for a discovery tool with no 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 description coverage is 100% with descriptions for all parameters. The description adds value by explaining that 'query' accepts natural language, listing aliases, and providing examples. It complements the schema without redundancy.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and explicitly differentiates from siblings with 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools and want to see the option set.' It does not explicitly state when not to use, but the context implies it.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral details: fans out across multiple datasources, returns specific fields, mentions patent sunset and soft-fail, news fallback, and URI format for filings. 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 thorough but slightly verbose. It starts with example queries, then core purpose, then detailed breakdown. Could be tightened, but every sentence adds value. The structure is logical and 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?

Given no output schema, the description fully explains what the tool returns: cik, company_name, recent_filings with URIs, fundamentals, patents (with caveat), news (with fallback), LEI. It also mentions limitations like patent sunset. Completeness is excellent 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% with descriptions for both parameters. The description adds extra context: explains that type must be 'company', value can be ticker or CIK, and explicitly states names are not supported. Provides examples like 'AAPL' and '0000320193'.

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: generating a full cross-source profile of a US public company in one parallel call. It lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return items. It distinguishes from siblings like resolve_entity and encourages preference over chaining individual 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?

Provides explicit guidance on when to use: whenever a holistic view of a company is needed, preferring over chaining single-source lookups. Also specifies when not to use: if only a name is provided, advises using resolve_entity first. Includes example user queries to trigger the tool.

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

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

Description aligns with destructiveHint=true. Adds context about clearing sensitive data, but no additional detail on side effects beyond deletion.

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: action then usage. Front-loaded, 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?

Fully covers purpose, usage, and sibling context for a simple one-param delete tool. No missing info.

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 key with full description. Baseline 3 since description adds no extra parameter info beyond schema.

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

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

Clearly states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings like remember and recall.

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

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

Explicitly says when to use (stale context, task done, clear sensitive data) and pairs with remember and recall.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context (fetches page, extracts title/description/key links, emits markdown) but does not disclose additional behavioral traits like rate limits or response size. With annotations covering safety, a score of 3 is appropriate.

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

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

The description is two paragraphs with front-loaded verb and purpose. The second paragraph lists use cases, which is helpful but slightly verbose. Every sentence adds value, though it could be trimmed to one paragraph 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?

For a simple tool with 2 parameters, full schema coverage, and informative annotations, the description is complete. It explains purpose, input, output format, and use cases. No critical information is 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% with both parameters described. The description does not add meaning beyond what the schema provides (e.g., default and max for max_links are already in schema). Baseline 3 is correct.

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 ('Generate') and resource ('llms.txt file'), clearly stating what the tool does. It distinguishes itself from siblings by focusing on a distinct task (generating llms.txt for AI crawlers) that is not covered by other sibling tools like 'scan_competitor_ai_presence' or 'validate_claim'.

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: getting a client's site indexed, drafting for own project, auditing competitor visibility. This provides clear context. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds context about being cheap and structural-only, harmonizing with 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?

Three sentences cover purpose, usage, and key attributes. No redundant information; front-loaded with core function.

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, full annotation coverage, and output schema existence, the description provides complete guidance including behavioral traits and call patterns.

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 the 'title' parameter. Description does not add extra parameter details; 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 it returns the table-of-contents (headings and hierarchy) of a Wikipedia article by title, distinguishing it from sibling tools like get_article_summary.

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

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

Explicitly advises use when article is long and navigation is needed, and suggests chaining with get_article_summary for lead text.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds context: it is faster and cheaper than alternatives, returns specific content types. However, does not discuss edge cases like disambiguation or missing articles.

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, front-loaded sentences that immediately convey purpose and usage, plus a third sentence for alternative advice. No filler 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?

Completeness is high given the simple tool: one parameter, full annotations, output schema present. Description covers return value and use case 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?

Single required parameter 'title' with clear description and examples in schema (100% coverage). Description emphasizes needing the canonical title but adds little beyond the schema's documentation.

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

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

Description clearly identifies the tool as returning an authoritative Wikipedia article summary with specific content (lead paragraph, description, thumbnail, links). Distinguishes from sibling tools like search_wikipedia and get_article_sections.

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 you already have the canonical title and need the standard 'what is X' answer. Names alternatives: search_wikipedia for finding titles, get_article_sections for full breakdown.

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

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

Description specifies return fields (title, intro, page ID), complementing annotations that declare read-only, idempotent, open-world 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?

Two efficient sentences, front-loaded with purpose and return data.

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?

Sufficient for a simple, well-annotated tool with output schema; 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 description covers count parameter fully (1-10, default 5). Description adds no extra meaning beyond schema.

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

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

Clear verb 'Discover' and specific resource 'random Wikipedia articles' with return types. Distinguishes from siblings like 'search_wikipedia'.

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?

No explicit when-to-use or alternatives, but context implies serendipitous discovery vs targeted 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return field list and default 'active' behavior but no major behavioral insight 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 concise sentences: one for what it does and returns, one for usage guidance. No extraneous text.

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 read-only tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage. No missing 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% for the single parameter (include_inactive). Description reinforces default behavior but adds no new meaning beyond schema.

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

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

Clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). Distinguishes 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?

Says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use. Implicitly excludes other actions but lacks explicit mention of alternatives.

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

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

Annotations already indicate non-readonly and non-destructive, and description adds important behavioral details: rate limit of 5 per identifier per day, that it's free and doesn't count against quota, and that feedback affects roadmap. 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?

Description is concise and well-structured: first sentence states purpose, second provides usage categories, third gives constraints and behavioral notes. Every sentence earns its place with no redundancy.

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

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

Given the tool's simplicity (3 params, no output schema), the description is fully complete: covers purpose, when to use, parameter tips, behavioral constraints, and team response. Nothing relevant is 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%, so baseline is 3. The description provides extra guidance on parameter usage, such as instructing users to be specific, keep messages to 1-2 sentences, and avoid pasting prompts. This adds value beyond schema.

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

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

Description clearly states the tool's purpose: sending feedback about bugs, features, data gaps, or praise. It specifies the resource (Pipeworx team) and action (tell), and naturally differentiates from sibling tools which are information 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?

Description explicitly defines when to use each feedback type (bug, feature, etc.) and provides a negative instruction (don't paste end-user prompt). It gives clear context for appropriate use, though does not name specific alternatives beyond implied contrast with its siblings.

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

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

The description discloses aggregate source (CF analytics-engine), data privacy (no PII, just counts), and caching behavior (5min-1h dependending on window), which add significant value beyond the annotations (readOnlyHint, idempotentHint, etc.). 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 five sentences long, front-loading the core purpose, then listing use cases, then technical details. It is well-structured but could be slightly more concise by merging some sentences.

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

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

Given a single optional parameter and no output schema, the description fully covers what the tool does, when to use it, what it returns (top tools, packs, volume), and technical behavior (caching, privacy). No gaps remain.

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

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

The input schema has 100% coverage with a single parameter `window` described using an enum and a helpful explanation. The description reinforces this by contrasting short vs long window behavior, providing additional 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 it returns 'top tools, top packs, and total call volume' over a time window, using a specific verb ('returns') and resource (Pipeworx trending data). It distinguishes itself from sibling tools by focusing on aggregate call volume and trending, not individual queries or tool 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 explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing alignment). It implies the tool is for trend analysis and not for raw data retrieval, but does not explicitly mention when to avoid it or mention alternative tools.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) are already present and the description adds detailed behavioral context: walking child markets, partition checks, fill check against CLOB depth, and filtering logic. 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 long but well-structured with bolded section headers. Every sentence adds value for a complex tool. It is as concise as the complexity allows without being verbose.

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

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

Despite no output schema, the description explains the response structure and fields. It covers modes, parameters, and behavioral constraints. Could mention more edge cases, but is largely complete.

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

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

Schema coverage is 100% and the description adds significant value beyond the schema (e.g., event slug format, topic seed questions, explaining what each mode does). Baseline 3 is exceeded.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes event and topic modes. While siblings like polymarket_edges exist, the description does not explicitly differentiate, but the purpose is specific and well-articulated.

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

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

The description gives explicit guidance on when to use event vs topic mode, notes that no args fails, and references polymarket_fill_risk for custom sizing. It lacks direct comparison to sibling tools but provides 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?

The description goes far beyond annotations (readOnlyHint, idempotentHint, not destructive) by detailing caching (1h KV), response structure with diagnostics showing why segments are empty, edge calculation methodology (like Kelly scaling, slippage subtraction), and special handling of Fed bets. No annotation contradiction is present.

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 exceptionally detailed and well-organized with numbered segments, but it is quite lengthy (over 300 words). While the complexity warrants the detail, some parts could be condensed without losing meaning. The front-loading of purpose helps, but overall it is less concise than ideal.

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 (9 parameters, no output schema, multiple opportunity types, internal filtering logic), the description is extremely complete. It covers caching, diagnostics, all parameter interactions, Fed bets exclusion, and even explains why certain segments may be empty. There is no notable omission for an agent to understand the tool's 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?

All 9 parameters have schema descriptions (100% coverage). However, the description adds significant value by explaining the rationale behind defaults (e.g., slippage_pp default 0.3 due to bid/ask and thin depth), clarifying tradeable-edge filters, and detailing the relationship between min_kelly and min_partition_leg_kelly. This additional context enhances parameter 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes among three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and explains the output structure, differentiating it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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 frames the tool for 'what should I bet on today' and provides extensive guidance on when to use knobs like min_liquidity, max_spread_pp, min_kelly, and min_partition_leg_kelly. It explains why min_kelly doesn't filter partitions and how the Fed bets note applies. However, it does not explicitly state when NOT to use this tool versus alternatives like polymarket_arbitrage, though the context implies it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral details beyond annotations, such as the structure of the response (tracked, expired, snapshot_dates), limits (60-day TTL, no intraday data), and decay calculation. 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 dense but well-structured, front-loading the core purpose. While it could be slightly more concise, every sentence adds value and technical precision. It avoids 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 the lack of an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and their meanings. It also covers important constraints (TTL, no intraday data, gap handling). This is complete enough for an AI agent to understand the tool's inputs, outputs, 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 coverage is 100%. The description largely repeats the schema information for the two parameters (days and window), adding only minor clarifications like max 30 for days. It does not add substantial meaning beyond the schema.

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

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

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

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

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

The description provides explicit context for when to use the tool (to differentiate between fresh and old wide edges) and implies that polymarket_edges is the alternative for raw snapshots. However, it does not explicitly state when not to use this tool or list all alternative tools.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive. The description adds context by explaining that the tool walks the order book ladder, returns fill details, and warns about partial fill risks. It 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?

The description is well-structured with clear sections for modes and warnings, using line breaks and bold for emphasis. Every sentence contributes value, though it is slightly verbose. Could be trimmed without losing critical 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?

Given the complexity (two modes, multiple return fields) and absence of output schema, the description thoroughly covers what the tool does, what it returns (top_of_book, vwap, slippage, verdict, etc.), and the risks. It is complete for an agent to understand the tool's 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 coverage is 100%, but the description adds significant nuance: clarifies market vs event modes, default side behavior, and details how size_usd is interpreted differently for single-market (max spend/target proceeds) vs basket (settlement notional). This goes well beyond the schema descriptions.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinctly separates single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use 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?

Provides explicit instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the rationale (theoretical overround not capturable, partial fills convert arb to directional risk), guiding the agent on 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: the two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions when spreads are not valid (temporal misalignment, non-equivalent bet shapes). 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 fairly long but well-structured with clear sections for modes, response, and safety fields. It front-loads the core purpose and mode selection. While every sentence adds value, it could be slightly more concise for agents scanning quickly.

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

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

Given the tool's complexity (two venues, potential mismatches) and lack of an output schema, the description comprehensively explains the response structure, safety fields, and conditions under which spreads are meaningful. It covers behavior for both matched and unmatched cases, temporal alignment, and skipped comparisons.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the 10 topic shortcuts, explaining that explicit parameters override the topic-mapped side, and providing examples. However, the schema already provides sufficient semantic information for each parameter.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on spreads rather than pure arbitrage. The two modes (topic shortcuts and explicit pairings) are explicitly described.

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

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

The description provides explicit guidance on when to use each mode: topic shortcuts for 10 pre-mapped macros, and explicit parameters for custom pairings. It warns that most pre-mapped topics currently return compatibility warnings, setting proper expectations. It also explains how to interpret safety fields to know when spreads are meaningful.

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, non-destructive, idempotent. Description adds scoping by identifier and the dual behavior (retrieve vs list). No contradictions.

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

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

Three sentences, no redundancy. Each sentence earns its place: purpose, usage context, scoping and pairing. 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?

Covers core functionality and scoping for a simple and safe tool. Lacks mention of error cases like missing key, but given simplicity and annotation coverage, it's nearly complete.

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

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

Schema coverage is 100% and schema already describes the parameter 'key' as 'Memory key to retrieve (omit to list all keys)'. The description repeats this without adding new parameter-level meaning, so 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?

Clearly states verb 'Retrieve' or 'list', resource 'value previously saved via remember' or 'all saved keys', and distinguishes from siblings 'remember' and 'forget'. Examples like 'user's target ticker' add specificity.

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?

Explains when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget, but could be more explicit about when not to use compared 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral details beyond annotations, such as the effect of mark_read ('flag returned events read so the next call only shows newer ones') and the availability of the same feed via a REST endpoint. This provides 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 four sentences long, front-loaded with the main purpose. Every sentence adds value: purpose, output contents, filter capabilities, behavioral note, and alternative access. 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?

Given that there is no output schema, the description partially compensates by describing what each alert carries (source, citation_uri, raw payload). It also covers mark_read behavior and an alternative access method. For a read-only tool with 5 optional parameters, this is mostly complete, though details on response structure are limited.

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 adds some meaning beyond the schema, such as explaining that mark_read affects subsequent calls and that the 'type' and 'since' parameters filter results. However, it does not significantly enhance understanding of the parameters beyond what the schema already provides.

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

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

The description starts with 'Pull fired events from your subscription feed. Returns the most recent alerts...' which clearly specifies the action (pull/returns) and the resource (subscription feed alerts). It also distinguishes itself from sibling tools implicitly by focusing on reading events rather than subscribing or managing 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?

The description states 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This provides an alternative usage context (for scripts/dashboards) and implies that the tool is suitable for polling. However, it does not explicitly compare to sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable context: fan-out strategy, fallback logic, soft-fail for USPTO, and return structure (changes[], 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 a single, dense paragraph that efficiently conveys all necessary information without redundancy. Every sentence adds value, from usage examples to fallback details.

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, fallback, return structure), the description covers all key aspects despite the absence of an output schema. It describes the return structure and citation URIs, making it complete enough for an agent to use 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 all 3 parameters. The description adds further nuance: accepted 'since' formats (ISO date vs relative shorthand with examples), and explanation that 'type' is limited to 'company'. 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 clearly states the tool provides a change feed for a company over a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from sibling 'entity_profile' by explicitly redirecting to that tool 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 provides explicit example queries ('What's new with X') and tells when to use 'entity_profile' instead ('Use entity_profile when you want the static profile'). It also explains fallback behavior between GDELT and GNews.

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

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

Description adds behavioral context beyond annotations: explains scoping by identifier, persistence differences for authenticated vs anonymous users (24 hour retention). Annotations already indicate idempotentHint=true and destructiveHint=false, and description does not contradict.

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 three sentences, front-loaded with purpose, and every sentence adds value: purpose, usage context, and behavioral details. No wasted words.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage, behavioral traits, and integration with sibling tools. It is complete and 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. Description does not add detailed parameter semantics beyond the schema's examples, but it reinforces the key-value pattern. No additional meaning provided.

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

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

Description uses specific verb 'Save' and resource 'data', clearly stating it stores key-value pairs for later reuse. It distinguishes from siblings 'recall' and 'forget' which are explicitly mentioned.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Also pairs with siblings 'recall' and 'forget', providing clear guidance on alternatives.

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

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

The description adds behavioral context beyond annotations: it notes internal cascading through multiple lookup endpoints and states that using this tool replaces 2-3 manual lookups. This is informative but could be more specific about any limitations or case sensitivity. Annotations already indicate read-only and idempotent nature, so no contradiction.

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

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

The description is well-structured, starting with example queries, then purpose, usage hint, and detailed per-type info. It is slightly verbose but each sentence adds value. It is front-loaded with the most important 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 tool with only two parameters and no output schema, the description provides thorough details on return values per entity type, including the specific identifiers, citation URIs, and auto-disambiguation behavior. No gaps are apparent.

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

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

With 100% schema coverage, baseline is 3. The description adds significant value by explaining each parameter with examples (ticker, CIK, name for company; brand/generic for drug). This clarifies the acceptable input formats beyond the schema's minimal 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: resolving a name to its canonical identifier. It provides example queries, distinguishes the tool from siblings by emphasizing it should be used first when an ID is needed, and explains the resource types it covers. The verb 'resolve' is specific and appropriate.

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 it first when having a name but needing an ID, giving clear usage guidance. While it does not enumerate specific scenarios where not to use it, the context implies its primary role and the sibling tools do not overlap directly, so the guidance 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the probing process (calls ai_visibility_check per entity), ranking behavior, and output fields (score, confidence, signal density). No contradictions with annotations.

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

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

The description is three sentences long, front-loaded with purpose, and concise. Every sentence adds value. It could be slightly more structured, but it is efficient and clear.

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 thoroughly explains what is returned (ranked list with score, confidence, signal density per entity). All parameters are adequately described. The tool's complexity is low and the description covers all necessary aspects.

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

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

Schema coverage is 100% with each parameter already described. The description restates some schema info (e.g., entities size 2-8, first is subject) but does not add new meaning beyond what the schema 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more general) by specifying the exact process and output.

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 a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use it or differentiate from alternatives beyond the context. It implies usage for multiple entities but lacks explicit exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about partial failures, bundlephobia first measurement taking 5-30s, and the sources_failed field, which are valuable behavioral traits 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 a single, focused paragraph that front-loads the purpose and key details. It is concise with no wasted words, though a bulleted list could improve readability.

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

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

Despite lacking an output schema, the description compensates by listing all output fields (summary, advisories, links, versions) and documenting graceful degradation and timeout behavior. This fully equips the agent to understand inputs 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?

Schema coverage is 100% with descriptions for both parameters. The description repeats the schema information (default version, scoped packages) without adding new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for evaluating whether to add an npm package, covering license, advisories, bundle size, and more. It distinguishes from siblings by specifying NPM ecosystem only and referencing other tools for other ecosystems.

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

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

The description explicitly says when to use (agent asks about safety, popularity, size) and provides usage boundaries (NPM only in v1, other ecosystems via different tools). It does not explicitly state when not to use, but the examples and ecosystem limitation offer clear guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the corpus size (~7M English articles) and continuous updates by the community, which is useful 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?

Single, well-structured paragraph that front-loads the most important guidance (when to prefer), then describes output and chaining recommendations. 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?

With an output schema present, the description need not detail return values. It covers usage context, alternatives, data freshness, and chaining suggestions, making it 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 both parameters described. The description does not add extra 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 tool searches Wikipedia and differentiates from web search by specifying it's for general-knowledge/encyclopedic questions. It lists the output elements (article titles, snippets, page IDs, word counts) and provides a clear purpose.

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

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

Explicitly states when to use ('PREFER OVER WEB SEARCH...') and when not, with examples of suitable query types. Advises chaining with other tools for full content, and mentions cost and structure advantages 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 declare read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral detail: embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character limit with flagging, and output offsets for verbatim verification. 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, well-structured paragraph. It front-loads the core purpose and then efficiently adds guidelines, behavioral details, and pairing advice without redundancy. Every sentence earns its place.

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

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

The tool has 3 parameters and no output schema, but the description thoroughly covers algorithm, limits, pairing with a specific sibling, and output features (offsets, similarity scores). It leaves no significant gaps for an AI agent to understand usage and behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the search methodology (embeddings, cosine, overlapping windows) and providing example queries for the 'query' parameter. It also reinforces the 'text' parameter limit with context about truncation.

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

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

The description uses a specific verb-resource pair ('Semantic search INSIDE a fetched record') and clearly differentiates from siblings by mentioning pairing with ask_pipeworx_grounded. It contrasts with fetching whole documents, making its unique value obvious.

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') and provides concrete workflow guidance ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'). It also notes the 200K char cap and truncation behavior.

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

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

Annotations indicate idempotent and non-destructive; description adds critical details: account requirement, delivery channel constraints (SMS cap, phone verification), webhook HMAC signing and auto-disable on failures. 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?

Description is well-structured, starting with purpose, then account requirement, types, and delivery channels. It is somewhat long but each sentence adds value; 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?

No output schema exists, but description adequately states return value (subscription ID and webhook secret once). It covers types, parameters, delivery options, and constraints. However, it does not describe error scenarios or rate limits beyond the SMS cap.

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 each parameter. Description adds examples and clarifies constraints (e.g., clinical_trial requires sponsor or condition), but largely reiterates schema information, providing only moderate additional 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?

Description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying its create action.

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 includes prerequisites (Pipeworx OAuth account) and mentions that the feed can be pulled via recent_alerts, but it does not explicitly contrast when to use this tool versus alternatives (e.g., list_subscriptions to view existing subscriptions).

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it returns category-bucketed examples and tool shapes, which is useful 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?

Single paragraph, front-loaded with trigger phrases, explains output and usage. Could be slightly trimmed but remains efficient for the information conveyed.

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 fully covers purpose, usage, output format, and when to use it.

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 optional topic parameter with description. The description adds usage guidance: 'Call with no arguments for full spread, or pass topic to focus', and provides examples of topic values.

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's an onboarding entry point that returns categorized example questions with exact tool calls. It distinguishes itself from siblings like ask_pipeworx by emphasizing its role as a starter 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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use and 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?

Adds significant behavioral context beyond annotations: ownership enforcement, soft-deactivation (not deletion), and that historical events remain. Annotations already indicate idempotent and non-destructive, which description reinforces and expands.

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

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

Two sentences with no waste. First sentence states action, second adds key behavioral details. Front-loaded and efficient.

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

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

Given simple parameter structure and no output schema, description covers core behavior (cancel, ownership, soft-delete, historical retention). Could mention return format, but not critical for a straightforward action.

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 with 100% schema coverage. Description adds that id is returned by subscribe, linking to sibling tool. This extra context justifies a 4 over 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?

Clear verb 'cancel' with specific resource 'subscription by id'. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'. Also mentions ownership and soft-deactivation for added clarity.

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

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

States when to use (cancel subscription) and ownership constraint (only your own). Implicitly says not for permanent deletion via 'deactivated not deleted'. Mentions historical events via recent_alerts. No explicit alternatives, but sufficient for this simple 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?

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns a verdict (with specific options), actual value with citation, and percent delta. It also explains it replaces 4-6 sequential calls, providing insight into the tool's internal logic and efficiency. 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 moderately long but well-structured with front-loaded trigger phrases. Every sentence adds value: listing examples, defining domain, explaining return values, and highlighting efficiency. It is concise for the amount of information conveyed.

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

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

Given the tool has no output schema, the description adequately explains the return values (verdict, structured form, actual value, citation, delta). For a single-parameter tool with clear domain and behavior, the description is sufficiently complete, covering purpose, usage, output, and performance benefits.

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 'claim' parameter is described in the schema with a clear description and examples. The tool description reinforces this by reiterating the natural-language nature and providing trigger phrases. Schema coverage is 100%, so the description does not need to carry the full burden, but it adds context by specifying the domain and the types of claims supported.

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 for fact-checking natural-language claims with specific trigger phrases. It clearly identifies the domain (company-financial claims for public US companies) and distinguishes it from other tools by explaining it replaces multiple sequential calls. This is a specific verb+resource with strong differentiation from siblings.

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 whenever the agent needs to check whether something a user said is factually correct.' It also notes the domain limitation (company-financial claims) and explains the efficiency benefit. Though it doesn't explicitly state when not to use it (e.g., for non-financial claims), the domain specification implies the scope.

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