Coresignal

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description adds value by explaining the free default model, the API key pass-through mechanism, and the per-model return structure (score, confidence, signals, raw_response). Could mention rate limits or cost implications but still strong.

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 moderate length, front-loaded with core purpose, then operational details, then use cases. Each sentence adds value; no fluff. Structure supports quick comprehension.

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

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

Covers purpose, parameters, behavioral details, return structure, and use cases. Despite no output schema, description explains the combined view and per-model fields. Annotations cover safety. Completeness is high for a probe tool.

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

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

Schema coverage is 100%, but description enriches each parameter: explains default behavior for models, clarifies that _apiKey is only needed for anthropic, and gives examples for entity. This adds meaningful guidance 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 verb ('probe'), resource ('LLMs'), and outcome ('score visibility 0-100 per model'). It specifies default model and optional Anthropic probing. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, though purpose is distinct enough.

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

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

Explicitly mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides operational guidance: default free model, conditional API key for Anthropic. Does not include when-not-to-use or alternative tools, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds substantial behavioral context: it routes to 4,774 tools across 1,242 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier. 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 relatively long but well-organized with bold headings, examples, and a clear flow. It front-loads the primary directive and then provides alternatives. However, it could be slightly more concise by trimming redundant phrases. Overall, it earns 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?

For a tool that routes to many sources, the description is exceptionally complete: it explains when to use, alternatives, examples, return format (structured answer with citation URIs), and even mentions tier compatibility. No output schema, but the description adequately covers return value expectations.

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 6 parameters, all aliases for 'question'. The description's parameter section simply states 'Your question or request in natural language.' While the examples and overall context clarify usage, the description does not add significant semantic depth beyond the schema's documentation. 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: routing questions to a vast set of tools/sources and returning structured answers with citation URIs. It provides specific examples and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and gives detailed guidance on when to use this tool vs alternatives (ask_pipeworx_grounded for high-confidence answers, deep_research for broad questions). It also lists example queries and types of factual questions, making usage criteria very 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. The description adds significant behavioral context: it explains the extraction logic (uses ONLY tool result), return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), and explicit refusal reasons. 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 front-loaded with the key benefit and routing info. It efficiently covers purpose, behavior, return format, use cases, and trade-offs in a structured paragraph. While slightly lengthy, every sentence contributes value, making it informative without being bloated.

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 parameters, no output schema), the description compensates well by detailing the return structure and refusal reasons. It covers high-stakes contexts and cost implications. However, it could further clarify the 'data_truncated' refusal reason and edge cases for completeness.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds minimal param-specific information beyond what the schema provides. It mentions the question is in natural language, but the schema already states that. Baseline 3 is appropriate as the description adds marginal value over 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 specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly distinguishes from its sibling ask_pipeworx by noting it extracts answers using only the tool result, providing a unique value proposition. The scope and purpose are immediately clear.

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

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

Explicitly provides use cases ('high-stakes reads, financial verdicts, legal claims, medical lookups, public statements') and when to prefer the sibling ('prefer ask_pipeworx for casual lookups'). It also includes cost comparison, giving the agent clear decision criteria. No guesswork needed.

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

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

Despite annotations already declaring readOnlyHint=true and destructiveHint=false, the description goes far beyond by detailing fan-out logic, response shapes, resolver contract (match confidence, alternatives), parent event extraction, news fallback handling, safety mechanisms (low-confidence suppression, closed markets, wide spread warnings), and resolution-rule risk. It fully discloses behavioral traits and edge cases.

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

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

The description is thorough but lengthy, spanning multiple paragraphs with examples and edge cases. While it is well-structured with section headers and all-caps labels, it could be more concise for an AI agent to quickly parse. Each sentence adds value, but the overall length reduces conciseness.

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

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

Given the tool's complexity (many output fields, safety concerns, resolution rules) and the absence of an output schema, the description compensates excellently. It explains response shapes, field meanings, and all relevant edge cases (low confidence, closed markets, wide spreads, cancellation rules). No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining input types (slug, URL, question text), the depth parameter's effect ('quick = 2-3 evidence sources, thorough = full fan-out'), and the include_raw parameter's impact on response size. This context enhances understanding beyond the schema alone.

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

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

