Hdx

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

Annotations already indicate read-only and idempotent behavior. The description adds critical transparency: default model is free Workers AI, probing Anthropic requires a user-provided API key with direct payment, and the return structure includes per-model score, confidence, signals, raw_response, plus a combined view. No contradictions with annotations.

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

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

The description is three sentences long, front-loads the core action, and efficiently covers purpose, default behavior, cost, return format, and use cases. Every sentence adds essential 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?

Despite no output schema, the description outlines the return structure (per-model fields + combined view). It explains the default model and optional anthropic integration. All 4 parameters are implicitly addressed through the narrative. The tool's complexity is low, and the description fully covers what an agent needs to know to invoke it 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 value by clarifying that the default model is free and explaining when and why to use `_apiKey` (Anthropic, BYO key with direct cost). This goes beyond the schema's simple 'optional' 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 probes LLMs for visibility of a business/brand/product/topic and scores it 0-100. It lists specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and distinguishes from siblings like scan_competitor_ai_presence by focusing on LLM knowledge scoring.

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

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

The description provides clear use cases and explains when to use the tool ('Useful for AI-marketing audits...'). It does not explicitly state when not to use it or mention alternative tools, but the context is sufficient for most agents to understand 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, and destructiveHint. Description adds context about routing to 4,862 tools, returning structured answers with citation URIs, and being fast one-call.

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 key message first, then use cases, examples, and guidance. Slightly verbose but each sentence adds value; no redundancy.

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

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

Given the tool's complexity and lack of output schema, description thoroughly covers purpose, behavior, use cases, alternatives, and return format. Provides complete guidance for agent invocation.

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

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

Schema coverage is 100% and describes the 'question' parameter and aliases. Description does not add significant meaning beyond the schema, meeting baseline expectation.

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 tool answers factual questions using verified sources, with specific verbs like 'routes' and 'returns structured answer'. Distinguishes from siblings ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use and when-to-step-up guidance with examples and alternative tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: the one extra LLM call, the exact output format with refusal reasons, and the fact that it dynamically picks from many tools. 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 concise at five sentences, each serving a distinct purpose: purpose, mechanism, output, usage, and cost trade-off. It is front-loaded with the key function and contains no redundant information.

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

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

Given the tool's complexity (dynamic routing, multiple sources, specific output), the description fully covers purpose, behavior, input, output format, and usage context. No output schema is provided, but the description compensates completely.

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 having descriptions like 'Alias for question.' The description does not add meaningful semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads,' explaining it routes and extracts answers using only the tool result. It explicitly distinguishes from the sibling tool 'ask_pipeworx' by highlighting the extra extraction step.

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

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

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides concrete examples. It also notes to prefer 'ask_pipeworx' for casual lookups due to extra cost, offering clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral details: fan-out logic, response shapes (market, analysis, evidence), resolver contract with confidence levels, parent event extraction, news error handling, safety short-circuits, and resolution-rule risk. No contradictions.

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

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

The description is substantial but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the core purpose. Some paragraphs are verbose (e.g., resolution-risk), but overall efficient for the tool's complexity.

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

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

Given no output schema and 3 parameters, the description compensates thoroughly: input types, fan-out behavior, response fields, edge cases (low-confidence, closed markets, wide spreads, cancellation rules). All critical aspects for correct agent invocation are covered.

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

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

Schema coverage is 100% (all 3 parameters have descriptions). The description does not add per-parameter semantics beyond the schema. It provides operational context for depth and include_raw, but the schema already covers their meanings. 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 opens with a clear verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on comprehensive research with fan-out behavior.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and fan-out examples but does not explicitly contrast with sibling tools or mention when not to use it.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. Description adds significant context: pulls from SEC EDGAR/XBRL with off-calendar handling for companies, FAERS for drugs, sorts by primary metric, returns citation URIs. No contradictions.

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

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

Single paragraph with dense information. Could be slightly more structured (e.g., bullet points), but is efficient and front-loads purpose. Every sentence adds value.

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

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

