Datagov Uk

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

Annotations already declare readOnlyHint and idempotentHint; description adds that Anthropic calls require personal API key and incur direct costs. Discloses return format with per-model data and combined view.

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

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

Three sentences: first states purpose and output, second details model options and returns, third lists use cases. No fluff, information front-loaded.

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

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

Covers all 4 parameters and explains return structure. No output schema but description provides enough detail. Could mention error handling or rate limits for completeness, but sufficient for a read-only tool.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds context about default model and payment responsibility for Anthropic, but parameter info is already adequately covered in 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 the verb (probe), resource (LLMs), and outcome (score visibility 0-100). Distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by specifying AI-marketing audits and brand checks.

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 default model and how to include Anthropic with BYO key. Mentions use cases for audits and monitoring, but does not explicitly state when to avoid this tool or what alternatives exist.

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, and idempotentHint. The description adds value by explaining that the tool routes to many sources, fills arguments, and returns structured answers with citation URIs, which goes beyond the annotations.

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

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

The description is lengthy but every sentence adds value. It is front-loaded with the key recommendation and is structured logically. A slight reduction could improve conciseness, but it remains effective for its informative 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 the tool's complexity (many alias parameters, no output schema, and rich annotations), the description covers all necessary aspects: purpose, usage guidelines, behavioral traits, and parameter semantics. It is 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 clear descriptions for the 'question' parameter and its aliases. The description enriches this by providing examples of valid queries and emphasizing that natural language is accepted, which aids understanding.

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

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

The description clearly states that the tool routes questions to the appropriate tool among 4,482 tools across 1129 sources and returns structured answers with citations. It effectively differentiates from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

The description explicitly recommends preferring this tool over web search for factual questions and provides clear guidance on when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). Examples are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destruction. The description adds context about the refusal mechanism, cost of extra LLM call, and that it only answers from tool results, which goes beyond annotations. No contradiction.

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

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

The description is four sentences that are front-loaded with purpose, then mechanism, usage guidelines, and refusal reasons. No wasted words; every sentence provides 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 (high-stakes, refusal modes, extra cost), the description covers purpose, differentiation, usage context, return format, and failure modes. It is complete despite lacking an output schema.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description does not add parameter-specific details beyond the schema, but it does explain the overall input expectation (natural language question) which is adequate. Baseline 3 is appropriate.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, distinguishes from the sibling tool ask_pipeworx, and specifies the return structure including refusal reasons. The verb 'extracts' and resource 'answer' are specific.

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 answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives examples. Also advises preferring ask_pipeworx for casual lookups due to extra cost.

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

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

Despite readOnlyHint and idempotentHint already being true, the description provides extensive behavioral details: fan-out examples, resolver contract behaviors, parent event extraction, news fallback mechanisms, safety short-circuits for low confidence matches and closed markets, wide-spread handling, resolution-rule risk analysis. 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 very long (multiple paragraphs) and includes many detailed examples and edge cases. While comprehensive, it lacks conciseness and could benefit from structural organization (e.g., bullet points or sections). The first sentence is front-loaded, but the length may make it difficult for an agent to parse efficiently.

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 (classifiers, fan-outs, multiple response shapes, resolver contracts, parent events, news fallback, safety checks, spread warnings, resolution rules), the description covers almost all relevant aspects. Despite lacking an output schema, it thoroughly describes response shapes and edge cases, making it 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%, so baseline is 3. The description provides examples and clarifies the market input types, but this largely mirrors the schema. It adds context about when to use depth and include_raw, but overall parameter semantics are adequately covered by the schema.

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

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

The description starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the main function and distinguishes from sibling tools (e.g., polymarket_edges, polymarket_arbitrage) by focusing on comprehensive data gathering and analysis. The description also covers multiple input types and the overall workflow.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting result fields before trusting analysis. However, it does not explicitly list when to avoid using the tool or provide clear alternatives among siblings.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds rich behavioral context: it explains what data is fetched for each type (company financials from SEC EDGAR/XBRL with off-calendar handling, drug adverse events/trials), sorting by primary metric, and citation URIs. 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 well-structured: it starts with example queries, then explains the core functionality, and then breaks down details per entity type. Every sentence adds value without fluff, making it dense yet clear.

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

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