The description begins with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further specifies the types of inputs and outputs, and distinguishes itself from sibling tools like 'polymarket_edges' and 'ask_pipeworx' by focusing on a single bet research task. The purpose is unmistakable.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context for when to call, but lacks explicit 'when not to use' statements or alternatives. However, the sibling tools list naturally implies alternatives for broader tasks like arbitrage or edge scanning.

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. Description adds details: uses SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, returns sorted results, and includes citation URIs. No contradiction.

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

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

Description is front-loaded with trigger phrases but is verbose (multiple sentences, examples, and details). Some redundancy could be trimmed while retaining 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?

Given the complexity (two entity types, multiple data sources, sorting, return format), the description covers essential details: data sources, fiscal year handling, sorting, and citation URIs. It is complete enough without 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 has 100% coverage. Description adds context: explains type enum values and provides examples for values (tickers vs drug names). It adds information about data sources per type beyond schema.

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

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

The description clearly states it compares 2-5 entities (companies or drugs) side-by-side, with specific verb 'compare' and resource 'entities'. It effectively distinguishes from sequential lookups by explicitly preferring 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?

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups'. It includes example queries and explains data sources per type. However, it does not specify when not to use it (e.g., more than 5 entities).

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, and open-world. Description adds 'LinkedIn-adjacent B2B data' and requires a BYO API key, which offers mild extra 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?

Two sentences, front-loaded with main action and result fields, followed by a concrete example. No unnecessary words.

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

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

Explains what data is returned, input options, and provides an example. Lacks error handling or authentication details beyond the API key, but for a simple lookup tool this is sufficient.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description repeats usage of name/website and shows _apiKey in example, adding minimal extra 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?

Clearly states it looks up company firmographics and headcount from Coresignal by name or website, listing specific fields (size, employee count, industry, founding year, HQ, LinkedIn URL). Distinguishes from sibling 'coresignal_employee' which focuses on employee data.

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

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

Specifies input options (name or website) and provides an example call. No explicit when-not-to-use or alternatives, but sibling differentiation is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the data source (Coresignal, LinkedIn-adjacent) and specific return fields (title, company, location, LinkedIn URL, work experience, education). No contradictions.

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

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

Two sentences and an example convey the purpose, inputs, and outputs without waste. Information is front-loaded with the action verb 'Find' and key details. Every element earns its place.

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

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

