Overheid Nl

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds meaningful context: default model, optional API key for Anthropic, costing note (BYO key), and return structure. It does not contradict annotations and enriches behavioral understanding.

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 (4 sentences), front-loaded with the primary action and output, followed by model details, return format, and use cases. No wasted words; every sentence adds value.

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

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

Given 4 parameters and no output schema, the description explains the tool well covering action, parameters, return structure, and use cases. It could be more complete by detailing the 'signals' field or scoring methodology, but overall it's 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 good parameter descriptions. The description adds little beyond the schema, only reiterating default model and API key usage. It does not provide additional semantic value for parameters.

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 scores visibility (0-100). It specifies verb 'probe', resource 'LLMs', and mentions use cases. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', lacking distinctiveness.

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 some usage context (AI-marketing audits, pre-launch checks, competitive monitoring) but does not give explicit when-to-use or when-not-to-use guidance. It implies usage but lacks exclusions or comparisons to alternatives.

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

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

Adds context beyond annotations: explains routing across 4,482 tools and 1,129 sources, argument filling, and returning structured answers with pipeworx:// citation URIs. Annotations already indicate read-only, open-world, idempotent; description reinforces and extends.

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 the key directive 'PREFER OVER WEB SEARCH', followed by structured sections. While lengthy, each sentence adds value; slight verbosity prevents a perfect score.

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

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

Comprehensive: covers purpose, usage, routing, example queries, and return format (structured answer with citations) despite no output schema. Complements sibling tools well.

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

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

Schema coverage is 100%, but description adds value by explaining that the question parameter accepts multiple aliases (q, text, input, query, prompt) and is natural language. Examples further clarify 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's purpose as a preferred alternative to web search for structured data queries, listing many specific data types (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'START HERE for most questions' and provides detailed guidance on when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). Also mentions default behavior for live news.

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, so the tool is safe. The description adds valuable behavioral detail: explicit refusal reasons, evidence extraction, and cost of one extra LLM call. Does not contradict annotations.

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

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

Single dense paragraph that front-loads purpose, then explains process, return format, usage guidance, and cost — every sentence is meaningful with no redundancy.

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

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

For a complex tool routing across 4,482 tools, the description covers purpose, process, output, and usage boundaries. Lacks detail on what 'tools' are or how routing works, but output schema is not needed since return format is described.

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 (question and aliases). The description does not add insight 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 clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from its sibling ask_pipeworx by specifying the extra cost and the strict answer-with-evidence return format.

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

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

Explicitly states when to use (high-stakes, quoted/cited answers, no fact invention) and when to prefer the sibling (casual lookups), providing clear decision criteria.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior, and the description does not contradict this. It adds extensive behavioral context: market resolution, classification, fan-out, safety checks (low-confidence short-circuit, closed markets), resolution-rule risk parsing, and news fallback handling. No contradiction.

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

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

The description is very long (≈300 words) and exhaustive, including many examples and edge cases. While well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), it lacks conciseness for a quick overview. It could be trimmed while retaining value.

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

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

Given the tool's complexity (multi-source data aggregation, risk analysis, resolution handling), the description covers all essential aspects: inputs, resolution process, fan-out logic, output structure, safety protocols, and risk considerations. Without an output schema, the description fully compensates.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds extra context: examples for market_input, explanation of depth parameter (quick vs thorough), and detailed rationale for include_raw (response size trade-offs). This goes 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 researches Polymarket bets using Pipeworx data. It specifies input types (slug, URL, question text), output components (evidence packet, market-vs-model comparison), and distinguishes from sibling tools by focusing on a single bet with multi-source fan-out.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it doesn't explicitly state when not to use, the context and alternatives are implied through sibling tools and the detailed description of its capabilities.

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 substantial behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorted results, and citation URIs. 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 concise and well-structured, front-loading the core purpose with example queries. Every sentence adds unique value, covering usage, data sources, result format, and efficiency gains. No redundancy or fluff.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description fully covers what the tool does, what data it returns (paired data + citation URIs), and how results are sorted. It is complete for agent selection and invocation.

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

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