Given the tool's complexity (two entity types, multiple data points, sorting, citations) and lack of output schema, the description is remarkably complete. It covers what data is returned, how it is sorted, and the source of citations, leaving no critical 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 description adds significant meaning beyond the schema: for type='company' it details the specific financial metrics pulled, and for type='drug' it explains the data sources. It also clarifies that values for company are tickers/CIKs and for drug are names, and mentions off-calendar handling.

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 side-by-side comparison of 2–5 companies or drugs, with specific examples of user queries. It distinguishes itself from sibling tools like entity_profile by emphasizing it is a parallel call that replaces multiple sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. However, it does not explicitly state when NOT to use it (e.g., for more than 5 entities or single entity scenarios).

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

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

Adds that resources are files, not queryable datastore tables, beyond annotations' readOnlyHint, idempotentHint. Good 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?

Two efficient sentences. First sets purpose, second adds resource details. No 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?

For a simple tool with one parameter and no output schema, description fully explains what to expect and how resources are structured.

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

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

Single parameter with 100% schema coverage. Description adds that 'id' can be UUID or slug with example, enhancing 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 it returns full dataset record by id/slug including resources. Specific verb+resource, distinct from sibling 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?

Implies usage for getting dataset details but lacks explicit when-to-use vs alternatives like search_datasets. No exclusions or when-not-to-use.

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

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

Discloses key behaviors: returns findings packet with verbatim evidence, confidence, source, citation, gaps array (never invents), parallel decomposition, and 15-60s timeframe. Adds context beyond annotations (readOnlyHint, idempotentHint, openWorldHint) by explaining the 'never invent' policy and response structure.

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

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

Description is well-structured with clear sections (account info, purpose, usage guidelines, limitations, timing). Every sentence adds value, though slightly verbose. Could be trimmed slightly 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?

Fully covers input (question, depth), behavioral process (decomposition, parallel tools, response format), limitations (gaps for uncovered topics, not for breaking news), and timing. No output schema, but the description sufficiently explains return structure.

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 significant meaning: expands depth enum values (quick=3, standard=5 default, thorough=8 paid), clarifies question accepts broad/multi-part natural language, and explains the decomposition purpose.

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 1129 structured data sources, decomposes questions into facets, and routes to 4,482 tools in parallel. It distinguishes itself from ask_pipeworx by specifying it's best for broad/multi-part questions over structured data.

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

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

Explicitly states when to use (broad/multi-part structured data questions) and when not to (breaking news, current events - prefer ask_pipeworx). Also provides account requirements and alternative (ask_pipeworx) for unsigned users, with clear context on paid plans.

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 and idempotent behavior. The description adds useful behavioral details: returns top-N relevant tools with full input schemas and examples, ready to call directly. This goes beyond the annotations.

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

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

The description is concise: 5-6 sentences front-loaded with the core purpose, then usage guidance, and output explanation. Every sentence adds value, no 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 6 parameters, 100% schema coverage, and no output schema, the description appropriately explains the output (tools with schemas and examples). It covers the essential context for an AI agent to use the tool effectively.

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

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

Schema description coverage is 100%, with all 6 parameters documented. The description repeats some schema info (aliases) but adds no new semantic meaning. The baseline of 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool finds tools by describing the data or task, with specific examples like SEC filings, FDA drugs, etc. It distinguishes itself from sibling tools (e.g., ai_visibility_check, search_datasets) by being a discovery/search utility, not a specific data access 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 says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context for when to use, though it doesn't explicitly state when not to use (e.g., if already knowing the tool).

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details like multi-source fan-out, specific data returned, patents soft-fail, and GDELT→GNews fallback. No contradictions. Could mention potential latency or rate 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?

Description is a single paragraph but front-loads examples and usage guidance. Every sentence provides value, though it could be slightly more structured with bullet points. However, it remains concise and informative.

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

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

