Chainlist

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: default model (Workers AI Llama-3.3-70b free), BYO key requirement for Anthropic, per-model return structure ({score, confidence, signals, raw_response}), and combined view. It does not contradict annotations and enriches the agent's understanding of side effects and authentication.

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 covering purpose, default behavior, key usage, return format, and use cases. No redundant information. Front-loaded with the core action. 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?

Despite lacking an output schema, the description explicitly lists return fields (score, confidence, signals, raw_response) and a combined view. Parameters are fully documented in the schema, and annotations cover all safety aspects. The description provides sufficient context for an agent to understand inputs, outputs, and constraints without missing key details.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model, the purpose of _apiKey ('BYO key — you pay Anthropic directly'), and how context helps disambiguate. This goes beyond the schema's descriptions (e.g., 'Optional: a phrase locating the entity') to clarify practical 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 probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. It uses specific verbs ('probe', 'score') and identifies the resource ('LLMs'). This differentiates it from sibling tools like 'scan_competitor_ai_presence' by focusing on direct model queries rather than scanning.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it does not provide explicit when-not-to-use guidance or alternative tools, the context signals and sibling list imply distinctiveness. The absence of exclusions is acceptable given the clear target 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, openWorldHint, idempotentHint. Description adds that it returns structured answers with citation URIs, works on every tier, and routes internally — beyond what annotations provide.

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

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

Front-loaded with key guidance and examples, but fairly verbose. Every sentence adds value, could be slightly shorter 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 tool's complexity (routing to thousands of tools), no output schema, the description is complete: covers purpose, usage, examples, alternatives, and behavioral context.

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

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

Schema coverage is 100%, so baseline 3. Description doesn't add parameter meaning beyond the schema's alias descriptions, but the schema itself is clear.

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

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

The description explicitly states it routes questions to 4,552 tools for structured data, providing citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Provides explicit guidance: prefer over web search, use for factual questions with examples, and specifies when to step up to grounded or deep_research. Clearly states 'START HERE for most questions'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds extra cost (one LLM call), refusal reasons, and the extraction process. 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 concise yet comprehensive; front-loaded with key concept and structured with bullet-like details. Every sentence adds value, though slightly longer than minimal.

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

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

Covers purpose, usage, refusal reasons, cost comparison, and return format. Despite no output schema, the description fully informs about behavior and expected outputs.

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

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

Schema coverage is 100% with clear alias descriptions. Description does not add parameter-specific details beyond the schema, but explains the overall query behavior. Baseline 3 is appropriate.

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

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

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates from sibling ask_pipeworx by explaining the extraction process and refusal handling. It uses specific verbs and resources.

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 specifies when to use (answers to be quoted/cited/acted on, high-stakes domains) and when not to prefer ask_pipeworx for casual lookups. Provides clear context and alternatives.

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

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

The description adds extensive behavioral context beyond the provided annotations. It details the fan-out mechanism, response shapes, resolver contract, parent event extraction, news fallback behavior, safety checks (low-confidence short-circuit, closed market handling), illiquid spread warnings, and resolution-rule risk. This fully discloses the tool's behavior without contradicting the readOnlyHint, idempotentHint, or openWorldHint annotations.

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

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

The description is very detailed and structured with sections like CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc. However, it is quite verbose (approximately 800 words). While valuable, it could be more concise by omitting some examples and lengthy explanations that are already clear in the schema or annotations. The front-loaded first sentence is effective.

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

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

Given the complexity of the tool and the absence of an output schema, the description provides a thorough account of the response structure (result.market, result.analysis, result.evidence), edge cases (low-confidence matches, closed markets, wide spreads), and resolution rules (cancellation_rule). It covers all aspects an agent would need to correctly interpret and use the tool's output.

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

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The description enriches understanding by clarifying that the 'market' parameter accepts slugs, URLs, or question text, explaining the 'depth' enum values, and describing the effect of 'include_raw' on response size. This adds value 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the tool's purpose and differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on researching individual bets rather than arbitrage or edge analysis. Usage examples like 'should I bet on X' further clarify its intended use.

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

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