Given the tool has no output schema, the description adequately lists return fields. However, it could mention behavior when a profile is not found or handling of missing company. Annotations cover safety, but completeness is slightly above average.

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 meaningful details beyond the schema: 'Full name of the person', 'Optional company name to disambiguate', and for _apiKey: 'BYO', 'Sign up + start a trial at coresignal.com'. This clarifies the key's origin and usage.

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 'Find a person's professional profile' with specific resources (name, company) and lists return fields. It distinguishes from siblings like coresignal_company by focusing on individuals. The example further clarifies usage.

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 indicates when to use (to find a person's profile) but does not explicitly state when not to use or provide alternatives among many sibling tools. However, the example and mention of LinkedIn-adjacent data give context. Some guidance is implied but not exhaustive.

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 critical details: decomposes question into facets, parallel routing to 4,774 tools, return format (findings packet with citations and gaps[]), expected 15-60s, and limitation on structured data only. No contradiction with annotations.

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

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

The description is thorough but slightly verbose. It is well-structured with important info upfront (account, alternative) and organized into clear points. Every sentence contributes value, but could be tightened slightly without loss.

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 fully explains what to expect: findings packet structure, confidence, citations, gaps array. It also covers constraints (no open-web search, not for breaking news) and performance. Complete for effective use.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value: explains depth values (quick=3, standard=5, thorough=8 paid) and clarifies that question can be broad/multi-part. This enhances understanding beyond schema.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources'. It uses specific verbs ('researches', 'decomposes', 'routes') and explicitly distinguishes from sibling ask_pipeworx (single lookup). The purpose is unambiguous and well-defined.

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: account requirement, when to use ask_pipeworx instead (single lookup, breaking news), and depth level explanation ('thorough' needs paid plan). This helps the agent choose between tools correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations, providing useful context about return format and readiness.

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

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

The description is concise at a few sentences, front-loading the main purpose. Every sentence adds value, though it could be slightly more terse by removing some redundant domain examples. Overall, it is 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?

Given the tool has 6 parameters (1 required) and no output schema, the description covers essential behavior: what it does, what it returns, and when to use it. It does not explain ranking details or error handling, but these are secondary. It is sufficiently complete for agent invocation.

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

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

Schema coverage is 100% and all parameters are described. The description adds value by explaining that query has aliases (q, task, search, description) and specifying default limit (20) and max (50), which are not in the schema. This additional context helps the agent understand parameter flexibility.

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 specific domains (SEC filings, financials, FDA drugs, etc.) and explains that it returns top-N relevant tools with names, descriptions, and full input schemas. This differentiates it from sibling tools which are specific utilities.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use the tool. However, it does not explicitly state when not to use it or provide alternatives.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavioral traits: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields (CIK, filings up to 5 with URIs, fundamentals sorted by period_end, patents soft-fail, GDELT→GNews fallback, LEI). No contradictions.

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

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

The description is relatively long but highly informative, with examples, prioritized guidance, and technical details. Every sentence adds value, though it could be slightly more concise 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?

Given the tool's complexity (multiple data sources, no output schema), the description is remarkably complete: it enumerates all returned components (CIK, filings, fundamentals, patents, news, LEI), specifies limits (up to 5 filings), and notes edge cases (patents sunset, news fallback).

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 crucial meaning: value parameter is 'Ticker (e.g., "AAPL") or zero-padded CIK (e.g., "0000320193")' and explicitly states names are not supported. This goes beyond the schema's simple string description.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with multiple example queries ('Tell me about X', 'research Acme', etc.). It distinguishes itself from siblings like resolve_entity by specifying it handles tickers or CIKs, not names.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and warns that names are not supported (use resolve_entity first). This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint and idempotentHint. The description adds usage context (clearing stale/sensitive data) and pairing advice but does not disclose error behavior or return value, which would improve transparency.

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

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

Three concise sentences, front-loaded with the action, 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?

Adequate for a single-parameter destructive tool with good annotations. Covers purpose, usage, and sibling relation, but could mention return value or error cases for full completeness.

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

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

Schema coverage is 100% with a clear parameter description. The tool 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 uses a specific verb ('Delete') and resource ('memory by key'), clearly distinguishing it from siblings '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 advises when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with related tools, though no explicit when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds context by explaining the process (fetches page, extracts title/description/key links, emits llms.txt markdown) and the output format, which the agent needs to know.

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

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

The description is concise: two sentences plus a bulleted list of use cases. Every sentence adds value, with the core purpose stated first. 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 (2 parameters, no output schema), the description covers all necessary context: what it does, how it works, when to use it, and the output format. No gaps remain.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' already described. The tool description does not add new meaning beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file for any URL', and specifies the target AI crawlers (ChatGPT, Claude, Perplexity). It differentiates from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning or 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 use cases: getting a client's site indexed, drafting for own projects, or auditing competitors. While it doesn't list when not to use or alternatives, the context is sufficient for most scenarios.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context about returned fields and the default exclusion of inactive subscriptions, which is useful but not critical given annotations.

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

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

Two concise sentences with no redundancy. First sentence covers purpose and output; second covers usage guidance. 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?

The tool is simple with one optional parameter and no output schema. The description fully covers what it does, what it returns, 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 coverage is 100%; description does not add meaning beyond the schema's description of the single parameter. Baseline 3 applies.

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

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

Clearly states it lists 'active subscriptions' and specifies return fields (id, type, params, etc.). Distinguishes from sibling tools by mentioning use for reviewing before adding or canceling.

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: to review monitors before subscribing or to find an id for cancellation. Implicitly indicates not for creation or deletion, but no explicit exclusions.

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

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

Discloses rate limit (5 per day per identifier), that it's free and doesn't count against quota, and that feedback is read daily and affects roadmap. This adds value beyond annotations, which only indicate non-readonly, non-destructive, etc.

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 compact paragraph that efficiently covers purpose, usage, constraints, and behavioral notes. Every sentence adds value with no redundancy.

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

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

For a feedback tool, the description covers what to do, how to do it, constraints, and what happens after submission. No output schema is needed; the description adequately explains the outcome.

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

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

Schema coverage is 100%, but the description adds value by explaining the enum values in plain language and specifying that message should be 1-2 sentences and 2000 chars max. It also clarifies the context fields briefly.

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 for sending feedback about bugs, feature requests, data gaps, or praise. It specifies what to include (tools/packs) and what not to include (end-user prompt), making it distinct from sibling tools like ask_pipeworx.

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

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

Explicitly lists when to use: for bugs, missing features, or praise. Provides guidance on content (describe in terms of Pipeworx tools). However, it does not explicitly contrast with sibling tools for when not to use, though the context implies it's only for feedback.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). This goes beyond annotations.

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

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

The description is concise and well-structured: one sentence for purpose, a list of use cases, then technical details. Every sentence adds value with no redundancy.

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

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

Given the tool has one optional parameter, no output schema, and comprehensive annotations, the description covers all necessary context: purpose, use cases, data source, privacy, caching, and parameter semantics. It is complete for an AI agent to decide when to invoke 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 coverage is 100% for the single parameter 'window'. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which aids in parameter selection beyond the schema's enum description.

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

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

The description clearly states the verb 'returns' and resource 'top tools, top packs, and total call volume' with a specific scope (recent window). It differentiates from siblings like ask_pipeworx and discover_tools by focusing on trending usage data.

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

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

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, seeing alignment). While no direct 'when not to use' is given, the context is clear and helps decide between this and sibling tools.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: monotonicity checks, partition sum, Jaccard similarity filter, placeholder filter, fill check from CLOB depth, and realizable edge calculation. No contradictions.

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

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