Given the tool's complexity (multiple data sources, diverse return fields), the description is very complete. It lists all returned items (CIK, filings, fundamentals, patents, news, LEI) and explains limitations. No output schema, so description covers return details fully.

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

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

Schema coverage is 100%. Description adds meaning: explains type is only 'company' supported, value is ticker or zero-padded CIK, and notes names not supported. This is helpful beyond the 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 starts with clear example queries and explicitly states it provides a 'full cross-source profile of a US public company.' It distinguishes from sibling tools by advising to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.'

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

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

It explicitly states when to use this tool (holistic view) and provides alternatives: 'names not supported (use resolve_entity first if you only have a name).' It also advises preference over chaining other lookups.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about 'previously stored memory' but does not contradict annotations. No additional behavioral details like effects of deleting non-existent key.

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 primary action, no wasted words. Highly efficient.

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

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

Given the tool's simplicity (1 param, no output schema, no nested objects), the description fully covers purpose and usage without 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% with one parameter 'key' described as 'Memory key to delete'. Description does not add extra meaning beyond the schema, meeting baseline for high coverage.

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

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

Description explicitly states 'Delete a previously stored memory by key', clearly indicating action and resource. Distinguishes from siblings by mentioning pairing with remember and recall.

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

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

Provides specific when-to-use scenarios: stale context, task completion, clearing sensitive data. Suggests pairing with remember and recall, offering guidance on alternatives.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which convey safety. The description adds valuable context: it fetches the page, extracts title/description/key links, and emits markdown. This goes beyond annotations by detailing the process and output usage.

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

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

The description is concise: two main sentences and a bullet list of use cases. It front-loads the core action and avoids unnecessary words, fitting all key information in a compact form.

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

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

The tool has no output schema, but the description explains the output is a single text blob ready to deploy. It covers the inputs (URL, max_links) and the extraction steps (title, description, key links). The description is complete for an AI agent to understand 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% with both parameters documented (url, max_links). The description restates the default and max for max_links but adds no new semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the target AI crawlers (ChatGPT, Claude, Perplexity) and the output format, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. While it doesn't mention when not to use or alternatives, the context from siblings implies this is the sole tool for generating llms.txt.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds context by specifying the data source (data.gov.uk) and the type of organizations listed, but does not reveal additional behavioral traits 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, no wasted words. The first sentence states purpose, the second provides actionable usage. Front-loaded and efficient.

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

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

While the description explains the output use (org names for filtering), it does not describe the full response format or pagination behavior. Given no output schema, more detail on returned fields would improve completeness.

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

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

The one parameter 'limit' is fully described in the input schema (coverage 100%), and the description adds no further meaning or constraints beyond what's in the schema.

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

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

Description clearly states it lists publishing organizations on data.gov.uk with specific examples, making the purpose unambiguous. The verb 'list' and resource 'organizations' are explicit, and the context of UK government bodies distinguishes it from general tools.

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

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

Description provides a concrete usage hint for chaining with search_datasets using the returned org name, but it does not explain when to use this tool vs. alternatives like organization_details. Lacks explicit when-not or exclusion criteria.

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

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

Annotations already indicate readOnly=true and non-destructive. The description adds value by specifying the returned fields (id, type, params, etc.) and the optional include_inactive parameter, enhancing transparency 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 clear, front-loaded sentences convey purpose, return details, and usage guidance. No 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?

For a simple tool with one optional parameter and robust annotations, the description covers purpose, return structure, and usage context completely. No output schema needed.

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 the parameter described well. The description mentions 'active' subscriptions which aligns with include_inactive, but adds minimal new meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates return fields. It distinguishes itself from siblings like subscribe/unsubscribe by focusing on listing rather than modification.

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 advises when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear context but lacks explicit alternative mentions or when-not-to-use scenarios.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by specifying the CKAN source and the exact fields returned (display name, description, dataset count, optional datasets), 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 sentences, front-loaded with key information, no unnecessary words.

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

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