The description explicitly states the tool is for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', providing clear context for when to use it. It also discusses when not to trust results (low-confidence matches, closed markets) but does not explicitly exclude alternatives like using polymarket_edges or deep_research for similar tasks. The sibling context implies differentiation, but it is not explicit.

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 details beyond annotations: explains data sources (SEC EDGAR/XBRL for company, FAERS for drug), mentions handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with readOnly/openWorld/idempotent hints.

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

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

Dense paragraph with good front-loading of example queries and key instruction. Could be slightly more structured but effectively communicates core information without excess.

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

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

Given simple schema (2 params, no output schema), description explains data sources, response type (paired data + citation URIs), and sorting. Could mention max entity count (5) but that's in schema. Reasonably complete for the tool's complexity.

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

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

Schema coverage is 100% with basic descriptions, but the description adds rich semantics: specifies exact financial metrics for company type (revenue, net income, cash, debt) and drug metrics (adverse-event counts, FDA approvals, trials). Also clarifies sorting behavior.

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 specifies verb 'compare' and resources 'companies or drugs' with concrete metrics. It distinguishes from sequential lookups by emphasizing 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

Explicitly states preference over sequential lookups and provides trigger phrases (e.g., 'compare X and Y', 'which is bigger'). Does not explicitly state when not to use, but sibling tools imply alternative for single 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, open-world, idempotent, non-destructive. The description adds significant detail: decomposition into facets, parallel routing to 4,552 tools, output structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps array), expected response time (15-60s), and account requirements. No contradictions.

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

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

The description is well-structured and front-loaded with critical information (account requirement). While relatively long, every sentence adds value, covering purpose, usage, behavior, and limitations. It is not excessively verbose but could be slightly tighter.

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

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

Given the tool's complexity and lack of output schema, the description covers all essential aspects: functionality, parallel execution, output format (findings packet with gaps), time estimate, account requirements, and when to prefer alternatives. It is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema by noting that 'thorough' depth requires a paid plan and explaining the number of facets for each depth level. This extra information is useful, meriting a 4.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources. It distinguishes itself from siblings like ask_pipeworx and clarifies it is not open-web search. The verb 'research' is specific and the resource is 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?

The description provides explicit guidance on when to use (broad/multi-part questions over structured data), when not to use (breaking news or current events), and alternatives (ask_pipeworx for single lookup, news). It also mentions account requirements and paid plan for 'thorough' depth.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable context: '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 discloses what the agent can expect from the output, going 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 somewhat long but is efficiently structured. It front-loads the core purpose and domain list, then details return value and guidance. Every sentence adds information, avoiding fluff. Could be slightly more concise, but the added detail justifies the length.

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

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

Given there is no output schema, the description fully covers what the agent needs to know: what the tool does, when to use it, input parameters (with examples and aliases), and what the output contains (tools with schemas and examples). This is complete for a discovery 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 description coverage is 100%, covering all 6 parameters. The description adds value by explaining aliases for 'query' (q, task, search, description) and gives example queries like 'look up FDA drug approvals' and 'analyze housing market trends'. This helps the agent formulate effective queries.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes from siblings by advising to 'Call this FIRST when you have many tools available and want to see the option set,' setting it apart from more specialized tools like search_within or deep_research.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and '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 and its precedence over other tools.

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

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

Annotations indicate readOnly, idempotent, and nondestructive behavior. The description adds transparency by detailing the sources fanned out (SEC, XBRL, USPTO, news, GLEIF) and noting the USPTO PatentsView API sunset soft-failure, which is valuable behavioral context beyond annotations.

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

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

The description is front-loaded with example queries and provides a dense but structured overview. It is packed with useful information without waste, though the length could be slightly streamlined for quicker parsing.

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

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

Given the absence of an output schema, the description thoroughly explains all return components (cik, company_name, filings with URIs, fundamentals, patents with sunset note, news fallback, LEI) and input constraints, making it fully self-contained for agent understanding.

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

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