The description is front-loaded with the main purpose and modes, but includes extensive internal algorithmic details that could be shortened. However, these details are valuable for correct tool invocation, so the verbosity is justified.

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 (`opportunities[]`, `partition_check`, `fill_check`) and references the sibling tool `polymarket_fill_risk` for custom sizing. It covers inputs, modes, internal logic, and outputs comprehensively.

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

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

Schema coverage is 100% with descriptions. The description adds meaning: for `event` it provides examples and notes it walks child markets; for `topic` it explains cross-event scanning and semantic anchor. It also details internal logic and recommendations.

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 between trending scan, event mode, and topic mode, providing a specific verb+resource with clear scope.

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

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

The description explicitly instructs when to call with no args, when to use `event` vs `topic`, and recommends `event` for specific markets. It explains the cross-event mode's advantage. However, it lacks explicit when-not-to-use or alternatives among sibling tools.

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

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

The description provides extensive behavioral details beyond annotations: it explains the five model families, three response segments, edge calculation (including slippage, Kelly fractions), caching (1h KV), diagnostics for empty segments, and special cases like Fed bets. There is no contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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, starting with purpose, then model families, output fields, knobs, and response layout. Every sentence adds value given the tool's complexity. Minor verbosity may slow parsing, but overall it's appropriately front-loaded and organized.

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

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

Given the complexity (9 parameters, no output schema), the description is comprehensive. It explains the response structure (by_segment, diagnostics), special fields (edge_pp_net, kelly_fraction, etc.), caching, and edge cases (placeholder filters, Fed bets). An agent can fully understand inputs, behavior, and outputs without additional context.

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

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

All 9 parameters are described in the schema with 100% coverage. The description adds significant meaning by explaining the rationale behind each filter (e.g., min_kelly vs min_partition_leg_kelly), default values, and when to adjust them (e.g., slippage for thin partitions). This surpasses what the schema alone provides.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today.' It distinguishes from sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) by focusing on Pipeworx disagreement and providing specific model families and segments.

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

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

The description explains the tool's purpose and context (discovering opportunities without paging), but does not explicitly state when not to use it or compare to alternatives. While it details filters and knobs, an agent might need guidance on when to choose this tool over related Polymarket 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 already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing behavioral traits: snapshot creation on cache-miss, history depth bounded by 60-day TTL, and decay computed from daily closes not intraday. 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 efficiently structured: it front-loads the core question, then covers arguments, response format, and limitations in a clear flow. Every sentence provides useful information with no redundancy.

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

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

Despite lacking an output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) and covers limitations. With annotations handling safety, the description is complete for this specialized telemetry tool.

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

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