Given the simple read operation, rich annotations, and full schema coverage, the description is fully adequate. No output schema needed; return values are implied.

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

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

Input schema has 100% description coverage with examples. Description adds minimal value: it mentions 'optionally a sample' aligning with include_datasets, but does not significantly enhance 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 retrieves full details for one organization, including display name, description, dataset count, and optionally a sample of datasets. It uses specific verb 'get' implied and distinguishes from sibling tools like 'list_organizations' and 'dataset_details'.

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

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

The description explains when to use the tool: 'Use to learn what a given UK publisher releases.' It implies context but does not explicitly state when not to use or name alternatives.

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

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

The description discloses rate limits (5 per identifier per day), that it doesn't count against quota, and that feedback is reviewed daily. These details go well beyond the annotations, which only indicate non-readonly, non-idempotent, etc.

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

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

The description is concise (5 sentences), front-loaded with purpose, and structured logically: purpose, usage guidance, constraints. No unnecessary words.

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

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

Given the tool's simplicity and no output schema, the description covers everything needed: what it does, when to use, how to format, and constraints. It is complete for an agent to invoke correctly.

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

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

The input schema already has 100% coverage with descriptions for each parameter. The description adds extra context, such as explaining the enum values and advising to describe issues in terms of tools/packs. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs and resources and distinguishes itself from sibling tools which are primarily query or action 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?

The description explicitly lists when to use the tool (for bugs, features, data gaps, praise) and provides a clear exclusion: 'don't paste the end-user's prompt'. This gives strong guidance on appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds that data is derived from 'CF analytics-engine, no PII, just (pack, tool, count)' and is cached for 5min-1h, providing valuable context beyond annotations. No contradiction.

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

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

Three well-structured sentences: first states return value, second lists use cases, third adds technical context. Front-loaded, no wasted words. Bullet-like numbering in use cases enhances 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 simple tool with one parameter and no output schema, the description covers input behavior, use cases, data source, privacy, and caching. It is sufficiently complete, though a note about the output format could be added.

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

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

Only one parameter (window) with 100% schema coverage. Description adds meaning that shorter windows surface what's hot now and longer show steady-state demand, complementing the enum values. This helps the agent choose appropriately.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume over a recent window', providing a specific verb ('returns') and resource. This purpose distinguishes it from sibling tools like 'discover_tools' or 'search_datasets' which serve different functions.

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

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

Three explicit use cases are given (discovering hot data, confirming canonical tool, checking alignment). Window guidance ('shorter for hot, longer for steady-state') helps decision-making. Could further improve by mentioning when not to use, but current guidance is strong.

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, and destructiveHint=false. The description adds significant behavioral context: it details the fill check, partition filter, semantic anchor, and when not to trade (realizable_edge_pp ≤ 0). No contradiction with annotations.

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

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

The description is front-loaded with the requirement and core purpose. It is somewhat verbose but every sentence provides useful information. It could be slightly more concise, but structure is logical.

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

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

Given the tool's complexity and lack of output schema, the description explains the response structure (opportunities, partition_check, fill check) and mentions related tool polymarket_fill_risk for custom sizing. It provides sufficient context 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?

Schema coverage is 100% and provides basic descriptions. The tool description adds extra meaning: examples of event slugs, accepted URL format, functionality of topic mode, and details about the response. This adds value beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples and explains the underlying mechanisms. This provides high clarity and differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states that one of `event` or `topic` is required and recommends event for specific markets and topic for cross-event scanning. It explains what cross-event mode catches that single-event misses. However, it does not mention when not to use this tool relative to sibling tools, though the internal guidance is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive; the description adds extensive behavioral context: model descriptions, edge calculations, slippage, caching (1h KV-level), diagnostic output, and warnings about market moves. It fully discloses traits beyond annotations without contradiction, offering high transparency for agent decision-making.

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

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