No output schema, but description explains return (paired data + citation URIs) and sort order. Covers both entity types thoroughly with metrics and data sources. Complete for a comparison 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%, so baseline is 3. Description enriches by explaining what each type fetches (three financial metrics for company, three counts for drug) and examples for values. Adds value beyond schema.

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

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

Description lists multiple user query patterns (compare, vs, rank, head-to-head), states the verb (side-by-side comparison), and specifies the resource (2-5 companies or drugs). It clearly distinguishes from sequential lookups and provides data source details per type.

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 instructs ALWAYS PREFER over sequential single-pack lookups when comparing entities. Provides examples of when to use (comparing companies/drugs) and contrasts with the alternative (sequential 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 indicate read-only, idempotent, non-destructive behavior. The description adds important context about how to access actual data via resource URLs, which is 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?

Two sentences, no wasted words. The first defines purpose, the second provides crucial usage guidance. Front-loaded and efficient.

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

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

Given no output schema, the description explains the key return value (dataset record with resources and download URLs). It is complete enough for a simple retrieval tool, though it doesn't detail all fields.

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

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

The input schema has 100% coverage with a clear description for the 'id' parameter. The tool description does not add further semantic details for the parameter, so baseline 3 is appropriate.

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

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

The description clearly states it fetches a full dataset record by id or slug, including resources. It distinguishes from sibling tools like 'search_datasets' by specifying it's for a single record, not a search.

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

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

The description tells when to use this tool (to get dataset details and resource URLs) and implicitly when not (if you need direct row queries, you must use the resource URLs). It does not explicitly name alternatives, 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?

The description expands significantly on annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing account requirements, paid tiers, parallel routing to 4,862 tools, return format (findings packet with gaps[] and contradictions[]), time estimates, and the fact that it never invents data. 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 longer than typical but packed with useful information. It front-loads critical caveats (account requirement, alternatives) and organizes details about depth modes. Could be slightly more structured with bullet points, but the density is justified given tool 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?

The description is highly complete given no output schema: it explains the return format (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), time ranges, and behavior across depth modes. It covers all important aspects for agent invocation.

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

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

Despite 100% schema coverage, the description adds value by explaining that depth='quick' uses 3 facets, 'standard' uses 5 with gap recovery, and 'thorough' uses 8 with contradictions. For the question parameter, it clarifies that broad/multi-part questions are decomposed automatically.

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 performs 'grounded multi-source research across Pipeworx's 1272 STRUCTURED data sources'. It distinguishes it from siblings like ask_pipeworx by noting that deep_research is for broad/multi-part questions and not for single lookups or current news.

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

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

The description gives explicit usage guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains when to choose each depth option (quick, standard, thorough) with concrete behavior.

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

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

Annotations denote safe, non-destructive, idempotent behavior. The description adds that each result 'is ready to call directly, no second schema lookup needed,' detailing output format and immediacy. 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?

Two sentences: first defines purpose, second gives usage guidance and output description. Extremely concise, front-loaded, and every clause adds value.

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

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

For a simple discovery tool with no output schema, the description covers purpose, usage, parameter aliases, limit defaults, and output format. It is fully self-contained and sufficient 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 descriptions for all 6 parameters. The description adds that q, task, search, description are aliases for query, and specifies default/ max for limit (20/50), adding value beyond the schema.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies actions like browse, search, look up, or discover, and lists numerous domains (SEC filings, FDA, etc.), making the purpose distinct from sibling tools that focus on specific tasks.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also implies when not to use (when a single answer is needed) and provides alternative search terms, effectively guiding the agent.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it fans out across multiple sources, soft-fails on patents if the API is sunset, and details the exact fields returned. This goes beyond the annotations, providing a clear picture of what happens when the tool is invoked.

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 information-dense and well-structured, with query examples front-loaded. However, it is somewhat verbose due to listing all data sources and return fields. While every sentence adds value, it could be slightly more concise without losing clarity. A 4 is appropriate.

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

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

Given the complexity of the tool (multiple sources, no output schema), the description covers all necessary aspects: input requirements, output components, limitations (patents soft-fail, name not supported), and guidance on when to use. It is sufficiently complete for an agent to decide 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?

Both parameters are described in the schema with enum and format details. The description adds extra meaning: 'type' is limited to 'company', and 'value' can be a ticker or CIK but not a name. It also explains why names are not supported, which is helpful 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: generating a full cross-source profile of a US public company. It provides specific query examples and lists the data sources and output fields, making it easy to understand what the tool does. It also distinguishes itself from chaining multiple single-pack lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells when not to use it: names are not supported, and suggests using 'resolve_entity' first if the user only has a name. This provides clear usage guidance.

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

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

Annotations indicate destructive hint and no read-only; description adds context about clearing sensitive data. Idempotency hint is not elaborated but acceptable.

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 core action, 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?

For a simple tool with one parameter and no output schema, description covers main use cases and context. Minor gap on idempotency 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?

Single parameter 'key' has full schema coverage; description adds no additional meaning beyond the schema.

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

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

Clearly states it deletes a memory by key, distinguishing it from sibling tools 'remember' and 'recall'.

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

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

Explicitly provides when to use (stale context, task done, clear sensitive data) and references pairing with 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?

Describes fetching, extracting, and emitting markdown format, consistent with annotations (readOnlyHint, idempotentHint). Adds context about the output being a text blob.

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 plus a clear bullet list, front-loaded with purpose. 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?

Covers purpose, usage, output format, and use cases adequately for a simple tool with full annotations and schema coverage.

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 description adds no new param details beyond schema. Baseline 3.

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

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

States it generates an llms.txt file for any URL for AI crawlers, with specific use cases. Distinguishes from sibling tools by its unique function.

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

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

Provides explicit use cases (client's site, own project, competitor auditing), but does not mention when not to use or 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=true, openWorldHint=true, destructiveHint=false, covering safety and idempotency. The description adds output format details (e.g., keyed by lowercase ISO3, example object) but does not disclose additional behavioral traits like rate limits or caching behavior. With annotations handling the safety profile, a score of 3 is appropriate.

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

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

Two sentences: first explains the tool's action and output structure, second gives a practical usage hint (how to use output in search_datasets). No redundant words, front-loaded with 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 simple list tool with one parameter and no output schema, the description covers the output format, typical count, and integration usage. It does not specify whether the response is paginated beyond limit, but the limit parameter handles that. Slight gap in describing the return type (array vs object) but overall complete for the tool's complexity.

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

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

The single parameter 'limit' is fully described in the schema (max 1-1000, default 300). The description adds context: 'HDX has ~250', helping the agent choose an appropriate limit. This goes beyond the schema's description, justifying a score of 4.

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

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

The description clearly states: 'List the locations on HDX (CKAN group_list) — countries and crises', specifying the verb 'list' and the resource 'locations on HDX'. It uniquely identifies the output structure (lowercase ISO3 code with display_name), distinguishing it from sibling tools like list_organizations or 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?

The description explains how to use the output with search_datasets via fq='groups:<name>', listing typical count (~250) and limit range (1-1000). It does not explicitly state when not to use this tool or compare to alternatives, but the guidance is clear and actionable for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about the organizations but does not disclose 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: first defines purpose, second provides a usage hint. No fluff, every sentence adds value. 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?

For a simple list tool with one optional parameter and robust annotations, the description is complete. It could mention the return format, but the examples and usage hint suffice. Missing output schema is not critical here.

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 limit parameter well-described. The description does not add further parameter details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists publishing organizations on HDX with specific examples (OCHA, UNHCR, etc.). It distinguishes from siblings like list_locations by specifying the resource and context.

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

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

The description gives clear context (HDX, CKAN) and hints at how to use the results with search_datasets (fq parameter). However, it does not explicitly state when not to use this tool or compare with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds return fields and default behavior, enhancing transparency without contradiction.

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

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

Two sentences, no fluff. Purpose and usage are front-loaded.

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

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

No output schema exists, but description lists return fields. Complete for a list tool with good annotations.

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

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

Schema provides full description for the single parameter (include_inactive), so description adds no new parameter info. Baseline 3 per schema coverage >80%.

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 'List the caller's active subscriptions' – a specific verb-resource pair with caller scope. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says when to use: 'before adding more or to find an id to cancel'. Provides context and alternative actions.

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

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

All annotations are false, so description carries full burden. It reveals that the team reads digests daily, feedback affects roadmap, it's free and doesn't count against quota, and rate-limited. 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?

Six sentences, each serving a purpose: purpose, usage scenarios, anti-pattern, team action, rate limit, and cost. No redundancy or fluff. Key information is 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?

Given 3 parameters with full schema coverage, no output schema, the description covers purpose, usage, constraints (rate limit, quota), and content guidance. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining each enum value for 'type' (bug, feature, etc.) in detail, and guides message format ('Be specific... 1-2 sentences typical, 2000 chars max'). Nested object 'context' is also described though schema already covers fields.

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

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

The description explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the specific resource (Pipeworx team) and action (tell/feedback), and is clearly distinct from all sibling tools which are data retrieval or analysis 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?

Provides explicit guidance on when to use: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also specifies what not to do: 'don't paste the end-user's prompt.' Includes rate-limit warning: 'Rate-limited to 5 per identifier per day.'

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

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

Annotations already declare readOnly, idempotent, non-destructive nature. The description adds important behavioral context: aggregated from CF analytics, no PII, caching varying by window. 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?

Three sentences plus a terse list of use cases. Every sentence adds value; no fluff. The main action is 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?

For a simple one-parameter tool with no output schema, the description covers purpose, use cases, data source, privacy, and caching. It is fully adequate for the complexity level.

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 enum values described. The description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which goes beyond the enum labels.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over specified windows, using specific verbs and resource. It distinguishes itself from siblings like 'discover_tools' by focusing on what other agents are calling, not general discovery.

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

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

The description explicitly lists three distinct use cases and explains the semantics of different window choices. It provides context for when to use shorter vs longer windows, though it could be more explicit about alternatives when this tool is not appropriate.

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 show readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds extensive behavioral context: scanning modes, Jaccard similarity filter, partition filter with placeholder logic, fill check with theoretical vs realizable edge. 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?

Long but well-structured with clear sections (semantic anchor, partition filter, response, fill check). Could be slightly tighter but every sentence adds value.

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

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

No output schema, but description fully explains response structure (opportunities[], partition_check, fill_check) and covers edge cases like skipped_low_similarity and placeholder filtering. Suitable for a tool with 2 optional parameters.

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

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

Both parameters are documented in schema (100% coverage). Description adds examples of event slugs, full URL acceptance, and topic seed questions, plus default behavior with no args.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between trending_scan, event mode, and topic mode, differentiating from sibling tools like polymarket_edges or 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?

Explicitly says call with no args for trending_scan, recommends event for specific markets, topic for cross-event scanning, and explains when cross-event is beneficial. Also warns about fill checks and when not to trade.

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 extensively details behavioral traits: three model families with formulas, filtering logic, output structure, caching, and exclusion of unreliable Fed bets. All annotations (readOnlyHint, etc.) are consistent and complemented with additional context.

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

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

The description is very verbose with extensive technical details (e.g., specific formulas). While well-structured and front-loaded with purpose, it could be more concise. Some details exceed necessary length for agent comprehension.

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

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

Given the complexity (9 parameters, three segments, nested output), the description covers all aspects comprehensively: output structure, explanations for empty segments, edge metrics, and caching. No output schema exists, so description fully compensates.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds minor extra context like slippage notes and examples, but does not significantly enhance meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly targeting 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on multiple edge types.

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

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

The description provides clear when-to-use context for opportunity discovery and includes tradeable-edge knobs for filtering. However, it does not explicitly state when not to use it or provide direct alternatives beyond mentioning Fed bet limitations.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral details: it reads snapshots, computes trends and decay, relies on snapshot availability (cache-miss gaps), and has a 60-day TTL. This provides comprehensive 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?

The description is dense and verbose, containing all necessary information but lacking structural separation (e.g., sections for response format, limits). It is front-loaded with the main purpose but could be more concise while preserving detail.

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 response structure (tracked[], expired[], snapshot_dates[]) with field details. It also covers limitations (TTL, snapshot gaps, no intraday). This makes the tool fully understandable without additional schemas.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces defaults and clamping behavior (days clamped 2-30, default 14) and lists window options. It adds slight extra context beyond schema, such as the implication of window families.

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's purpose: tracking edge persistence and decay using daily snapshots. It uses specific verbs like 'answers' and provides a concrete example contrasting fresh vs. old edges, distinguishing it from sibling tools like polymarket_edges.

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

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

The description gives clear context on when to use the tool (to understand edge age and trend) and implies when not (old wide edge is suspicious). It does not explicitly name alternative tools but provides enough guidance for an AI agent to infer 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 indicate readOnly and idempotent, consistent with the description's 'check' nature. The description adds behavioral detail: walks the order book ladder, returns verdict (clean/degraded/cannot_fill), and warns about forced directional risk. No contradiction with annotations.

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

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

The description is well-structured with clear uppercase section headers. While fairly long, every sentence adds value. Could be slightly more streamlined, but the organization aids readability for a complex tool.

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 documents return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), covers both modes, edge cases (thin legs, partial fills), and practical risks (unhedged directional position). Complete for an AI agent to assess risk.

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, but the tool description adds significant meaning: explains size_usd as 'max spend on buys, target proceeds on sells' and 'settlement notional' for baskets, side defaults ('auto from partition sum'), and clarifies single-market vs basket parameter roles.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explains both single-market and basket modes, and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by noting it should be used before acting on their signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create directional risk), providing clear context for when not to use.

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

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