Schema coverage is 100% with parameter descriptions, but the description enriches by explaining the data pulled for each type (e.g., latest 10-K financials for companies, adverse-event counts for drugs) and the array constraints (2-5 items). This adds significant value over the schema alone.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, with examples like 'compare X and Y'. It explicitly differentiates from sequential single-pack lookups and sibling tools like 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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists example queries and explains when to use for companies vs drugs, making usage context very clear.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds that the portal is metadata-only, meaning no raw data is returned, and instructs to fetch URLs. This provides 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?

Two sentences cover purpose and key usage details without any fluff. The main action is front-loaded, and the additional context is efficiently appended.

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 1-parameter tool with comprehensive annotations and no output schema, the description is complete. It explains what is returned and what to do with the data, leaving 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?

The single parameter 'id' is fully described in the schema with an example. The description reinforces that it accepts id or slug and mentions the return of resources, adding minimal extra semantic 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 retrieves a full dataset record by id or slug, including resources. It uses a specific verb ('get' implied) and resource ('dataset record'), and distinguishes itself from sibling search/list tools.

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

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

It explains the return includes resource URLs and formats, and notes that the portal is metadata-only, so actual data must be fetched. This gives clear usage context, though it doesn't explicitly state when not to use it or list 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?

Adds significant context beyond annotations: account needed, paid plan for 'thorough', parallel execution, returns gaps[] for unanswered facets, 15-60s response time, no open-web search. No contradictions with annotations.

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

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

The description is detailed and front-loaded with the critical account requirement. While it is long, every sentence adds value. Minor redundancy could be trimmed, but overall well-structured.

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

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

Given the tool's complexity, 31 sibling tools, and no output schema, the description covers prerequisites, alternatives, performance, behavior, limitations, and examples. Highly 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%, but the description explains the depth enum values (quick=3, standard=5, thorough=8) and clarifies that the question should be natural language and multi-part, which is beyond the schema's minimal descriptions.

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

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

The description clearly states it performs 'grounded multi-source research' across Pipeworx's structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes itself from siblings like ask_pipeworx for single lookups and current-news queries.

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

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

Explicitly tells when to use this tool (broad/multi-part structured data questions) and when not (if not signed in, use ask_pipeworx; for breaking news, prefer ask_pipeworx). Also details account requirements and plan tiers.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: returns full input schemas with examples, ready to call directly, and no second lookup needed. No contradiction.

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

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

The description is concise and well-structured: purpose first, then examples, then what it returns, then strategic advice. Every sentence adds value.

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

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

Despite no output schema, the description fully explains what is returned (top-N tools with names, descriptions, schemas) and how to use it. 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 coverage is 100%, and the description doesn't add significant meaning beyond the schema. The description mentions 'query' and its aliases, but schema already explains. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples and distinguishes itself as a meta-tool for discovery, not a domain-specific tool.

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

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

The description explicitly advises when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It does not explicitly state when not to use, but clear context is provided.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds details about fanning out across multiple sources, specific fields returned, and soft-fail behavior for patents. 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 somewhat lengthy but front-loaded with examples and clear structure. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Despite no output schema, the description thoroughly explains what the tool returns and its limitations (e.g., patents soft-fail, only company type). Complete for a complex multi-source lookup tool.

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

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

Schema coverage is 100%, but description adds critical context: 'Ticker or zero-padded CIK', 'names not supported', and 'type' enum limited to 'company'. This goes beyond schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company' and lists specific data returned (CIK, filings, fundamentals, patents, news, LEI). Distinguishes from sibling tools like resolve_entity.

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

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

Explicitly advises to prefer over chaining single-pack lookups for a holistic view. Provides example user queries and states when not to use (names not supported), directing to resolve_entity first. Also notes patent soft-failure after May 2025.

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

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

Annotations already provide destructiveHint and idempotentHint. The description adds context about clearing sensitive data, which is useful but not extensive.

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

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