The description is comprehensive but verbose, spanning multiple technical paragraphs. It is well-structured with clear sections (segments, opportunity fields, knobs, response), but some details (e.g., specific model formulas) could be condensed without losing utility. It earns its sentences but could be tightened.

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 the response structure: top-level by_segment with three groups, fed_candidates, and _diagnostics including counters for why segments might be empty. It covers all return fields and edge case reasoning, making the tool's output predictable and actionable.

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, providing baseline of 3. The description adds significant value by explaining parameter nuances, such as why min_kelly does not filter partition arbs (basket trades) and how min_partition_leg_kelly applies per-leg, and clarifying default behaviors. This enhances understanding beyond 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It explicitly distinguishes from siblings like polymarket_arbitrage by detailing three segments (model-driven, structural arbitrage, concentrated longshot) that go beyond simple arbitrage, making the purpose highly specific and differentiated.

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

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

The description provides explicit guidance on when to use the tool (discovering opportunities without paging hundreds of markets) and describes adjustable knobs like min_liquidity, max_spread_pp, and category_filter to tailor usage. It notes Fed bets are excluded from ranking, offering context. However, it does not explicitly state when to use alternatives like polymarket_arbitrage, leaving a slight gap in exclusion 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail: the return structure (tracked, expired, snapshot_dates), computation of trend and decay_pp_per_day, and limits like 60-day TTL and start time. No contradiction with annotations.

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

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

The description is front-loaded with the key question and uses clear formatting (RESPONSE fields). However, it is somewhat verbose in explaining return details. Overall efficient but could be slightly more concise.

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

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

Despite lacking an output schema, the description thoroughly explains the return structure and key computed fields. It covers limits and edge cases (negative signs, median lifespan). This is complete enough for an agent to understand usage and behavior.

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

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

Schema coverage is 100% with both parameters described. The description adds minor context (days max 30, window snapshot family) but does not significantly enhance beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes between a fresh and old edge, contrasting with sibling tools like polymarket_edges which likely provide raw snapshots.

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 for analyzing edge persistence but does not explicitly state when to use this tool versus alternatives like polymarket_edges or other sibling tools. No when-not-to-use or exclusion conditions 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 declare readOnlyHint and idempotentHint, so the tool is safe and non-destructive. The description adds behavioral context beyond annotations by explaining the partial fill risk ('partial basket fills convert an arb into an unhedged directional position') and detailing return fields like 'thin_legs' and 'forced_directional_risk.'

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

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

The description is long but well-structured, with the key purpose front-loaded. Every sentence provides necessary information; however, some details (e.g., the list of return fields) could be slightly more concise. Still, it efficiently conveys complex information without waste.

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

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

Given there is no output schema, the description fully compensates by enumerating all return fields for both modes (top_of_book, vwap_fill_price, verdict, etc.) and explaining edge-case scenarios. For a 4-parameter tool with two modes and no enums, this is exceptionally 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 adds significant meaning: it explains the two operational modes, clarifies default values (e.g., side default 'auto' for basket), and describes how size_usd is interpreted differently in each mode (max spend vs target proceeds vs settlement notional). This adds value beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying two distinct modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage by giving explicit usage advice ('USE THIS before acting...').

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

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

The description explicitly states when to use the tool: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns of consequences if not used, but does not explicitly list situations where the tool should not be used, though the context implies it is for risk checking before trades.

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

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

Annotations already declare safe, idempotent, non-destructive behavior. The description adds significant behavioral context: compatibility warnings for non-equivalent bet shapes or mismatched events, temporal alignment checks, and counters for skipped comparisons. No contradictions with annotations.

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

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

The description is relatively long but every sentence adds necessary detail about safety fields, modes, and caveats. It is front-loaded with the main purpose and structured logically. Could be slightly trimmed without loss but remains efficient.

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

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

Given no output schema, the description explains response structure (leg-by-leg prices, top spreads, safety fields) and their meanings. It covers temporal alignment and compatibility warnings, but could briefly mention error handling for invalid tickers or network failures.

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 describes parameter values. The description adds practical semantics by explaining how 'topic' maps to pre-mapped shortcuts and that explicit parameters override the mapped side, plus provides examples for 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?

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on multi-venue comparison, and details two usage modes (topic shortcuts vs. explicit tickers).

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 outlines when to use each mode (topic vs. explicit), highlights that real spreads are rarer than the pre-mapped list suggests, and explains compatibility warnings that guide the agent on whether results are meaningful. It implicitly contrasts with single-venue tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail ('Scoped to your identifier...') and clarifies behavior when omitting key, adding value beyond annotations.

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

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