Schema coverage is 100%. The description enriches both parameters: for 'type', it clarifies only 'company' is supported; for 'value', it explains the formats (ticker or zero-padded CIK) and explicitly states names are not supported, advising to use resolve_entity first.

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 holistic cross-source profile for US public companies, with specific verb phrases like 'Tell me about X' and differentiates itself from sibling tools by explicitly stating to prefer this over chaining multiple lookups and by referencing resolve_entity for name inputs.

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 (holistic view, prefer over chaining) and when not to use (for names, use resolve_entity first), providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds specific filtering behavior for https_only parameter, which is additional context. 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 extremely concise: one sentence plus a clarifying note. It front-loads the purpose and wastes no words.

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

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

Given the simple two-parameter tool, presence of annotations, and an output schema, the description provides sufficient context for the agent to use the tool correctly. It could note that chain_id_or_short_name is required, but the input schema already enforces that.

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 50% with only https_only having a description ('Default true'). The tool description explains https_only's effect ('filters out ws:// + http:// only'), adding meaning. The other parameter (chain_id_or_short_name) lacks explicit description, but the tool name implies its role. Baseline is 3 for 50% coverage, and description partially compensates.

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 'Return RPC endpoints for a chain', using a specific verb and resource. It distinguishes from sibling tools like 'list_chains' (which lists chains) and 'get_chain' (which likely returns chain details).

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 implicitly indicates use when RPC endpoints for a specific chain are needed. It does not explicitly exclude alternatives or mention when not to use, but the context is clear given the tool name and purpose.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not significantly extend beyond what annotations provide.

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

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

Two sentences, no wasted words, action verb first. Efficient and well-structured.

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

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

For a simple, single-parameter tool with no output schema and good annotations, the description provides complete information: what it does, when to use, and related tools.

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

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

Schema coverage is 100% and the description does not add meaning beyond the schema's own description of 'key' as 'Memory key to delete'. 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 specifies the action ('Delete'), the resource ('previously stored memory by key'), and clearly distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly states when to use ('context is stale, task is done, or clear sensitive data') and suggests alternatives ('Pair with remember and recall'), providing clear context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also notes the output is a single text blob, adding value 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: two sentences plus a bullet list of use cases. It is front-loaded with the core purpose. However, the bullet points could be integrated into the prose 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 complete schema (100% coverage with descriptions), and annotations covering safety and idempotence, the description provides enough context: what the tool does, how it works, and example use cases. No gaps are apparent.

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

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

Schema coverage is 100% with descriptions for url and max_links. The description does not add significant parameter-specific detail beyond the schema, but it reinforces the url context. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the context 'for any URL'. It specifies the target AI crawlers and the output format, and distinguishes itself from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by focusing on file generation.

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 by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not mention when not to use or alternative tools, but the given scenarios are sufficient.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and behavior. The description adds no extra behavioral details beyond input format, so a 3 is appropriate.

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

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

Single sentence, front-loaded with key information, no unnecessary words. Perfectly concise.

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

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

Given the tool's simplicity (1 required param, annotations cover behavioral traits, output schema exists), the description is complete and sufficient. 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 has 100% coverage for the single parameter, describing it as 'Chain id as string or shortName'. The description adds value by clarifying the two formats (number or shortName) and providing examples, going 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 specifies the verb 'Fetch', the resource 'single chain', and the two identifiers (chainId number or shortName). It effectively distinguishes from sibling 'list_chains' which fetches multiple chains.

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

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

The description implies use when needing a single chain by ID or short name. It doesn't explicitly exclude alternatives, but the sibling list provides context. Adequate guidance for the tool's simplicity.

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. The description adds that the registry is for EVM chains and that 'active' defaults true to exclude deprecated chains, providing useful behavioral context beyond annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose.

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

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