Two sentences, front-loaded with the action, and no wasted words. Highly 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?

For a tool with one required parameter, no output schema, and clear annotations, the description is complete. It explains when to use and how it relates to sibling 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% with one parameter 'key' described as 'Memory key to delete'. The description does not add additional semantics 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 'Delete a previously stored memory by key', which is a specific verb+resource combination. It distinguishes itself 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?

The description explicitly lists use cases: when context is stale, task done, or to clear sensitive data. It does not explicitly state when not to use, but the context makes it clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the process beyond what annotations provide, and no contradiction exists.

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

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

The description is two clear sentences plus a concise bullet-style list of use cases. It is front-loaded with the main purpose and every sentence contributes without repetition or fluff.

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

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

Despite no output schema, the description states the output is a 'single text blob ready to drop at site-root/llms.txt.' This covers return format. With two well-documented parameters and simple behavior, the description is complete.

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

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

Schema description coverage is 100%: both url and max_links have descriptions. The tool description does not add new parameter semantics beyond what the schema already provides (e.g., 'default 25, max 50' is in schema). Baseline 3 is appropriate since the description adds no extra meaning.

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

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

The description clearly states it 'Generate a production-ready llms.txt file for any URL' and lists specific use cases (getting client site indexed, drafting own, auditing competitor). This is a specific verb+resource that distinguishes it from sibling tools like ai_visibility_check or bet_research which have different purposes.

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

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

The description provides explicit contexts: 'Useful for: 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 implies when to use but does not explicitly state when not to use or mention alternatives; however, given the tool's uniqueness among siblings, this is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the crucial context that the portal currently exposes no groups, which goes beyond annotations.

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

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

Two concise sentences: one for purpose, one for caveat and alternative. No redundant information.

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

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

Given the simple tool (1 param, high schema coverage, no output schema), the description fully covers purpose, limitation, and alternative, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% with a single parameter 'limit' fully described. The description does not add additional semantic value beyond what the schema provides.

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

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

The description clearly states the verb 'List' and resource 'thematic groups/categories' on a specific portal, differentiating it from sibling tools like search_datasets.

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 notes that the tool returns empty results and advises preferring 'search_datasets' with fq facets, providing clear when-to-use and alternative guidance.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds useful context about the specific CKAN API endpoint but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

The description is two well-structured sentences. The first sentence concisely states the tool's purpose, and the second provides a concrete usage tip. No fluff or redundancy.

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

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

Given the tool's simplicity (single optional parameter), the description covers the core purpose and provides a cross-reference. It does not mention the output format, but for a list function the default list structure is expected. Overall it is mostly 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?

The input schema fully describes the single parameter 'limit' with its range and default. The description does not add any additional semantic meaning to this parameter, so it meets the baseline but provides no extra value.

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

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

The description clearly states the action ('List') and the resource ('publishing organizations (ministries/agencies/provinces)') and specifies the data source (data.overheid.nl). It also includes a helpful hint about using the output with another tool (search_datasets), differentiating it from siblings like 'list_groups'.

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 a common use case: using an org name from the list in the search_datasets tool's fq parameter. However, it does not discuss when to avoid this tool or mention alternatives among siblings, leaving some room for ambiguity.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return field detail and active status. No contradictions.

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

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

Two efficient sentences: first explains function and output, second guides usage. No redundancy.

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

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

For a simple list tool with one optional parameter, description covers return fields, default behavior, and use case. No output schema, so return info is sufficient.

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

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

Schema covers parameter fully. Description reinforces 'active' vs inactive, adding context beyond schema. Baseline 3 +1 for extra clarity.

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

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