Front-loaded with core action, but the description is a bit lengthy at four sentences. Could be slightly tighter, but still efficient.

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

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

Given the simple input and annotations, the description covers scoping, usage examples, pairing with siblings, and parameter behavior, making it fully 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 one optional parameter. The description explains the effect of omitting the key (list all), adding practical semantics beyond the schema description.

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

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

The description clearly states the tool's purpose: retrieve a value saved via remember, or list all saved keys. It distinguishes from sibling tools (remember, forget) by name.

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: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also advises to pair with remember and forget, covering usage context and alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds value by explaining the returned fields (source, citation_uri, raw event) and the mark_read behavior that modifies read state without being destructive. It also clarifies polling suitability.

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, front-loaded with the key purpose, and each sentence adds necessary information without fluff. Well-structured and concise.

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

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

No output schema is present, but the description explains what is returned (source, citation_uri, raw event payload). With 5 parameters and good usage guidance, the description is complete enough for an agent to use this 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%, so baseline is 3. The description adds meaning by explaining what 'mark_read' does and that 'since' is an ISO timestamp, and mentions filtering by type. This provides additional context beyond the schema.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on reading 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 mentions 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards,' providing alternatives and context for when to use this tool. It does not explicitly state when not to use it, but the guidance is clear.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds significant context: fans out to multiple sources, handles rate-limiting with fallback, mentions PatentsView API sunset causing soft-fail until reactivated. No contradiction with annotations.

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

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

Description is comprehensive but slightly long. It front-loads typical use cases then explains behavior. Every sentence adds value, though some details (like specific API names) could be slightly more concise. Still well-structured and efficient.

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

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

Despite no output schema, the description explains return structure: changes grouped by source, total_changes count, citation URIs. Covers edge cases (fallback, API sunset). For a complex multi-source tool, the description is complete and leaves little ambiguity.

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 parameters are fully documented in schema. Description adds value by explaining the purpose of each parameter: `since` accepts ISO or relative shorthand with examples, `value` accepts ticker or CIK, `type` is only company. Gives guidance on default window ('30d' or '1m'). Minor deduction for not elaborating on `value` format beyond schema.

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

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

Description clearly states the tool provides a change feed for a company in a recent time window, covering SEC filings, news, and patents. It distinguishes from sibling entity_profile by specifying that this tool is for dynamic changes while entity_profile provides static profiles. Examples like 'What's new with X' reinforce purpose.

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

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

Description explicitly lists typical queries ('What's new with X', 'latest on Y') and provides a clear alternative: 'Use entity_profile instead when you want the static profile'. It also details fallback behavior (GDELT→GNews) and interprets parameter `since` with recommended values ('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 already declare write operation and non-destructive behavior. Description adds useful context: scoped by identifier, persistence for authenticated vs anonymous users. No contradictions with annotations.

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

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

Four sentences, all relevant. Front-loaded with purpose. Every sentence adds value: purpose, when to use, persistence details, sibling tool references.

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 simplicity of the tool (two simple string params, no output schema), the description covers all necessary aspects: purpose, usage context, behavior details. Complete without being verbose.

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

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

Schema coverage is 100%, so baseline is 3. Description adds examples for key values (e.g., 'subject_property', 'target_ticker') but no extra meaning beyond schema definitions.

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

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

Description clearly states the purpose: saving data to reuse later. Uses specific verbs (Save) and resources (key-value pair). Distinguishes from sibling tools like recall and forget, and gives concrete examples of what to store (ticker, address, preference).

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: 'discover something worth carrying forward'. Also says when not to use by mentioning alternatives (recall, forget). Provides context about scope (by identifier) and retention (24 hours for anonymous).

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by revealing internal cascading through multiple endpoints and specifying exact return fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug), which annotations do not cover.

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 query examples first, then core purpose, then type-specific details. Every sentence is functional and front-loaded. No extraneous text.

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

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