The tool has a simple input schema with three optional filters, comprehensive annotations, and an output schema (indicated). The description, combined with structured fields, provides complete context for an agent.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description ('Browse or filter') adds no parameter-specific detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('Browse or filter') and the resource ('EVM chain registry'). It distinguishes from sibling 'get_chain' which retrieves a single chain.

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 context of 'Browse or filter' implies listing vs. single retrieval, but no explicit when-not or alternative guidance is provided. Sibling tool 'get_chain' serves the single-chain use case, but this is not stated.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds context that it returns specific fields and defaults to active subscriptions only, with an option to include inactive ones.

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, front-loaded with purpose and return fields, then usage guidance. No wasted words.

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

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

Given a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage. Minor omission: no mention of pagination or ordering, but not critical for this tool.

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

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

Schema coverage is 100% (one parameter described). Description does not add new parameter details beyond what the schema provides, but clarifies default behavior (active only). 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 lists the caller's active subscriptions and enumerates the return fields. It is distinct from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit use cases: reviewing monitored subscriptions before adding more and finding IDs to cancel. Does not explicitly mention when not to use, but context is sufficient.

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

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

Annotations are all false, so the description carries full burden. It discloses rate limits (5/day), that it doesn't count against quota, and the signal-to-roadmap impact. 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?

Front-loaded with clear purpose, followed by usage contexts, then behavioral details. Every sentence adds value; no fluff. Appropriate length for the complexity.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers inputs, constraints, and impact. It tells the agent everything needed to submit appropriate feedback.

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, but description adds actionable guidance for the `message` field (describe in terms of tools/packs, avoid pasting prompts) beyond the schema description. 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 purpose: collecting feedback on broken, missing, or needed tools. It lists specific types (bug, feature, data_gap, praise) and distinguishes from sibling tools by focusing on feedback rather than queries or actions.

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

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