Clearly states verb 'List', resource 'subscriptions', and specifies scope ('caller's active'). Distinguishes 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?

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides clear context and alternative actions.

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 context beyond annotations (readOnlyHint, destructiveHint false), disclosing rate limits (5 per identifier per day), cost (free), and quota behavior (doesn't count against tool-call quota). 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?

Concise, front-loaded single paragraph with no wasted words. Every sentence serves a purpose: purpose, usage guidance, constraints, and behavior.

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 3 parameters, full schema coverage, no output schema, and zero sibling overlap, the description fully covers what the agent needs: purpose, when to use, what to include in the message, rate limits, and non-quota behavior. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by elaborating on the 'message' parameter's content guidance ('Describe the issue in terms of Pipeworx tools/packs') and reinforcing enum type meanings. However, much of the parameter info is already in the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific types (bug, feature, data_gap, praise) and distinguishes itself from all siblings, none of which handle feedback.

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

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

Provides explicit guidance on when to use: bug, feature/data_gap, praise. Advises against pasting end-user prompts and mentions rate limits. Lacks explicit 'when not to use' alternatives, but the tool is unique in its category, so the omission is minor.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds crucial behavioral details: data source (CF analytics-engine), privacy (no PII), aggregation method (self-aggregating), and caching (5min-1h depending on window). This provides rich transparency.

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

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

The description is concise yet comprehensive, using a clear introductory sentence followed by bullet-pointed use cases. Every sentence adds value, and the structure is front-loaded with the core purpose.

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

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

Given there is no output schema, the description adequately describes the return data (top tools, top packs, total call volume) and window options. However, the exact format of the response (e.g., list vs. object, attributes per item) is not specified, which could require an agent to infer or test. Still, it is mostly complete for the tool's simplicity.

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 sole parameter 'window' is fully described in both the schema (enum, description) and the narrative description. The description adds semantic value by explaining the trade-off between shorter and longer windows ('hot right now' vs 'steady-state demand'), which goes beyond the schema's basic definition.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over configurable time windows, using specific verbs and resource nouns. It distinguishes itself from sibling tools by focusing on trending/aggregate data rather than individual queries or entity 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?

Three specific use cases are enumerated, providing clear when-to-use guidance. While no explicit when-not-to-use is given, the listed use cases effectively convey the tool's purpose and avoid ambiguity. No alternatives among siblings are explicitly mentioned, but the context is clear enough.

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

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

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds extensive behavioral details: required parameters, processing logic (monotonicity, partition checks), semantic anchor for cross-event, partition filter, response structure, and fill-check against live depth. 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 lengthy but well-structured: starts with requirement and purpose, then details each mode, followed by conditions and response. Every sentence adds value, though some redundancy could be trimmed. Front-loaded with critical requirement.

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

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

For a tool with no output schema, the description thoroughly explains the response (opportunities, partition_check, fill_check). It covers edge cases (low similarity, placeholders, book depth) and references a sibling tool for custom sizing. Context is complete for effective use.

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

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

Schema already covers both parameters with descriptions, but the tool description adds significant context: recommended use cases, examples of valid inputs, and details on how each mode works (e.g., event walks child markets, topic flattens union). This enhances understanding beyond the schema.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with two distinct modes (event and topic). It specifies the verb (find), resource (Polymarket opportunities), and differentiates between single-event and cross-event 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?

Explicitly states that one of `event` or `topic` is required, and provides recommendations for when to use each mode. It does not explicitly exclude scenarios or mention alternatives, but the guidance is clear for a specialized 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 (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false) already convey safety and idempotence. The description adds substantial behavioral context: caching (1h at KV level keyed on all knobs), internal model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), filtering logic (placeholder-slug filter, partition skipping), and response diagnostics. 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 lengthy but well-structured: front-loaded purpose, then model families, then knobs, then response format, then caching. Every sentence serves a purpose, but some internal details (e.g., specific α values, funnel counters) could be trimmed without losing core guidance. The use of visisble keys (e.g., "TRADEABLE-EDGE KNOBS:") aids scanability.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment with three segments, diagnostics, fed candidates). It covers edge_pp_net, kelly_fraction, market attributes, and 24h-move warning. All 9 parameters are explained and knob suggestions given. The description compensates fully for the lack of output schema and provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% (all 9 parameters described in input schema), baseline 3. The description adds extra semantic value for key parameters: e.g., for max_spread_pp it suggests "Set to 2 to require tight books", for min_liquidity it says "Set to 5000 to drop thin-book opportunities", and for min_partition_leg_kelly it explains why min_kelly doesn't apply to partitions. These provide actionable guidance beyond the schema.

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

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