The description discloses behavioral traits well beyond the annotations: it describes the two modes, what causes compatibility warnings (shape mismatch, semantic mismatch), the significance of temporal alignment, and the counters for dropped comparisons. It also notes that real spreads are rarer than the shortcut list suggests. There is no contradiction with annotations (readOnly, openWorld, idempotent).

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

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

The description is thorough but somewhat lengthy. Every sentence adds value, but some information (e.g., the detailed explanation of compatibility_warning cases) could be slightly more condensed without losing clarity. The structure is logical: modes, response, safety fields. It is not excessively verbose, but there is room for minor tightening.

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 does an excellent job of explaining the response structure: leg-by-leg prices, top_spreads_pp, and safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It covers edge cases, warns about limitations, and provides enough context for an 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 coverage is 100% with descriptions, but the description adds significant value: it lists the exact topic shortcuts, explains that they auto-fetch matching events, and clarifies the override behavior. The description also provides context (e.g., 'pre-mapped ≠ tradeable') that the schema alone does not convey, fully compensating for any lack of enum or format hints.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by focusing on a specific niche not covered by any other tool in the sibling list. The description precisely identifies the resource (spreads) and the action (computing and reporting), with specific modes and response fields.

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

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

The description provides explicit guidance on when to use each mode (topic shortcuts vs explicit tickers), explains the safety fields (compatibility_warning, temporal_alignment) and their implications for tradeability, and explicitly warns that most pre-mapped topics are not tradeable. This gives the agent clear criteria for tool selection and interpretation of results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining scoping to identifiers (anonymous IP, BYO key hash, account ID) and pairing with remember/forget. No contradictions.

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

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