Explicitly describes when to use: for bugs, missing features/data, or praise. Provides anti-guidance ('don't paste the end-user's prompt') and notes rate limits. No other sibling tool has such usage 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, non-destructive. The description adds value by explaining the data source (CF analytics-engine), mentioning no PII, and specifying caching freshness (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?

Two concise paragraphs: first states the core functionality, second lists use cases. No redundant sentences. Front-loaded with essential info.

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 return types (top tools, top packs, total call volume). Parameter documentation is complete. Caching and use cases provide sufficient context for an agent to decide when to call.

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 single parameter 'window' having both enum and description. The tool description repeats the window options but does not add new semantics not already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states it 'Returns the top tools, top packs, and total call volume over a recent window'. The verb 'returns' and resource 'trending data about other AI agents' calls on Pipeworx' are specific. It distinguishes from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated usage stats.

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 provided (discovering hot data sources, confirming canonical choice, alignment checking). It also mentions caching behavior. However, there is no explicit 'when not to use' or direct comparison with alternatives, which would strengthen it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true. The description adds extensive behavioral context: algorithms used (monotonicity, partition checks, fill check), filtering logic (semantic anchor, placeholder filter), and conditions for signals. 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 front-loaded with purpose and structured by mode. It is somewhat lengthy but necessary given complexity. Some redundancy (e.g., repeating 'NO args') could be trimmed, but overall well-organized.

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

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

Despite missing output schema, the description explains the response structure (opportunities array, partition_check results, fill check details). It covers all modes and edge cases (placeholder filtering, fill check rejection). Very complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds significant meaning beyond schema: explains modes, provides examples, describes algorithms and outputs. This helps an agent understandParameter semantics thoroughly.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (no args for trending_scan, event for specific market, topic for cross-event) and distinguishes from sibling tools like polymarket_fill_risk.

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

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

The description tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event. It recommends event mode and mentions an alternative sibling (polymarket_fill_risk) for custom sizing. However, it does not explicitly exclude other arbitrage tools or provide when-not-to-use.

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

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

The description goes far beyond annotations, detailing caching (1h at KV level), response structure with diagnostics, filtering logic, Fed bet handling, and why segments may be empty. Annotations (readOnlyHint, etc.) are consistent with no contradictions.

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

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

The description is long but well-structured with clear sections and logical flow. It front-loads the purpose and uses formatting like all-caps for segment names. Minor verbosity in explaining model details, but each sentence adds necessary context for the tool's complexity.

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

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

Given 9 parameters and no output schema, the description completely covers the response structure (by_segment, diagnostics, Fed note) and explains caching. It provides all necessary context for an agent to understand when to use and what to expect, making it fully self-contained.

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

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

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The tool description adds significant extra context, such as explaining slippage assumptions, tradeable-edge knobs (min_liquidity, max_spread_pp), and min_partition_leg_kelly's specific behavior, adding value beyond the schema.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes itself from sibling tools like polymarket_arbitrage by focusing on the 'what should I bet on today' use case and avoiding paging through hundreds of markets.

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

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

The description explains when to use the tool ('what should I bet on today') and details the three segments and their conditions. It provides guidance on tradeable-edge knobs but does not explicitly mention when not to use or compare to alternatives like bet_research or polymarket_arbitrage.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral details: snapshot TTL (60 days), daily closes of edge_pp_net (net default slippage, not intraday), and explains the response structure (tracked, expired, snapshot_dates). This goes well 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 detailed (150+ words) but well-structured: purpose sentence, example question, args, response breakdown, limits. It is front-loaded and each sentence adds necessary information for a complex tool. Minor compression possible but suitable.

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

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

No output schema exists, so the description fully explains return fields: tracked[] with full time-series, first_seen, trend, decay; expired[] with lifespan_days; snapshot_dates. It also covers limits (TTL, snapshot origin). Complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters. The description adds context: 'days' default 14, max 30 (schema says clamp 2-30, consistent), and explains 'window' as 'snapshot family' with default '1wk', reinforcing schema values. This adds value beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes from simple edge listings by highlighting that a 3-week-old wide edge is different from a fresh one, differentiating it from siblings like polymarket_edges.

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

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

The description implies usage when needing temporal edge persistence (e.g., 'how long has this edge existed?'). It provides clear context but does not explicitly state when not to use or name alternatives. The example question guides usage effectively.

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 comprehensively outlines behavioral traits, including the verdict output (clean|degraded|cannot_fill), return fields, and risks like thin legs and forced directional risk. Annotations already indicate readOnly, openWorld, idempotent, and non-destructive, and the description adds valuable context beyond these.

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

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

The description is long but well-structured with bold headings for modes and key warnings. It front-loads the main purpose and uses formatting for emphasis. Minor verbosity but still efficient for the complexity.

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

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

Given the tool's complexity (two modes, many return fields, no output schema), the description thoroughly covers what the agent needs: return values, risk factors, and usage context. It explains the implications of thin books and directional risk, making it complete for decision-making.

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

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

All four parameters have schema descriptions (100% coverage), and the description adds extra semantics: clarifies size_usd interpretation for single-market vs basket, side auto-detect for basket, and default values. 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: checking realizable-vs-theoretical edge against live CLOB order-book depth. It specifies two distinct modes (single-market and basket) and differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill feasibility.

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

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

Explicit guidance on when to use: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It warns against partial basket fills converting arb into unhedged directional position, providing clear context for tool selection.

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

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

Adds significant behavioral details beyond annotations: explains safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) and conditions when spreads are meaningless. No contradiction with readOnly/idempotent 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?

Well-structured with clear sections bolded, front-loaded purpose and modes. Some redundancy in the safety warnings section could be trimmed, but overall efficient for the complexity described.

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

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

Despite no output schema, description fully explains response structure (leg-by-leg prices, spread, compatibility fields) and handles edge cases (mismatched bet shapes, temporal alignment). Complete for a cross-venue spread 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 already has 100% coverage with descriptions for all 3 parameters. Description supplements by listing the 10 topic shortcut values and clarifying that explicit tickers override topic mapping, adding context 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 explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Describes two modes (topic shortcuts and explicit pairings) and warns that most pre-mapped topics return compatibility_warning. However, does not explicitly compare to specific sibling tools for when to use this over polymarket_arbitrage or polymarket_edges.

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

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