Both parameters have full schema coverage, but the description adds context: for 'days' it clarifies lookback and max (30 vs. schema's clamp 2-30), and for 'window' it calls it a 'snapshot family' with default. 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's purpose: analyzing edge persistence and decay from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes from sibling tools like polymarket_edges by focusing on temporal behavior.

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

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

The description provides explicit guidance on when to use this tool (to assess edge age and decay) and implies alternatives (polymarket_edges for current edges). It explains the significance of fresh vs. old wide edges, giving context for decision-making.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, non-destructive. Description adds that it walks the ladder, returns fill details, and identifies forced_directional_risk, adding context beyond annotations. No contradiction.

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

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

Description is lengthy but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence earns its place, though minor redundancy could be trimmed.

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

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

No output schema, but description comprehensively lists all return fields for both modes, explains risks and motivation. Complete for a complex tool with two modes.

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

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

Schema coverage is 100%, but description greatly enriches meaning: explains side auto-selection in basket mode, size_usd interpretation per mode, and difference between single-market and basket parameters. Adds significant value.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth', distinguishing single-market and basket modes with specific return fields. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by acting as a prerequisite check.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about partial basket fills causing directional risk. Provides clear when-to-use guidance.

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

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

The description elaborates on safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains conditions under which spreads are meaningful. This adds context beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false). No contradiction detected.

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

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

The description is informative but slightly verbose, with multiple explanatory sentences. However, every sentence adds value and the structure (modes, response, safety fields) is logical. A minor trim could improve conciseness.

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

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

Given no output schema, the description fully explains the response format (leg-by-leg prices, spread data) and covers edge cases like mismatched shapes, empty matches, and temporal alignment. It provides a complete picture for an agent to use the tool correctly.

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

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

Schema coverage is 100% and the description adds substantial meaning: it explains the two modes, how topic overrides work, and gives concrete examples. This goes beyond the basic schema properties.

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

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

The description clearly states the tool computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and specifies two modes (topic shortcuts and explicit tickers). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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 explains when to use each mode, and provides warnings about compatibility and temporal alignment. It advises that most pre-mapped topics return compatibility warnings, setting realistic expectations about tradeable spreads.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and pairing semantics, no contradictions.

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

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

Three sentences, front-loaded with main action, 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 retrieval tool with full schema and annotations, description covers behavior, pairing, and scoping adequately.

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

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

Schema covers 100% of 1 optional parameter. Description adds meaning about listing all keys when omitted, going beyond schema.

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

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

Description clearly states it retrieves a value via remember or lists all keys if omitted. Differentiates from siblings remember and forget.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and suggests pairing with remember and forget. Does not explicitly exclude alternatives but provides clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations: it specifies returned fields (source, citation_uri, raw payload), and that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones.' This enriches agent understanding without contradiction.

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

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

The description is concise at 4 sentences, each serving a distinct purpose: core action, return fields, parameter guidance, and usage context. It is front-loaded with the primary action and avoids unnecessary verbiage.

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 5 parameters and no output schema, the description adequately covers return fields, parameter behavior, and alternative access. However, it lacks details on pagination, error handling, or rate limits. Given the complexity, it is reasonably complete.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by providing usage examples: 'Filter by type (e.g. 'sec_8k') and/or since (ISO timestamp). Set mark_read:true to flag returned events read.' This clarifies parameter semantics beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and action (pull). However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'subscribe', though the context implies it deals with event data. Lacks explicit sibling distinction.

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 indicates when to use: 'Polls work fine' suggests suitability for polling. It also provides an alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' However, no explicit when-not-to-use or exclusion scenarios are given.

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?

Describes multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), explains soft-failure of USPTO, and mentions output structure with citations. Annotations confirm read-only, idempotent nature; 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?

Single dense paragraph; front-loaded with example queries. Very efficient, though slightly long; could be broken into bullet points for readability, but still concise.

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

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

No output schema, but description explains return structure (changes[] grouped by source, total_changes, citation URIs). Covers all needed context for a complex multi-source tool.

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

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

Schema covers 100% of parameters with descriptions. Description adds context for `since` (ISO date or relative shorthand, typical value) and clarifies `value` accepts ticker or CIK. Schema and description together provide complete understanding.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with example queries, and distinguishes from sibling 'entity_profile' which provides 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?

Explicitly states when to use alternative tool ('entity_profile instead when you want the static profile'), describes fallback behavior (GDELT→GNews), and provides typical parameter usage ('Use "30d" or "1m"').

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 set idempotentHint=true and destructiveHint=false. Description adds important context about session persistence (authenticated vs anonymous, 24-hour retention). Missing detail on overwrite behavior for existing keys.

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

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