Three sentences, each earning its place: action, usage context with examples, scoping and pairing. No fluff, front-loaded with purpose.

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

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

The description covers purpose and usage well, but since there is no output schema, it should ideally describe the return format (e.g., value or list of keys). The examples are helpful but the return structure is implied rather than explicit.

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

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

Schema coverage is 100% and description of parameter 'key' includes 'omit to list all keys'. The tool description adds broader context about what the saved values represent (e.g., user's target ticker, address, research notes), going beyond the schema.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys, with specific verb+resource. It distinguishes from sibling tools 'remember' and 'forget' by naming them explicitly.

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 (look up context stored earlier) and provides examples like user's target ticker. It mentions omitting key to list all, but lacks explicit when-not guidance or alternative tools beyond the sibling mention.

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 idempotent, read-only, and non-destructive behavior. The description adds valuable context: it returns specific fields (source, citation_uri, raw payload), explains filtering and mark_read side effects, and mentions polling adequacy. 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 five sentences, front-loaded with the main purpose. Each sentence adds distinct value (purpose, output fields, filters, mark_read behavior, polling/alternative). No filler or redundancy.

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

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

Given the tool has 5 optional parameters and no output schema, the description explains what the response contains, filter capabilities, mark_read effect, and polling suitability. It also notes an alternative REST endpoint. This provides sufficient information for correct invocation without 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% with descriptions for all parameters. The description adds extra context for 'type' (example 'sec_8k'), 'since' (ISO timestamp), and 'mark_read' (marks events read for next call). This goes beyond the schema for those key parameters, enhancing 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 'Pull fired events from your subscription feed', specifying the verb and resource. It details what each alert carries (source, citation_uri, raw payload). However, it does not explicitly differentiate from sibling tools like recent_changes or list_subscriptions, which could cause confusion when selecting the right 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 implies usage for polling recent alerts and mentions an alternative access method (GET endpoint). It also hints at mark_read behavior for subsequent calls. However, it does not explicitly specify when to use this tool versus alternatives like recent_changes or search within subscriptions, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds transparency beyond that: fan-out behavior to multiple sources, fallback logic, soft-fail for USPTO, and return structure (changes grouped by source, total count, citation URIs). No contradiction. Score 5.

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

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

Description is dense but well-organized. It starts with example queries to quickly convey purpose, then details sources, parameter usage, and ends with a sibling disambiguation. No fluff; every sentence serves a purpose. Score 5.

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

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

For a complex tool with multiple sources and fallback, the description covers all essential aspects: sources, parameter behavior, return format, and limitations. It lacks explicit error handling or pagination details, but given the output structure is adequately described (changes[], total_changes, citations), it is mostly complete. Score 4.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining the `since` parameter with examples ('7d', '30d', '3m', '1y') and clarifying that `value` accepts ticker or CIK. It also provides context on how the window affects data. While the schema is sufficient, the description enriches understanding. Score 4.

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

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

Description clearly states tool provides a change feed for a company over a window, fanning out to multiple sources. It gives concrete example queries ('what's new with X', 'latest on Y') and explicitly distinguishes from sibling entity_profile. This meets a 5: specific verb+resource+scope with sibling differentiation.

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 explicit when-to-use scenarios (example queries) and when-not-to ('use entity_profile instead for static profile'). It also details fallback behavior (GDELT -> GNews) and source limitations (USPTO soft-fail). This is a 5: explicit with exclusions 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 provide idempotentHint=true (safe to retry), destructiveHint=false, and readOnlyHint=false (writes). The description adds behavioral context: key-value pairs scoped by identifier, persistence differences (authenticated vs anonymous, 24-hour retention). 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?

Four sentences, front-loaded with purpose and usage, then details on behavior. Every sentence adds value; no redundancy.

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

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

For a simple key-value store tool with 2 required params and no output schema, the description covers purpose, usage, behavioral traits, and parameter hints. It is fully adequate for correct invocation.

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

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

Schema coverage is 100%, so parameters are documented. The description adds examples for key ('subject_property', 'target_ticker') and for value ('findings, addresses, preferences'), 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?

The description states a specific verb ('Save data') and resource ('data the agent will need to reuse later'), with clear examples (resolved ticker, target address). It distinguishes from sibling tools 'recall' and 'forget', which are explicitly mentioned.

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

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

The description explains when to use ('when you discover something worth carrying forward') and explicitly mentions alternatives ('Pair with recall to retrieve later, forget to delete'). No ambiguity.

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

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

Annotations already declare the tool as readonly, idempotent, and non-destructive. The description adds value by disclosing that each call cascades through several internal endpoints, replacing multiple manual lookups. This provides insight into internal behavior beyond what annotations convey.

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 concise given the amount of useful information packed in. It front-loads with example queries, then explains types and internal behavior. Every sentence adds value, though it could be slightly trimmed without losing clarity.

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

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

Despite no output schema, the description fully explains return values for each entity type (including citation URIs). It covers both parameters, usage guidance, internal behavior, and tool purpose. For a two-parameter tool, this is exceptionally complete and actionable for an agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description enhances this by giving concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and noting auto-disambiguation for company names. It also explains the return format per type, adding semantic meaning.

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

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

The description clearly defines the tool's purpose: resolving a name to a canonical identifier. It provides specific example queries and details what each entity type returns (ticker/CIK for companies, RxCUI for drugs). This distinguishes it from sibling tools that require IDs as input.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also notes that using resolve_entity replaces 2-3 manual lookups, implying efficiency and suggesting it should be prioritized over chaining multiple 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?

Describes internal probes via ai_visibility_check, ranking, and output fields (score, confidence, signal density). Adds value beyond annotations, which already indicate safety and idempotency.

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

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

Two concise sentences with front-loaded purpose. Slightly wordy but clear and efficient.

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

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

No output schema, but description covers return structure (ranked list, score, confidence, signal density). Combined with annotations, the agent has enough context 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%, so the description adds no new parameter information; it merely restates schema hints (e.g., 'Omit for just workers-ai'). Baseline 3 is appropriate.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly says useful for competitive AI-marketing audits and gives an example question. Does not mention when not to use or alternatives, but context is clear.

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

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

Annotations already cover safety profile. Description adds that it's a composite call with potential partial failures and that bundlephobia measurements can be slow. Provides good context beyond structured fields.

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?

Fairly long but every sentence adds value. Well-structured with clear sections. Could be slightly more concise, but no wasted words.

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

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

Given no output schema, the description thoroughly explains the return structure (summary block, per-advisory, links, alternatives). Also covers partial failures, ecosystem limitation, and behavior on timeout. Very complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds a note about version defaulting to latest, which is already implied by the schema. Does not add significant new meaning.

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

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

Clearly states it's a composite check for npm packages, specifying the sources (deps.dev and bundlephobia) and the types of information returned. Distinguishes itself from siblings by its specific domain.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost of an npm package. Also notes ecosystem limitation (NPM only) and provides alternative for other ecosystems.

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

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

Annotations already declare the tool as read-only, idempotent, and open-world. The description adds useful behavioral details: it returns titles, descriptions, publishing organization, locations, and resources, and explains the filter syntax for country/crisis. No contradiction with annotations.

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

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

The description is concise: two sentences that cover purpose, return fields, and filter guidance. No extraneous information, every sentence earns its place.

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

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

Given the tool has 5 parameters and no output schema, the description adequately covers what the tool returns and how to filter. Pagination and sort are handled by the schema. The reference to list_locations completes the context for effective filtering.

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

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

Schema coverage is 100%, but the description adds value by providing a concrete example for the fq parameter (e.g., 'groups:syr') and directing users to list_locations for codes. This enhances understanding beyond the schema's generic 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 specifies it searches the HDX catalogue for specific topics like displacement, refugees, etc., and returns matching datasets with details. It references sibling tool list_locations, distinguishing itself from other 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 provides clear context on when to use (searching for specific topics) and gives concrete filter examples. It references list_locations for obtaining ISO3 codes, guiding the user but not explicitly stating when not to use this tool versus 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 detailed behaviors beyond the annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and truncates inputs over 200K chars with a flag. All annotations are consistent (readOnlyHint, idempotentHint, etc.).

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

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

The description is a single, well-organized paragraph that front-loads the core purpose and immediately explains why it is useful (saves context). Every sentence conveys necessary information—from parameters to technical details—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?

Given the tool's complexity (semantic search with offsets, truncation) and lack of output schema, the description covers all essential aspects: purpose, use case, parameters, behavior, technical details, and integration with a sibling tool. It is fully self-contained.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds context beyond the schema: explains that 'text' is the fetched document, 'query' is a natural-language question with examples, and 'limit' controls max passages. This enriches understanding without duplication.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It uses a specific verb (search), identifies the resource (inside a fetched record), and distinguishes it from sibling tools like ask_pipeworx_grounded by emphasizing internal search over whole-document processing.

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

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

The description explicitly advises when to use: 'Use when the record is too big to cram into the prompt.' It also mentions pairing with ask_pipeworx_grounded, providing a usage workflow. However, it does not explicitly list when not to use or name alternatives to exclude.

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

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

Annotations indicate idempotent and non-destructive behavior. The description adds operational details: webhook secret returned once, auto-disable after 10 failures, SMS 10/day cap, and phone verification requirement. These go beyond what annotations provide.

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

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

The description is a single paragraph that flows logically: purpose, requirements, types, delivery. It is front-loaded with the core action. While it could be split for readability, it contains no wasted sentences.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers creation, return value, prerequisites, type-specific filters, and delivery details. It is sufficiently complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances understanding by providing concrete examples for each subscription type and explaining parameters like 'items', 'topic', etc., which the schema describes only briefly.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and mentions the return of a subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains the requirement for a Pipeworx OAuth account and lists supported alert types with examples. While it does not explicitly say 'use this when you want to create an alert', the context makes it clear, and alternatives (list, delete) are implied by sibling names.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds transparency by explaining the output format (category-bucketed questions with exact tool and argument shape, drawn from live catalog). This goes beyond annotations to clarify behavior.

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 trigger phrases and then concisely explains what the tool does, what it returns, and usage patterns. 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?

For an onboarding tool with no output schema, the description is complete: it explains return format (category-bucketed questions with tool+argument shape), usage scenarios (first tool to ask, or to learn meta-tools), and parameter options. 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% with one optional parameter. The description explains the topic parameter by listing valid focus areas and explicitly states that omitting it returns a full cross-category spread. This adds semantic value beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for agents wanting to know what Pipeworx can do. It uses specific verbs like "returns category-bucketed example questions" and distinguishes itself from siblings like ask_pipeworx, entity_profile, etc., by stating it provides tool+argument examples for the live catalog.

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

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

Explicit usage guidance: "Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)." This clearly tells the agent when to use this tool and provides 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?

Discloses that rows are deactivated (not deleted), adding context beyond annotations which already indicate non-destructive behavior. Could mention side effects like reversibility.

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 with front-loaded action. No extraneous 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?

Adequately covers purpose, constraints, and effect for a simple tool. Lacks return value description but not critical for cancellation.

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

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

Schema covers the single parameter with full description (uuid returned by subscribe). The tool description adds no additional parameter semantics beyond what the schema provides.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. 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?

Specifies ownership enforcement as a usage constraint. Implicitly guides when to use (own subscriptions) and mentions the effect on historical data. Lacks explicit comparison to alternatives like 'forget'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: returns a verdict (with 5 types), extracted structured form, actual value with pipeworx:// citation, and percent delta. It also discloses domain limitations (company-financial claims, US public companies). This goes beyond what annotations provide.

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

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

The description is front-loaded with typical user queries, making it immediately scannable. At 4 sentences, it is efficient but packs substantial detail (verdict types, citation, delta, domain, replacement of multiple calls). Every sentence earns its place; no filler. Slightly longer than ideal but justifiable 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 a single parameter, no output schema, and comprehensive annotations, the description fully covers what the tool does, its input (natural-language claim), its output (verdict with structured details), and its scope (US public company financials via SEC EDGAR+XBRL). No missing information for an agent to use it 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 description coverage is 100% for the single required parameter 'claim'. The description adds significant value by clarifying it expects natural-language factual claim, providing examples ('Apple's FY2024 revenue was $400 billion'), and implying the parameter accepts free-form text. This enriches the schema's minimal 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 verifies factual claims, using specific verbs like 'validate', 'verify', 'confirm or refute'. It explicitly mentions the domain (company-financial claims via SEC EDGAR + XBRL) and distinguishes from siblings by replacing 4-6 sequential calls, showing strong purpose clarity.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also limits scope to company-financial claims for US public companies. However, it does not explicitly mention when not to use or provide alternatives, though the sibling list shows no direct competitor. Minor gap in exclusionary guidance.

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