With no output schema, the description fully explains return values for both types and internal behavior. Combined with annotations, it provides complete context for the agent to 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?

Schema coverage is 100%, but description adds major value: explains what each type resolves to, gives input examples (ticker, CIK, name for company; brand/generic for drug), and mentions auto-disambiguation for company input. This goes well beyond the schema descriptions.

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

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

Description starts with concrete query examples and clearly states the purpose: resolving names to canonical IDs. It lists supported entity types and what each returns, distinguishing it from sibling tools like compare_entities or entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. Does not explicitly mention when not to use or alternatives, but the guidance is strong.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This goes beyond annotations by explaining the internal process and output structure.

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

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

The description is two sentences plus a parenthetical example, every sentence adds value. It is front-loaded with the core purpose and gives a concrete use case without 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 missing an output schema, the description fully specifies return fields (ranked list with score, confidence, signal density). Given the tool's moderate complexity and rich annotations, the description covers purpose, behavior, usage, and output adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates that context disambiguates common names and entities are brand/product names, but does not add significant new meaning beyond the schema descriptions. The internal use of ai_visibility_check is implied but not explicitly detailed 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 compares AI visibility across multiple entities side-by-side, explicitly distinguishing it from sibling ai_visibility_check (single entity) by mentioning probing with it. It uses specific verbs like 'Compare', 'Probes', 'ranks', and 'surfaces' to convey the operation.

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use this tool over siblings (multi-entity comparison) but does not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral traits beyond these: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 paragraph but packs substantial information with examples and edge cases. It is front-loaded with the main purpose and gradually adds details. Could be slightly more concise but remains efficient.

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

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

Given the tool's complexity (multi-source composite), no output schema, but the description enumerates return fields and explains partial failure behavior. Schema coverage is complete. The description satisfactorily covers all needed context for an agent to invoke correctly.

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

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

Schema coverage is 100% with both 'package' and 'version' described. The description adds value by noting that scoped packages are accepted and that version defaults to latest, which is not in the schema description. This extra context aids agent 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 defines the tool as a composite check for evaluating npm packages across deps.dev and bundlephobia, covering license, advisories, version history, and bundle size. It distinguishes itself by answering 'should I add this npm package' and is not overlapping with sibling tools like scan_competitor_ai_presence or entity_profile.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies ecosystem scope (NPM only in v1) and suggests alternatives for other ecosystems via 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds value by specifying the data source (data.gov.uk), language (English), return fields, and dataset count, which aids agent behavior beyond structured data.

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 purpose and source, then usage tip and language note. 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?

No output schema, but description mentions return fields. Input schema covers all parameters. Pagination (start/rows) is in schema, not description, but the description is sufficient for basic usage. Could mention sorting behavior more explicitly.

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 only the empty-query tip; other parameter details are already in the schema. Minimal additional 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?

The description clearly states it searches the data.gov.uk catalogue for UK government open datasets, naming the backend (CKAN package_search) and listing returned fields. However, it does not explicitly differentiate from sibling tools like 'search_within', though the scope is distinct.

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 to pass an empty query to browse everything, and implies usage for UK open data. No specific when-not-to-use or alternative tools 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?

Discloses embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and input cap (200K chars with truncation flag). This adds value beyond the safe-read 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 at 4-5 sentences, front-loaded with the main action, then key details (performance, pairing, technical specs). Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description clearly explains the return: 'top-N passages with character offsets and similarity scores'. It also covers edge cases (truncation) and typical use cases.

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 enriches parameters with usage context: text parameter exemplified as 'SEC 10-K body', query with natural-language examples, and limit with default. It explains the purpose of each parameter.

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

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