Well-structured: starts with purpose, then usage, then behavioral details. Each sentence adds value without redundancy.

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

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

No output schema needed; description covers key details (scoping, persistence). With 2 simple params and good annotations, no gaps.

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

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

Schema covers both params with 100% coverage. Description adds that it's key-value scoped by identifier and gives example patterns, but schema already provides description.

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

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

Clearly states verb 'save' and resource 'data' for reuse. Mentions pair with recall/forget, distinguishing 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?

Explicitly says when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget for retrieval and deletion.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses that each call cascades through multiple lookup endpoints and replaces 2-3 manual lookups. It also mentions auto-disambiguation for companies and provides return details including citation URIs. This gives full behavioral transparency without contradiction.

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

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

The description is a single paragraph that front-loads examples and key guidance. Every sentence adds value (goals, supported types, return info). It is moderately concise but could be slightly tighter without losing information. Overall well-structured.

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

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

Given no output schema, the description compensates by detailing return values for each type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It provides enough context for the agent to understand what the tool returns and how to use it, making it complete.

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

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

Schema coverage is 100% (both parameters described in schema). The description adds value by explaining valid inputs for each type (e.g., ticker, CIK, name for company; brand or generic name for drug) and mentions auto-disambiguation. This enhances understanding beyond the schema, but the schema already provides basic descriptions, so it's slightly above baseline.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to a canonical/official identifier. It provides specific examples like 'What's the ticker for…' and explicitly says 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This distinguishes it from sibling tools that operate on entities directly.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' This tells the agent when to invoke this tool over others. It also implies alternatives: if you already have an ID, use other tools. The description further details supported entity types and what each returns, aiding correct invocation.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds behavioral context: it probes each entity, ranks by score, returns a ranked list with score, confidence, signal density, and treats the first entity as the subject for narrative. 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 two sentences, front-loading the core action in the first sentence ('Compare AI visibility across multiple entities side-by-side'). Every sentence provides necessary context without redundancy.

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

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

Given 4 parameters, 1 required, high schema coverage, no output schema, and annotations covering safety, the description adequately explains the tool's purpose, behavior, and output format (ranked list with score, confidence, signal density). Minor missing details like pagination are acceptable for this type of tool.

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

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

Schema coverage is 100%, but the description adds value: it explains that the first entity is treated as the 'subject' for narrative (not in schema), that models defaults to workers-ai, and that _apiKey is only needed for anthropic. This extra context improves 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and highlights most/least recognized. It uses a specific verb ('compare') and resource ('AI visibility'), and distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison.

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

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

The description explicitly says 'Useful for competitive AI-marketing audits' and gives an example question, implying when to use it. It mentions it internally uses ai_visibility_check, differentiating from the single-entity sibling. However, it does not explicitly state when not to use it or list specific 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, destructiveHint=false. Description adds: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, and output includes summary block, per-advisory details, links, alternative versions. 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 relatively long but every sentence adds value. Front-loaded with main purpose and usage. Could be slightly more concise but well-structured overall.

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 the output structure (summary block, per-advisory, links, alternative versions), partial failure behavior, and ecosystem limitations. Very complete for a composite 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% so baseline 3. Description adds that scoped packages (e.g., '@types/node') are accepted and version defaults to latest. These details go beyond schema descriptions.

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

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

The description clearly states it is a composite check combining deps.dev and bundlephobia for npm packages, with specific verb 'scan dependency' and resources. It distinguishes from sibling tools by specifying NPM-only scope and referencing other ecosystem fallbacks.

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 agent asks "is X safe / popular / small" or "what does adding lodash cost me"', and notes NPM ecosystem only in v1, with alternatives for other package managers.

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, and non-destructive. The description adds significant value by disclosing the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), character cap (200K chars with truncation flag), and return details (character offsets, similarity scores). No contradictions.

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

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

The description is concise (four sentences) and front-loaded with the core purpose. It flows logically from intention to use case to technical details, with no wasted words. 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?