The description opens with a clear verb+resource: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It further states it's built for "what should I bet on today" — agents discover opportunities without paging. This sufficiently distinguishes from siblings like polymarket_arbitrage or bet_research by focusing on Pipeworx data disagreement and consolidated edge 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 implies usage (discovering betting opportunities from Pipeworx differences) but does not explicitly state when to use this tool versus alternatives such as polymarket_arbitrage, bet_research, or polymarket_kalshi_spread. No when-not or direct comparisons are given, leaving the agent to infer context from the tool name and sibling list.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds valuable behavioral details: time-series computation, trend categories, expired opportunities, snapshot gaps due to cache-misses, and decay calculation from daily closes. 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 purpose, then args, then detailed response structure and limits. Every sentence is informative, though the response description is lengthy but necessary given no output schema. Well-organized for readability.

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

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

No output schema, so description fully specifies return fields (tracked, expired, snapshot_dates) with semantics. Covers input defaults, limits (TTL, snapshot start), and behavioral caveats (gaps). Complete for an AI agent to use effectively.

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

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

Schema documentation covers both parameters with defaults and ranges. Description adds context by explaining the meaning of 'window' as snapshot family and the output structure, going beyond schema. Minor discrepancy: schema says clamp 2-30, description says max 30, but overall adds value.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. Differentiates from sibling tools like polymarket_edges by focusing on historical time-series rather than current 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?