Description adds critical context beyond annotations: scoping to identifier and behavior when key is omitted. 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?

Four sentences, front-loaded with main purpose. No redundant words. Every sentence adds value.

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

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

Fully addresses the tool's purpose, usage, scoping, and listing behavior. Suitable for a simple tool with one optional parameter and strong annotations.

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

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

Schema coverage is 100% and description restates schema info. No additional parameter meaning beyond what schema provides. Baseline 3.

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

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

Clearly states 'Retrieve a value previously saved via remember, or list all saved keys'. Specifies verb and resource, distinguishes 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 states when to use: 'to look up context the agent stored earlier'. Mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use scenarios, but adequate.

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 cover readOnly, idempotent, non-destructive nature. Description adds unique behavioral details: mark_read flag marks events read to shift future polling, and notes polling works fine. No contradictions, but some behavioral aspects (e.g., rate limits, auth) are omitted.

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

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

Three sentences with front-loaded purpose and key details. Very concise without omitting critical information. Slight improvement could be bullet-listing parameters, but structure is clear and efficient.

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

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

Despite no output schema, description specifies return fields (source, citation_uri, raw payload). Explains filtering, mark_read effect, and alternative access method. For a read-only polling tool with rich annotations, this is fully 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 parameters. Description adds significant context beyond schema: explains that mark_read flags events read so next call returns only newer events, and clarifies the effect of unread_only. This enables the agent to use parameters effectively.

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

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

Clearly states the tool pulls fired events from subscription feed, with specific fields returned (source, citation_uri, raw payload). Distinguishes by mentioning filter options (type, since) and alternative endpoint, ensuring no confusion with sibling tools like list_subscriptions or search_within.

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

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

Explicitly describes when to use (pulling fired events, polling) and provides an explicit alternative (GET registry.pipeworx.io/alerts.json for scripts/dashboards). The description also hints at when mark_read is useful, guiding agent decision-making.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: fans out to multiple sources (SEC, GDELT/GNews fallback, USPTO), explains soft-failures, and describes the return structure. No contradictions.

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

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

The description is comprehensive but front-loaded with query examples and structured with an alternative tool mention. While slightly verbose, every sentence adds useful information, earning it a 4.

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

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

Given the tool's complexity (multiple sources, fallbacks, soft-fails) and lack of output schema, the description fully covers expected behavior, return structure (grouped changes, counts, URIs), and edge cases like USPTO sunset. It is complete for an agent.

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

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

Schema description coverage is 100%, baseline 3. The description adds value by explaining 'since' format (ISO or relative) and recommending typical values, and clarifying 'value' accepts ticker or CIK. It also contextualizes parameters within the tool's multi-source behavior.

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

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

The description explicitly states the tool provides a change feed for a company with example queries like 'What's new with X' and distinguishes from sibling tool entity_profile, which handles static profiles. It clearly identifies the action as fetching dynamic changes over a window.

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

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

The description provides explicit when-to-use guidance via query examples and recommends using entity_profile for static profiles instead. It also advises on 'since' parameter values like '30d' for typical monitoring.

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 beyond annotations: persistence behavior (24h for anonymous, permanent for authenticated), scoping by identifier, key-value storage. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Two efficient sentences, no wasted words. Front-loaded with purpose, then usage guidance, then behavioral details. Perfect 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?

No output schema needed—description suffices by explaining storage mechanism and pairing with retrieval/deletion tools. Complete for a simple key-value store 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?

Although schema coverage is 100% and schema already describes key and value with examples, the description adds context about using key-value pairs for storing various findings. Slightly above baseline 3 because it clarifies the purpose of each parameter.

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

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

The description starts with a clear verb+resource: 'Save data the agent will need to reuse later'. It distinguishes itself from siblings like 'recall' (retrieve) and 'forget' (delete) by explicitly pairing with them.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Specifies scope and persistence details (authenticated vs anonymous). Mentions companion tools recall and forget.

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

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