For a tool with three parameters, no output schema, and straightforward behavior, the description covers all essential aspects: inputs, outputs (passages with offsets and scores), constraints (200K char cap, truncation), and even the embedding model and windowing. An agent can fully understand how to invoke and interpret results.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description reinforces the purpose of each parameter but does not add new semantic detail beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states it performs 'semantic search INSIDE a fetched record,' identifies the input (text and query), and outputs passages with offsets and scores. It distinguishes itself from sibling tools by specifying when to use it (for large records) and how it pairs with ask_pipeworx_grounded, leaving no ambiguity.

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 this tool: 'Use when the record is too big to cram into the prompt.' It provides a concrete alternative ('Pairs with ask_pipeworx_grounded') and explains the benefit (saves context, returns only relevant passages). This is exemplary 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?

Adds significant details beyond annotations: authentication requirement, delivery channel constraints (SMS cap, webhook signing secret, auto-disable), and type-specific behaviors. No contradiction with annotations.

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

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

Single dense paragraph front-loads core purpose and return. Could benefit from structured bullets for readability, but each sentence adds necessary information without redundancy.

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

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

Covers return value, prerequisites, type-specific params, and delivery details. No output schema, but description adequately explains what agent can expect. Minor gap: no mention of duplicate subscription handling, but idempotent hint suggests safety.

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%, yet description enriches with concrete examples, codes for sec_8k items, topic for polymarket_edge, and delivery channel constraints. Adds value well beyond schema descriptions.

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

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

Clearly states verb 'Create' and resource 'proactive monitoring subscription' with return value 'subscription id'. Disambiguates from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly requires a Pipeworx OAuth account, listing prerequisites. Provides context for supported types and parameters but does not explicitly specify when not to use or mention alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds behavioral details: it returns category-bucketed examples drawn from a live catalog, and explains the response format (tool+argument shape). This complements annotations without contradiction.

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

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

The description is informative but somewhat verbose, containing many example queries upfront. However, it front-loads the purpose and usage, and every sentence adds value. Could be slightly more concise, but overall well-structured.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (category-bucketed example questions with tool and argument shapes) and covers all necessary context for an agent starting out. It is complete for its intended onboarding role.

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

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

The single optional parameter 'topic' is described in both schema and description. The description adds context by listing possible values and explaining that omitting it gives a cross-category spread, which adds meaning beyond the schema's enum-like description.

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

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

The description clearly defines the tool as an onboarding entry point that returns categorized example questions with tool and argument shapes. It uses specific verbs ('returns') and distinguishes it from siblings like ask_pipeworx and discover_tools by stating it should be used first to learn about Pipeworx's capabilities.

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 ('FIRST when you do not yet know what Pipeworx can do for you') and how to call it (with no arguments for full spread, or with a topic to focus). It also indicates the tool helps learn how to call meta-tools, providing clear usage context.

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

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

Adds key behavioral details beyond annotations: ownership enforcement and soft-deactivation. Aligns 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?

Two concise sentences with front-loaded purpose. 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?

Fully covers purpose, usage, and outcome for a simple tool with one parameter. No gaps given 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 covers parameter fully (100%). Description adds context: 'returned by subscribe', which is helpful but not essential.

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

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

Clearly states the action 'Cancel a subscription by id', with specific verb and resource. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement and explains the effect (deactivation not deletion) with reference to alternative recent_alerts for historical data.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds significant context: data source (SEC EDGAR + XBRL), verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), output includes citation and percent delta, and efficiency claim (replaces 4-6 calls). 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 somewhat lengthy but well-structured: starts with query patterns, then usage guidance, scope, output details, and efficiency note. Each sentence serves a purpose without redundancy. Could be slightly condensed but still effective.

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

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

Given the simple input (one string) and no output schema, the description covers input format with examples, output types, and data source. It lacks explicit mention of error handling or unsupported claim types, but overall provides sufficient context 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?

Only one parameter 'claim' with full schema coverage (100%). Description adds value by providing natural-language examples and clarifying format, going beyond the schema's description which is already adequate. The examples illustrate expected input style.

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

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

Description explicitly states the tool's purpose as natural-language claim verification against authoritative sources, with specific example queries and clear scope (company-financial claims for US public companies). It distinguishes itself from sibling tools by replacing multiple sequential calls.

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

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

Clearly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and provides scope limitations (company-financial claims, public US companies). It does not explicitly list alternatives or when not to use, but the context of sibling tools provides implicit differentiation.

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