Explicitly contrasts fresh vs old edges to guide usage. Mentions limits like 60-day TTL and snapshot start. Does not explicitly name alternatives, but context from sibling tools implies when not to use (e.g., for current edges, use 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?

Annotations already declare readOnly, idempotent, non-destructive. Description adds: requires one of market/event, walks ladder, returns specific fields (top of book, VWAP, slippage, verdict, per-leg details), and warns about forced directional risk. 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 long but well-structured with sections (SINGLE-MARKET, BASKET). Every sentence is informative; could trim some redundant phrasing but overall 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?

Despite no output schema, description fully explains return values for both modes, including verdict, thin legs, max clean notional, forced directional risk. References sibling tools and addresses key risk. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, but description adds substantial context: side defaults and basket auto-detection, market/event modes, size_usd interpretation (max spend vs target proceeds vs settlement notional) and clamp range. Adds meaning beyond schema.

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

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

Clearly states verb+resource: 'realizable-vs-theoretical edge check against live CLOB order-book depth'. Distinguishes between single-market and basket modes, and explicitly mentions sibling tools polymarket_arbitrage and polymarket_edges to differentiate.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why: theoretical overround not capturable, partial basket fills lead to unhedged positions. Covers when-not-to-use implicitly.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description goes far beyond by explaining response structure, compatibility warnings, temporal alignment, and leg-matching logic, providing rich behavioral context that helps the agent interpret results correctly.

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 (purpose, modes, response, safety fields). Every sentence adds substantive information, though the length could be trimmed slightly without losing meaning.

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 covers the full response including leg prices, spread array, and all safety fields (compatibility_warning, temporal_alignment, skipped counters). Handles edge cases like cross-type mismatches, making it self-contained.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the topic macros and explaining how explicit tickers override topic-mapped selections, plus examples. Slightly redundant with schema but still additive.

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 computes cross-venue spreads between Kalshi and Polymarket for the same question, with two modes (topic shortcuts and explicit tickers). It distinguishes from siblings like polymarket_arbitrage which likely operates within a single venue.

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

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

Provides explicit guidance on when spreads are meaningful (equivalent bet shapes) and when not (compatibility warnings, temporal misalignment). It also warns that most pre-mapped topics return warnings, setting expectations. Could be improved by directly contrasting with 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 already declare readOnlyHint=true and idempotentHint=true. Description adds context about scoping to identifier and pairing behavior, but does not contradict annotations. Slight additional 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?

Two concise sentences that front-load the primary purpose and provide efficient secondary 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 no output schema, the description explains return behavior (value or list of keys) and scoping, making it fully 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% and the schema description already states 'omit to list all keys'. Description reinforces this but does not add new parameter semantics 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?

Uses specific verbs 'retrieve' and 'list', clearly names the resource (values saved via remember), and distinguishes from sibling tools 'remember' and 'forget' by specifying the action and pairing.

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 (look up context stored earlier) and provides guidance on alternatives: pair with remember to save, forget to delete. Also mentions scoping context.

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

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

The description adds behavioral details beyond annotations: it discloses that setting mark_read:true modifies read state (contradicting readOnlyHint=true), explains the feed is persisted, and describes return structure. Despite the annotation contradiction, the description itself is transparent about the write capability.

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

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

The description is four sentences long, front-loads the core purpose, and adds details without extraneous fluff. It is efficient but could be slightly more structured (e.g., bullet points).

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

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

The description covers the main aspects: what the tool returns, filtering options, mark_read behavior, and alternative access. It does not mention pagination beyond a limit (1-200) or error states, but for a list retrieval tool with no output schema, it is fairly 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 parameter descriptions. The description adds value by giving an example for type ('sec_8k'), explaining the effect of mark_read, and clarifying the ISO timestamp format for since. This goes beyond what the schema provides, though baseline is 3.

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

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

The description clearly states the tool pulls fired events from the subscription feed, describes the returned data (source, citation_uri, raw payload), and uses specific verbs ('Pull', 'Returns'). It distinguishes from siblings like list_subscriptions by focusing on fired events rather than listing subscriptions.

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

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

The description mentions polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, giving some usage context. However, it does not explicitly guide when to use this tool over sibling tools (e.g., list_subscriptions) or when not to use it, so the guidance is implied rather than 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds significant context: fans out to multiple APIs (SEC, GDELT, GNews, USPTO), explains fallback logic, and describes return structure (changes, total_changes, citation URIs). No contradictions.

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

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

The description is a single detailed paragraph, front-loaded with examples. It is efficient but could benefit from slightly more structured formatting (e.g., bullet points for sources).

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 all aspects: purpose, input parameters with examples, behavior (multiple sources, fallback), return format, and alternative tool (entity_profile). No output schema needed as description explains 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?

Schema coverage is 100%, but description adds value by explaining relative time shorthands (e.g., '7d', '3m'), typical usage ('30d'), and acceptable formats for 'value' (ticker or CIK).

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

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

The description clearly defines the tool as a change feed for a company over a time window, with examples like 'What's new with X'. It distinguishes from sibling tool entity_profile by specifying that entity_profile is for static profiles.

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

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

Provides explicit context on when to use this tool (recent changes) and when to use entity_profile instead. Includes guidance on the 'since' parameter, e.g., 'Use "30d" or "1m" 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?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds critical context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and scoping by identifier. This goes beyond annotations, although it doesn't mention overwriting behavior or size limits.

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

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

The description is five sentences, front-loading the core purpose. Each sentence adds value, covering usage, persistence, and sibling tools. It could be slightly tighter, but overall concise 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 the tool's simplicity (2 params, no output schema), the description is fairly complete. It explains persistence, scoping, and how to use with recall/forget. Missing details like size limits or overwrite behavior are minor omissions for this 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?

With 100% schema description coverage, the schema already documents the parameters. The description reinforces that it's a key-value pair and provides examples for the key parameter, but adds no additional semantic depth 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: 'Save data the agent will need to reuse later.' It specifies the verb (save) and resource (data) and distinguishes itself from other tools by mentioning cross-session reuse and pairing with recall/forget.

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

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

The description provides clear usage context: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget, guiding when to use this tool versus alternatives. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that calls cascade through multiple endpoints and replaces manual lookups, 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 concise, starting with illustrative examples, then stating purpose, then listing supported types with details. Every sentence adds value; no redundancy.

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

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

Given no output schema, description fully covers return values for each entity type (ticker, CIK, citation for company; RxCUI, ingredient, citation for drug). It also mentions auto-disambiguation for company input, making it complete for its 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 has 100% coverage, but description enriches parameters with examples (e.g., 'AAPL', 'ozempic') and explains return values per type. Adds significant value beyond the minimal schema descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples and supported types (company, drug). It distinguishes itself from sibling tools like entity_profile by focusing on ID lookup.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides details on when to use for company or drug, but does not explicitly state when not to use or list alternatives, though the context of siblings implies clear use case.

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

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

Annotations already declare readOnlyHint, destructiveHint, etc. The description adds that it probes each entity with ai_visibility_check and returns a ranked list. It does not contradict annotations (annotation_contradiction=false). It could mention rate limits or auth details but is sufficient given the annotations.

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

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

The description is 4 sentences, front-loaded with the core purpose, followed by mechanism, example, and output. It is efficient and clear, though could be slightly more structured by separating the output format line.

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

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

Given 4 parameters and no output schema, the description explains the tool's behavior, what it returns (ranked list with score, confidence, signal density), and the role of the first entity. It also adds a constraint (2-8 entities) not in the schema. It doesn't cover error cases, but the tool is simple and well-described.

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% description coverage, baseline 3. The description adds value: it explains the first entity is treated as 'subject' for narrative and rest as competitors, and that context is shared across probes. This goes beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check for each. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by specifying its competitive audit use case and the internal call to ai_visibility_check.

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

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

The description gives a concrete use case: 'does Claude know about us as well as our competitors?' and implies it is for multiple entities. It does not explicitly state when not to use or list alternatives, but the sibling list includes ai_visibility_check for single entity checks, so the context is clear.

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

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

Disclosures beyond annotations: partial failures degrade gracefully with specific timing (5-30s) and reporting via sources_failed. Annotations already indicate read-only, idempotent, open-world, non-destructive. No contradiction.

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

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

Single dense paragraph with logical flow: purpose, sources, use case, return details, failure behavior. No wasted words; front-loaded with key 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?

Covers return format (summary block, advisories, links, alternatives), limitations (NPM v1), and graceful degradation. With no output schema, the description provides sufficient context for correct usage.

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

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

Schema coverage is 100%, but description adds that scoped packages are accepted for the package parameter. Most parameter details are already in the schema, so only minor additional value.

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

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

The description starts with a clear verb and resource: 'Composite ... check in ONE call' for npm packages. It distinguishes from siblings by specifying NPM ecosystem and contrasting with deps.dev for other ecosystems.

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

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

Explicitly states when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

The description adds context about language behavior (Dutch returns more matches) and result content 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?

Three focused sentences, no wasted words, front-loaded with 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?

For a search tool with full schema and annotations, the description sufficiently covers source, language, and result format. Pagination details are in schema.

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

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

Schema coverage is 100% and the description adds minimal new meaning (language tip is already in 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 searches a specific government open data catalogue and mentions the API, but does not explicitly differentiate from sibling tools like search_within or polymarket_arbitrage.

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

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

Usage is implied (search Dutch government data) but no explicit when-to-use or alternatives are provided.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. The description goes beyond by detailing the underlying model (BGE-base-en), windowing (500-char overlapping), and limitation (200K chars with truncation flag). No contradiction.

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

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

The description is a single efficient paragraph with essential information. Slightly dense but every sentence adds value. Could benefit from slight restructuring for readability.

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

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

For a tool with 3 parameters, no output schema, and moderate complexity, the description covers all key aspects: purpose, usage context, technical details (embeddings, windowing), and limitations (character cap). No gaps.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds value by explaining the max text length, natural-language query examples, and the default limit range, aiding interpretation.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and a distinct verb+resource combo. It also differentiates from sibling tools like ask_pipeworx_grounded by specifying its niche.

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

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

The description explicitly says to use when the record is too large for the prompt and pairs with ask_pipeworx_grounded. It implies when not to use (small records) but does not provide explicit exclusions.

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

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

Annotations are supplemented with valuable behavioral details: requires OAuth account, delivery channels with caps (SMS 10/day), webhook auto-disable after 10 failures, and signing secret returned once. No contradictions with annotations; in fact, the description enriches the agent's understanding.

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 a clear summary, then detailed explanations of types and delivery. It is somewhat lengthy but each sentence adds value, and the formatting aids readability.

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

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

Given the tool's complexity (multiple types, nested params, delivery options), the description covers most aspects. It mentions the always-on feed, required account, and behavioral details. It lacks explicit mention of idempotency behavior for repeated subscriptions, but overall it is quite 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%, so baseline is 3. The description adds substantial meaning by explaining each subscription type's params (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}') and delivery channels in detail beyond the schema (e.g., SMS verification, webhook signing).

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb and resource, distinguishing from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides context on when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). It mentions feed vs optional delivery channels but does not explicitly direct to sibling alternatives like list_subscriptions for viewing existing subscriptions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. No contradictions. It could mention any potential performance implications but is otherwise thorough.

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

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

The description is dense but well-structured, with a clear lead sentence, bullet-like listing of return categories, and usage instructions. A few words could be trimmed, but it earns its length by providing substantial guidance.

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 adequately explains what is returned (category-bucketed example questions with tool+argument shapes). It covers the single parameter, usage scenarios, and purpose. No gaps remain for this simple tool.

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

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

Schema coverage is 100% with a clear description for the topic parameter. The description adds context by listing example topic values and explaining the effect of omitting vs. passing topic. This goes beyond the schema's simple enum description.

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

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

The description explicitly states the tool is the onboarding entry point for a new agent to learn what Pipeworx can do, with examples like 'getting started' and 'what data do you have?'. It clearly distinguishes from siblings like ask_pipeworx and discover_tools, and uses a specific verb+resource: 'returns category-bucketed example questions'.

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

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

The description says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to omit or pass the topic argument, and provides explicit guidance on alternatives (meta-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 provide idempotentHint=true, destructiveHint=false. Description adds ownership enforcement, deactivation vs deletion, and historical event retention. No contradiction.

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

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

Two sentences, both essential and informative. No redundancy or irrelevant details.

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

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

For a single-parameter tool with no output schema, the description fully explains the action, ownership constraint, side effect, and impact on historical data.

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

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

Schema coverage is 100% with one parameter described as 'Subscription id (uuid) returned by subscribe.' Description adds no further meaning to the parameter beyond what schema provides.

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

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

Description clearly states 'Cancel a subscription by id' which is a specific verb+resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and mentions the effect (deactivation, not deletion). Lacks explicit mention of when not to use or alternatives, but sufficient for a simple 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the safety profile is clear. The description adds value by detailing that the tool returns a verdict, extracted structured form, actual value with citation, and percent delta, and that it replaces 4-6 sequential calls, providing extra behavioral context.

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

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

The description is informative but slightly lengthy. It is well-structured, starting with user intents, then usage guidance, scope, and output details. Each sentence serves a purpose, though minor condensation could improve conciseness.

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

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

Given the tool has one parameter and no output schema, the description provides essential context: when to use, what it does, scope limitations, and output format. It lacks explicit error handling or edge cases, but the overall completeness is sufficient for an AI agent to understand and invoke the tool correctly.

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

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

With 100% schema coverage for the single 'claim' parameter, the schema already documents it. The description adds value by providing example claim formats and clarifying the expected natural-language structure, which aids the agent in constructing valid inputs.

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

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

The description clearly defines the tool as a natural-language claim verifier against authoritative sources, specifically for company-financial claims. It distinguishes from siblings by its unique function of fact-checking, unlike other tools like ask_pipeworx or search tools.

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

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

Explicitly states usage: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies scope (company-financial claims for public US companies) and notes that v1 supports this domain, guiding appropriate use. While it doesn't explicitly state when not to use, the context implies alternatives for other claim types.

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