The description adds significant behavioral context beyond annotations, such as internal cascading lookups, auto-disambiguation, and citation URIs. Annotations already indicate safety (readOnly, idempotent), so description enriches rather than repeats.

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, well-structured, and front-loaded with examples. Every sentence earns its place, and it avoids redundancy with the schema.

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

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

Given no output schema, the description fully explains return values and internal behavior. It covers both supported types adequately, making the tool self-contained for an agent.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains what each type returns (ticker, CIK, company name for company; RxCUI, ingredient, brand for drug) and that company accepts multiple input forms and auto-disambiguates. This goes well beyond the schema.

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

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

The description uses specific verbs and resources ('resolve a user-spoken NAME to the canonical/official identifier') and provides concrete examples ('What's the ticker for…'). It clearly differentiates from sibling tools by focusing on entity resolution as a first step.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' While it doesn't provide explicit exclusions or alternatives, the context is clear for when to invoke this tool.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks results, and returns score/confidence/signal density. No contradictions with annotations.

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

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

Four sentences, front-loaded with purpose and key use case. Every sentence adds value; no fluff. Efficient and well-structured.

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

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

Given no output schema, the description explains return format (score, confidence, signal density). Covers inputs, internal probe, and output. Lacks detail on ranking algorithm, but sufficient for correct selection and invocation.

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

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

Schema descriptions cover all 4 parameters (100% coverage). The description adds extra context: entities array first entry is treated as subject, models omit for default workers-ai, context disambiguates common names. This enhances schema meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the internal probe and ranking 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 context for competitive AI-marketing audits with an example question. It mentions the first entity is treated as subject, but does not explicitly exclude alternatives or state when not to use it versus siblings like compare_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 readOnlyHint true, openWorldHint true, idempotentHint true, destructiveHint false. The description adds critical behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This discloses performance characteristics and error behavior, adding value beyond annotations.

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

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

The description is a single dense paragraph that front-loads the purpose and then covers usage, limitations, and behavior. Every sentence adds value, but it could be slightly more structured with line breaks. There is no fluff, but the length is justified by the tool's complexity.

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

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

Given the composite nature of the tool, the description thoroughly covers purpose, parameters, output (listing all return fields), edge cases (scoped packages, version default, performance delay, partial failures), and ecosystem scope. There is no output schema, so the description bears full burden and succeeds.

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

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

Schema coverage is 100% with both parameters described. The description mentions that scoped packages are accepted for 'package' and defaults to latest for 'version', which mostly echoes the schema. It adds no new syntactic or semantic details beyond what the schema already provides, 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 explicitly states the tool performs a composite check combining deps.dev and bundlephobia to answer whether to add an npm package. It clearly distinguishes itself from siblings by being a one-call composite for npm packages. The verb 'scan' is appropriate and the resource is 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?

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also tells when not to use it: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear differentiation from alternatives.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds technical details: embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K chars with truncation flag), and that passage offsets enable quote verification. No contradiction with annotations.

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

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

The description is well-structured with the core purpose upfront, followed by use case, pairing, and technical details. It is slightly wordy but every sentence adds value.

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

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

Given no output schema, the description compensates by explaining return values (passages with offsets and scores). It covers technical limits, embedding details, and relationship to sibling tool ask_pipeworx_grounded, making it complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds example queries and reminds of the 200K char limit for text, but the schema already describes all parameters adequately.

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 does semantic search inside a fetched record, specifying it returns passages with offsets and scores. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description explicitly advises using this tool when records are too large to fit in the prompt, saving context. It also mentions pairing with ask_pipeworx_grounded, but does not provide explicit when-not-to-use 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 indicate idempotency, but description adds operational details: requires OAuth, SMS 10/day cap, webhook auto-disabled after 10 failures, webhook secret returned once. No contradictions with annotations.

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

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

Description is well-structured and packs substantial information, but could be slightly more concise. Every sentence adds value; the format is clear.

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

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