The description clearly states the verb 'semantic search' and the resource 'inside a fetched record', distinguishing it from sibling tools like search_datasets by emphasizing internal document search. It provides concrete examples like SEC 10-K body.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt' and pairs with an alternative tool (ask_pipeworx_grounded) for a grounding workflow.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context on account requirements, delivery channel behaviour, webhook signing secret returned once, and auto-disabling after failures. It does not contradict annotations and provides useful behavioral details.

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

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

The description is front-loaded with the core purpose and remains informative throughout. It is slightly long but every sentence adds necessary detail without redundancy.

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

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

Given the complexity (3 params, nested objects, enums) and no output schema, the description adequately covers prerequisites, type-specific options, delivery channels, caps, and return value. No critical gaps are present.

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

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

Schema coverage is 100%, yet the description adds significant value beyond schema descriptions by explaining type-specific parameters (e.g., items for sec_8k, topic for polymarket_edge) and delivery webhook HMAC signing details.

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 creates a proactive monitoring subscription and returns a subscription ID. It lists supported types and delivery channels, distinguishing it 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 explicitly mentions prerequisite (Pipeworx OAuth account) and caps (10/day for SMS). While it does not directly compare to alternatives, the context makes it evident when to use this tool versus siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: it is the onboarding entry point, returns example questions with exact tool and argument shapes, and can be called with no arguments or a topic. No contradiction with annotations.

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

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

The description is a single paragraph that front-loads with user questions. It packs substantial information without being overly verbose. Minor reducible redundancy could be trimmed, but overall it remains focused and valuable.

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

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

Given the tool has one optional parameter and no output schema, the description fully covers its behavior, return type, and use cases. It explains what the output contains (category-bucketed examples with tool+argument shapes), how to call it, and why to use it first. No gaps remain.

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

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

Schema coverage is 100% (one parameter, described). The description goes beyond by listing specific topic options (finance, pharma, etc.) and explaining that omitting the topic gives a broad spread. This adds meaning beyond the schema's generic 'Optional focus area' description.

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

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

The description clearly states the tool's purpose: it serves as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by being the first tool to use when unfamiliar with Pipeworx, and it includes multiple user phrasings ('What can I ask Pipeworx?', etc.).

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and also mentions learning how to call meta-tools. It does not explicitly state when not to use it or compare to alternatives, but the context of sibling tools like ask_pipeworx and discover_tools implies this is a discovery tool. Thus clear guidance with minor omission.

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

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

The description adds behavioral context beyond annotations: ownership enforcement and deactivation (not deletion). Annotations already indicate non-destructive and idempotent behavior, and the description aligns with these.

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

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

Two sentences, action-first, no unnecessary words. Every sentence provides essential information.

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

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

For a single-parameter tool with no output schema and good annotations, the description covers purpose, ownership, and side effects (deactivation with historical availability). It 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?

With 100% schema coverage, the schema already describes the 'id' parameter well. The description does not add new parameter-level meaning beyond stating 'by id.' 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 starts with 'Cancel a subscription by id,' clearly stating the action and 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?

The description explicitly enforces ownership ('you can only cancel your own subscriptions') and explains the deactivation behavior, but does not explicitly list when not to use it or compare with alternatives.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive. Description adds return type details (verdicts, structured form, citation, delta) and data source (SEC EDGAR + XBRL), providing 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?

Description is detailed but each sentence adds value: examples, usage scope, replacement benefit, output summary. It is front-loaded with examples and not overly long for the complexity.

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

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

Given one parameter with full schema coverage, comprehensive annotations, and no output schema, the description fully explains the tool's purpose, inputs, outputs, and limitations. It is complete for a verification tool.

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

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

Schema description coverage is 100% with a clear description. Tool description adds value by providing natural-language examples and clarifying the input as a factual claim, enhancing understanding beyond the schema.

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

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

Description clearly states it performs natural-language claim verification against authoritative sources, provides example phrasings, and distinguishes itself by replacing multiple sequential calls. The scope (company-financial claims) is explicitly defined.

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

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

Advises using whenever the agent needs to check factual correctness of a user's statement and gives example phrasings. While no explicit exclusions or sibling alternatives are named, the context implies it's for factual claims and mentions it replaces sequential calls.

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