For a tool with multiple types and delivery channels, the description covers all aspects: prerequisites, type-specific parameters, delivery options with constraints, and expected return (subscription ID). No output schema exists, but the description suffices.

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?

Description provides extensive examples for the params object exceeding schema descriptions, e.g., sec_8k items, polymarket_edge topic and min_spread_bps, fred_series series_id. Also explains delivery constraints and webhook behavior, adding significant 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?

Description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returns subscription ID, and lists supported types and delivery channels. It distinguishes from sibling tools like unsubscribe 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?

Description explicitly requires a Pipeworx OAuth account and states that anonymous/BYO cannot persist subscriptions, which guides when to use. It details supported types and delivery options, but does not explicitly contrast with other tools like ask_pipeworx or recent_alerts.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context beyond annotations: it returns 'category-bucketed example questions' with 'exact tool + argument shape' drawn from a live catalog. It does not contradict annotations and enriches understanding of the tool's output and data source.

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

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

The description is moderately long but each sentence adds value: example user queries, output structure, parameter guidance, and usage recommendation. It is front-loaded with common user questions. While it could be slightly condensed, there is no redundancy or wasted words.

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

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

Given the tool's role as an onboarding guide, the description is quite complete: it explains what the tool returns, how to call it, and when to use it. The lack of output schema is compensated by describing the output as 'category-bucketed example questions with tool and argument shape'. It also mentions the live catalog nature. However, it does not specify the exact response format or pagination, but that is acceptable for this discovery 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 description coverage is 100%: the only parameter 'topic' is already fully described in the schema with allowed values and the note to omit for cross-category. The description repeats nearly the same information without adding new meaning. Thus, it meets the baseline of 3 but does not exceed it.

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

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

The description explicitly states the tool is the onboarding entry point for new agents, using phrases like 'What can I ask Pipeworx?' and 'the onboarding entry point'. It clearly distinguishes itself from siblings by stating 'Use this FIRST' and mentions it helps learn how to call meta-tools, setting it apart from tools like ask_pipeworx or entity_profile.

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

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

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains when to use no arguments vs. a specific topic. It indirectly tells when not to use it (when you already know what to ask). This is clear and helpful for an AI agent.

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 beyond annotations: row is deactivated not deleted, and links to recent_alerts for historical events. 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?

Two sentences with no wasted words. Action, constraint, and effect are front-loaded.

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

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

Complete for a simple tool with one parameter and no output schema; clarifies ownership and side effects.

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

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

Schema coverage is 100%; description confirms id comes from subscribe, adding minimal but helpful context.

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

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

The description specifies the verb 'Cancel' and resource 'subscription', and distinguishes from siblings by mentioning ownership enforcement and the deactivation effect.

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 constraint ('you can only cancel your own subscriptions'), providing clear when-to-use guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: supported claim domain (company-financial), data sources (SEC EDGAR + XBRL), return verdicts, and citation format. It does not disclose limitations like only US public companies, but the annotations set a baseline so additional context earns a high score.

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

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

The description is a single paragraph but is well-structured: it starts with example intents in quotes, then explains when to use, then details domain and output. It is informative without being overly verbose; every sentence adds value. Minor conciseness improvement possible, but overall solid.

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 1 parameter, no output schema, and rich annotations, the description is fairly complete. It explains the output verdicts, includes efficiency gains, and covers domain scope. However, it lacks details on error handling, claim format constraints, and coverage limitations (e.g., only US public companies), which would make it fully comprehensive.

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 single parameter 'claim' described. The description adds meaning beyond the schema by specifying the kind of claims supported (company-financial) and providing concrete examples, which aids correct invocation. Since baseline is 3 due to high schema coverage, the added value pushes it to 4.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It provides specific verb ('validate claim') and resource ('authoritative sources'), and distinguishes from sibling tools by its specialized domain and efficiency gains.

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 tells when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and lists example intents. However, it does not provide explicit guidance on when not to use it or direct alternatives among siblings, though the efficiency mention implies superiority over multi-call approaches.

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