Unicef

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable context about cost implications (BYO key for Anthropic, you pay directly) and the return structure. It does not discuss rate limits or failure modes, but annotations cover the safety profile.

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

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

The description is four sentences, front-loaded with the core purpose. Every sentence adds information: what it does, default model, optional API key, return structure, and use cases. No fluff or repetition.

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

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

Given the tool's complexity (multiple models, return structure) and absence of output schema, the description explains the per-model return format (score, confidence, signals, raw_response) and combined view. It lacks details on 'signals' and error handling, but is sufficient for understanding.

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

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

Schema coverage is 100% and parameter descriptions are already detailed in the schema. The description adds examples (e.g., entity examples) but does not significantly enhance understanding beyond what the schema provides. 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 it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic probing. This distinguishes it from sibling tools like ask_pipeworx or bet_research, as it focuses on visibility scoring for AI-marketing audits.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not mention when not to use it or contrast with alternatives. The context is clear, but explicit exclusions are missing.

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 (readOnly, openWorld, idempotent) are consistent; description adds context about routing, citation URIs, multi-step argument filling, and coverage of many domains, adding value beyond annotations.

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

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

Well-structured with clear sections, bullet-point examples, and front-loaded key info; slightly lengthy but justified by richness of guidance.

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

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

Given many siblings, full schema, annotations, and detailed usage guidance with examples, the description is comprehensive and leaves no major gaps.

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

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

Schema coverage is 100% with descriptions for each alias. Description adds no new parameter meaning but confirms the tool auto-fills arguments; baseline score 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 routes questions to a vast set of tools and returns structured answers with citations, distinguishing it from siblings like web search and ask_pipeworx_grounded.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', lists query types, gives examples, and provides step-up alternatives (ask_pipeworx_grounded, deep_research) for different needs.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the extraction mechanism (uses only tool result), the refusal handling (specific refusal reasons), and the additional LLM call cost. 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 reasonably concise but somewhat lengthy. It is well-structured, front-loading the core purpose, then explaining mechanism, and finally usage guidance. Every sentence adds value, though a slight reduction in redundancy could improve conciseness.

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

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

Given no output schema, the description fully explains the return format including answer, evidence, confidence, source, and refusal reasons. The parameter schema is fully covered by descriptions. Annotations are present. The sibling list is large, but the description adequately differentiates from the key sibling. The tool is complex and the description is complete enough for an agent to use correctly.

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

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

The input schema has 100% description coverage, with each parameter alias clearly documented. The description mentions 'fills arguments' but does not add significant additional meaning beyond what the schema provides. Baseline of 3 is appropriate given the high coverage.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers only from tool results, returning evidence. It effectively distinguishes itself from the sibling 'ask_pipeworx' by emphasizing its grounded nature and specific use case.

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

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

The description explicitly states when to use this tool (high-stakes reads, when answers will be quoted/cited/acted on, and when the agent must not invent facts) and when to prefer the alternative 'ask_pipeworx' (casual lookups). It also mentions the cost trade-off of an extra LLM call, providing clear 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?

Exceeds annotations by detailing fan-out behavior, resolver contract, parent_event extraction, news fields with fallback handling, safety mechanisms like low-confidence short-circuit, and resolution-rule 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?

Very detailed but presented as a dense paragraph without clear structure. Could benefit from bullet points or sections for easier scanning.

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

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

Covers all critical aspects: resolution matching, evidence sources, edge cases (closed markets, wide spreads, cancellation rules), and response shape. No output schema but description compensates thoroughly.

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. Tool description adds value by explaining input types for market, depth options with defaults, and include_raw with performance implications.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, with specific verbs and resources. It distinguishes from siblings like polymarket_edges by focusing on a single bet research rather than edge tracking or arbitrage.

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

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

Explicitly advises use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Does not explicitly exclude alternatives but provides clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it uses SEC EDGAR for companies, FAERS for drugs, handles fiscal years correctly, and returns paired data with citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and is dense but not overly long. It could be slightly more structured, but it efficiently conveys key 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 no output schema, the description explains return format (paired data + citation URIs). It covers both entity types completely, making the tool fully understandable.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond schema by specifying exact financials for companies and counts for drugs, and clarifies that type and values are required.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, distinguishing it from sequential lookups. The verb 'compare' and resource 'entities' are specific, and it distinguishes from sibling tools like entity_profile.

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

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

The description explicitly prefers this tool over sequential single-pack lookups and provides example queries. It explains what data each type pulls but does not explicitly state when not to use it.

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

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

Discloses behavior beyond annotations: the output structure (ordered dimensions, valid codes), how to construct the dot-separated key, wildcard semantics, and an example call. Annotations already indicate read-only and idempotent, but the description adds critical operational context.

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

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

Two sentences and an example, no wasted words. Purpose is front-loaded, followed by usage guidance and an illustrative example. Efficient and well-organized.

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

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

Despite no output schema, the description fully explains what the tool returns and how to use it, making it self-sufficient for an agent to call effectively. All relevant context is provided.

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% with a description for `dataflow_id`. The description adds value by providing example values ('CME', 'NUTRITION', 'EDUCATION') and a concrete example call, 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 clearly states 'Get the structure (Data Structure Definition) of one UNICEF dataset' with specific verb and resource, and distinguishes itself from sibling tools like `get_data` and `list_dataflows` by detailing what it returns (dimensions and codes).

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 'Always call this before get_data' and explains how the output (dimension_order, codes) is used to build SDMX keys for `get_data`, providing strong contextual guidance on when and why to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: parallel tool routing, 15-60s response time, returns findings with gaps[], and never invents. No contradictions with annotations.

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

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

The description is detailed but well-structured: starts with account requirement, then tool purpose, use cases, examples, and caveats. Every sentence adds value, though slightly lengthy due to necessary specifics.

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 2 parameters, 100% schema coverage, and no output schema, the description thoroughly explains what the tool returns (findings packet with verbatim evidence, confidence, source, citation, gaps[]), timing expectations, and limitations. Highly complete.

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

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

Schema coverage is 100%, but the description adds value: for 'question' it clarifies broad/multi-part is fine, for 'depth' it explains numeric equivalents (quick=3, standard=5, thorough=8) and the paid plan requirement for 'thorough'.

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

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

The description uses a specific verb (research) and resource (Pipeworx's structured data sources), clearly distinguishing it from siblings like ask_pipeworx. It states it's for broad/multi-part questions over structured data, not open-web 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?

Explicitly tells when to use (broad/multi-part structured-data questions) and when not (breaking news, single lookups), and names alternatives (ask_pipeworx for single lookups and breaking news). Also notes account requirements and paid plan for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 two sentences plus a list of examples – very concise. The first sentence front-loads the core purpose. Every sentence adds value without redundancy.

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

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

Given the tool's nature (discovery), the description covers purpose, usage, and return format. It doesn't mention error handling, but that's acceptable. No output schema, but return format is described indirectly.

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 well-documented. Description adds marginal value by mentioning limit default and max, and that aliases are accepted. With high schema coverage, 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 'Find tools by describing the data or task' – a specific verb and resource. It distinguishes from sibling tools (which are specific data tools) by being a meta-discovery tool. The list of example domains further clarifies the scope.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for when to use, though it does not explicitly state when not to use or name alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. Description adds further context: fans out across multiple sources, describes each source's output, notes patents soft-fail until reactivated. No contradictions.

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

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

Front-loaded with examples and purpose, then details return structure. Some redundancy in examples, but overall efficient and well-organized for its length.

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

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

No output schema, but description enumerates return components (cik, filings, fundamentals, patents, news, LEI) with format hints. Covers the complexity of a multi-source tool well.

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

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

Input schema covers both parameters with descriptions. Description adds value by clarifying that type is limited to 'company', value can be ticker or zero-padded CIK, and names are not supported (with examples).

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

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

The description uses specific verb-resource pairs (profile a US public company) and provides multiple example queries. It clearly states the tool returns a full cross-source profile in one call, distinguishing it from sibling tools like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' Also advises using resolve_entity if only a name is given, providing clear when-to-use and alternatives.

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

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

The description aligns with annotations (destructiveHint=true, readOnlyHint=false) and adds context about motivations for deletion. It does not contradict annotations.

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

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

Two concise sentences with no filler. The action is front-loaded, and every word 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 tool with one parameter and no output schema, the description covers purpose, usage guidelines, and relationships to siblings adequately.

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

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

The description does not add meaningful information beyond the schema, which already fully documents the single 'key' parameter with 100% coverage. Baseline score applies.

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

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

The description clearly states the action 'delete' and the resource 'previously stored memory by key'. It distinguishes from sibling tools by referencing 'remember' and 'recall' as complementary operations.

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 usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', giving clear guidance on when to use this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds details about fetching the page, extracting metadata, and outputting a markdown blob, which are meaningful behavioral traits beyond what annotations provide. No contradiction.

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

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

The description is concise (4 sentences) and front-loaded with the main purpose. Each sentence adds value: purpose, process, output format, and use cases. No unnecessary repetition.

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 functionality, output format, and use cases adequately. With no output schema, it explains the return value well. Could mention error handling or rate limits given the openWorldHint, but overall sufficiently complete for a simple read-only tool.

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

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

Schema coverage is 100% with both parameters well-described. The description does not add significant extra semantics beyond the schema, as it mentions the 'url' implicitly and does not detail 'max_links'. The defaults and constraints are covered by the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and target AI crawlers. It distinguishes itself from siblings by its unique function of creating a standard llms.txt file.

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

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

The description mentions useful scenarios (getting a client's site indexed, drafting llms.txt, auditing competitor), but does not provide explicit when-to-use vs when-not-to-use guidance or mention alternatives. The use cases are implied but not formally distinguished from sibling tools.

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

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

Annotations already declare non-destructive, read-only, idempotent behavior. Description adds detail on returned format (decoded series with labels and per-period values) and the key filtering mechanism, which augments transparency.

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

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

Concise yet comprehensive. Starts with purpose, then key usage and prerequisite, example, and return format. No wasted words; every sentence adds value.

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

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

Given the complexity (6 params, no output schema), the description covers all critical aspects: prerequisite, key format, large result warning, and return structure. Sibling tool reference completes the picture.

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. Description adds significant meaning to the `key` parameter: explains dot-separated structure, wildcard positions, and the dependency on dataflow_structure. Other parameters are clearly described in schema.

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

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

Description clearly states 'Pull observations from a UNICEF dataset,' specifying the verb and resource. It distinguishes from sibling tools like dataflow_structure by noting the prerequisite and the output nature.

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 to call dataflow_structure first for dimension order. Provides example and warns about large results when omitting key. Lacks explicit when-not-to-use, but the reference to the sibling tool guides context.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc., so the bar is lower. The description adds that there are ~70 datasets and results include id, version, and name, but does not cover limitations like pagination or rate limits. Adds moderate value beyond annotations.

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

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

The description is concise at 5 sentences, front-loaded with purpose, and every sentence adds value. Structurally clear with examples.

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

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

Given the simple tool (2 optional params, no output schema, comprehensive annotations), the description covers purpose, result structure, usage guidance, and examples. No critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples of query usage and context about UNICEF topics, but does not provide new parameter details beyond the schema. Minimal enhancement.

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 browses and keyword-searches UNICEF datasets (dataflows), specifying the verb-resource combination. It distinguishes from sibling tools like dataflow_structure and get_data by explaining that results contain an id for use in those 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 the tool (to find datasets) and gives examples of filtering by query. It implies not to use for accessing data or structure, but does not explicitly list exclusions or alternatives, though siblings are mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return field details and default filtering to active subscriptions, but no additional behavioral traits beyond what annotations provide.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, effectively 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 list tool with one optional parameter and annotations present, description covers purpose, return structure, usage guidance, and parameter context. Complete 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 covers parameter include_inactive fully (100% coverage). Description adds context that default is active subscriptions, but doesn't add significant meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states verb 'list', resource 'subscriptions', and scope 'caller's active'. Also enumerates return fields. Implicitly distinguishes from siblings like subscribe/unsubscribe by being a list operation.

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

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

Description explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides clear context 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?

Adds key behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily. Annotations provide no safety hints, but description fills gaps.

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 efficiently covering purpose, usage, and behavioral notes. No redundancy. Front-loaded with core purpose.

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

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

Complete for a feedback tool: all parameters documented with meaningful descriptions, usage guidelines cover when and how, behavioral traits disclosed, no output schema needed.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by advising to describe issues in terms of Pipeworx tools/packs, linking to context parameter. Also reinforces message specifics. Minor improvement over schema.

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

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

Clearly states the tool is for sending feedback to the Pipeworx team covering bugs, features, data gaps, or praise. Unambiguous verb-resource pair. Distinct from 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?

Explicitly specifies when to use (bug, missing feature, praise), what to include (describe issue in tool terms), and what to avoid (pasting user prompt). Also mentions rate limits and free 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. The description adds behavioral context: aggregated signal, no PII, cached 5min-1h, and return structure. This complements the annotations well.

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

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

The description is concise, well-organized with bullet points, and front-loaded with the core purpose. Every sentence adds value with no redundancy.

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

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

Given low complexity (one optional parameter, no output schema), the description fully covers purpose, usage, parameter semantics, behavioral traits, and caching. It explains return values without needing an output schema.

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

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

Schema coverage is 100% with a description for the 'window' parameter. The description adds value by explaining how different windows affect results (hot vs. steady-state), 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 returns trending tools, packs, and call volume from other AI agents on Pipeworx. It specifies the resource and action, and implicitly distinguishes from siblings like 'discover_tools' by focusing on recent usage trends.

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

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

Three explicit use cases are given: discovering hot data sources, confirming popular tools, and seeing alignment with agent needs. However, it lacks explicit exclusions or alternatives to sibling tools like 'ask_pipeworx'.

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 rich behavioral context: monotonicity checks, partition_sum logic, semantic anchor for cross-event pairs, partition filter, fill check behavior, and reference to custom sizing. 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 long but well-structured. It front-loads the main purpose and then elaborates on each mode. While verbose, every sentence adds value and there is no repetition. Slightly less concise than ideal but effective.

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

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

Given the tool's complexity, the description covers all aspects: invocation, modes, constraints (Jaccard similarity, partition filter), response structure (opportunities[] with fields), fill check logic, and sibling tool reference. Without an output schema, it adequately describes return values.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains what each parameter does, provides examples (e.g., slug format), and describes the behavior triggered (e.g., event mode walks child markets, topic mode searches related events). This goes beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and specifies the verb-resource relationship. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided: use no args for trending_scan, event for a specific market, topic for cross-event scan. It recommends event mode with slug examples and explains the benefits of cross-event mode. This gives clear context on when to use each mode.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description goes far beyond, detailing cache behavior (1h at KV level), the three segments with specific methodologies, filtering knobs, diagnostics, and notes about Fed bets being excluded. 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 long but well-structured with front-loaded purpose, then segments, knobs, and response details. It efficiently covers the tool's complexity without excessive verbosity, though slightly dense.

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 (9 parameters, no output schema, nested concepts), the description is highly complete. It explains segments, filters, diagnostics, edge cases (Fed bets, diagnostic funnel counters), and what the output structure looks like (by_segment, _diagnostics).

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 9 parameters described. The description adds holistic context but does not significantly elaborate on individual parameter semantics beyond what the schema already provides. 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs like 'scan' and 'return', and distinguishes itself from siblings by focusing on Pipeworx data disagreement and providing segments like MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT.

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 targets 'what should I bet on today' use case and states agents discover opportunities without paging hundreds of markets. It provides tradeable-edge knobs and filtering options. However, it does not explicitly mention when not to use this tool over siblings like polymarket_arbitrage, relying on implied differentiation.

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

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

Annotations already declare readOnlyHint true and idempotentHint true. The description adds significant behavioral context: it explains that snapshots are written on cache-miss, has a 60-day TTL, uses daily closes of edge_pp_net, and details the response structure including expired opportunities and snapshot dates. 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 a clear front-loaded purpose, then details on parameters, response, and limitations. However, it is somewhat verbose, especially the RESPONSE section which could be more concise. Still, it earns its length by providing necessary 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?

Given the tool has only 2 optional parameters and no output schema, the description is remarkably complete. It covers inputs, detailed output fields, limits (60-day TTL, daily closes), and the behavior when snapshots are missing. This compensates for the lack of an output schema.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context like default values and constraints (days default 14 max 30, window default '1wk') and enumerates valid window options, providing more clarity than the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, distinguishing it from sibling tools like polymarket_edges by focusing on historical tracking and decay analysis. It specifies the tool answers 'how long has this edge existed and is it shrinking?'.

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

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

The description provides context for when to use the tool (historical edge analysis) but does not explicitly state when not to use it or provide direct alternatives. However, the differentiation from other tools is implied through the detailed output and the mention of 'fresh wide edge vs 3-week-old edge'.

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, idempotent, and non-destructive behavior. The description adds substantial behavioral details: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage, verdicts, and warns about thin legs and forced directional risk. This far exceeds 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 well-structured with clear sections for required params, single-market mode, basket mode, and usage admonitions. It is dense but every sentence adds value. Slightly verbose for the level of detail, but efficient given 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 tool has 4 parameters and no output schema, yet the description comprehensively covers all parameters, explains output fields in detail for both modes, and provides crucial usage context with sibling tools. It is fully adequate for an agent to use this 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 for all 4 parameters. The description adds value by explaining mode-specific behavior (e.g., size_usd interpretation differs between single-market and basket, side auto-detection in basket mode). This enriches the schema descriptions enough to merit above the baseline of 3.

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

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

The description clearly states that the tool performs a realizable-theoretical edge check against live order-book depth, distinguishing two modes (single-market and basket). It explicitly positions itself as a prerequisite for using sibling tools like polymarket_arbitrage and polymarket_edges, making its purpose distinct and highly specific.

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

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

The description provides explicit guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of partial fills and unhedged directional positions, giving clear when-to-use and when-not-to-use context.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes further by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross types) and explaining what causes each warning, adding context beyond annotations. 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 dense but well-structured: core purpose first, then modes, response format, safety fields, and a final caveat. Every sentence adds value, though it could be slightly more concise by using bullet points for the modes and warnings.

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 covers response fields (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It also addresses edge cases like mismatched bet shapes and temporal misalignment. It is mostly complete, though a brief example response would fully close the gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the 'topic' parameter auto-maps to pre-defined events, and explicit tickers override the topic side. It also lists all 10 topic shortcuts and provides example usage, going beyond the schema's brief descriptions.

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

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

The description clearly states the tool computes cross-venue spreads between Polymarket and Kalshi. It distinguishes itself from siblings like polymarket_arbitrage by focusing on the same resolving question across venues and explicitly describing two modes (topic shortcuts and explicit tickers).

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

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

The description provides explicit when-to-use guidance: it explains the two modes, warns that compatibility warnings indicate non-tradeable situations (non-equivalent bet shapes, no token overlap, temporal misalignment), and states that most pre-mapped topics currently return warnings. This tells the agent when results are reliable.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the two operational modes (retrieve specific key vs list all) and scoping to the user's identifier. 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, with the first sentence clearly stating the purpose and modes. It is front-loaded, every sentence adds value, and there is 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?

For a simple tool with one optional parameter, the description fully explains its use cases, scoping, and relationship with sibling tools. Even without an output schema, the return behavior (value or list of keys) is inferable from the description.

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 optional 'key' parameter is fully described in the schema (100% coverage). The description adds meaning by explaining that omitting the key lists all saved keys, and provides examples of what typical keys might be (e.g., ticker, address, notes).

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 value previously saved via remember or lists all saved keys when key is omitted. It uses specific verbs and resource references, and distinguishes from siblings like remember and forget.

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

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

The description explicitly states when to use the tool, gives concrete examples (e.g., user's target ticker, address, research notes), and mentions scoping by identifier. It pairs with remember and forget, providing clear context for use without explicitly stating 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?

Annotations indicate readOnlyHint=true, but the description explains that mark_read parameter changes read state, adding behavioral context beyond annotations. However, this creates a minor contradiction as the tool is not purely read-only.

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, front-loaded with purpose, and uses four clear sentences without 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?

The description covers return fields (source, citation_uri, raw payload) and provides polling guidance and an alternative API. Lacks pagination details but is adequate for a read tool with limit parameter.

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

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

With 100% schema description coverage, the description adds value by giving an example for 'type' ('sec_8k') and explaining the effect of 'mark_read'. It does not significantly enhance 'limit' or 'since' beyond schema.

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

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

The description clearly states 'Pull fired events from your subscription feed,' specifying the action and resource. It distinguishes from sibling tools like 'list_subscriptions' which lists subscriptions, not events.

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

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

The description mentions that polling works fine and gives an alternative API endpoint, but it does not explicitly state when to use this tool over siblings or provide when-not-to-use conditions.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description details parallel fan-out to multiple sources, fallback mechanics, soft-fail for USPTO, and the structured return format including citation URIs. No contradiction with annotations.

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

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

The description is fairly detailed but front-loaded with query examples. Every sentence adds value, though it could be slightly more concise. Nonetheless, it is well-structured and effective.

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

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

Despite no output schema, the description explains the return structure (changes[] grouped by source, total_changes, URIs) and covers edge cases like soft-fail and fallback. It is complete for the tool's complexity and context.

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

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

Schema coverage is 100% with good descriptions, but the description adds significant value: states type is only 'company', explains since accepts ISO dates and relative shorthand with examples, and clarifies value can be ticker or CIK. Also recommends typical since values.

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

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

The description clearly defines the tool as a change feed for a company in a given time window, listing example use cases like 'What's new with X' and explicitly distinguishing from sibling tool entity_profile which provides static profiles.

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

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

Description provides explicit when-to-use examples and states when to use the alternative 'entity_profile' tool. It also explains fallback behavior (GDELT to GNews) and the soft-fail for USPTO, giving clear usage context.

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

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

Annotations (idempotentHint=true, destructiveHint=false) are complemented by description stating scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. No contradictions.

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

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

Description is concise, front-loaded with purpose, and 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?

Covers purpose, usage context, behavioral traits, and integration with sibling tools, all while being sufficient given the simple input schema and lack of output schema.

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

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

Schema coverage is 100%, and the description does not add new parameter details beyond the schema. It provides example values but no additional syntax or constraints.

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 saves data for later reuse, with specific examples (resolved ticker, target address, user preference). It distinguishes from sibling tools recall and forget.

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

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

Explicitly advises when to use ('when you discover something worth carrying forward') and pairs with recall and forget. Also clarifies persistence differences for authenticated vs anonymous users.

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 that each call cascades through several lookup endpoints, replacing 2-3 manual lookups, and specifies return types. This provides useful context beyond annotations without contradiction.

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

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

The description is well-structured with examples, purpose, usage, and details. Every sentence adds value; it is appropriately sized for the tool's complexity. Slightly verbose but not wasteful.

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 lookup tool with two entity types and no output schema, the description fully covers what to expect: input formats, output fields, and citation URIs. It is complete for the task.

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

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

Schema covers both parameters with descriptions. The description greatly enriches the meaning by detailing what each type returns (ticker, CIK, company name for company; RxCUI, ingredient, brand for drug) and gives input examples, adding significant 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 provides specific verb 'resolve' and resource 'entity', with clear examples like 'What's the ticker for...'. It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID', which sets it apart from tools like 'entity_profile'.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear context for when to use. It does not explicitly state when not to use, but the positive guidance is strong. Alternative tools like 'entity_profile' or 'compare_entities' are not mentioned, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: each entity is probed with 'ai_visibility_check', results are ranked by score, and output includes score, confidence, and signal density. This complements annotations without contradiction.

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

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

The description is three sentences long, front-loading the main purpose and then providing details. Every sentence is informative and there is no redundancy, making it efficient and well-structured.

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

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

The description explains the output (ranked list with score, confidence, signal density), covers required and optional parameters, and specifies constraints (2-8 entities). It lacks details on error handling or default behavior for missing parameters but is sufficiently complete for most use cases.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by explaining that the first entity in 'entities' is treated as the 'subject', that 'models' defaults to 'workers-ai', that '_apiKey' is needed only with 'anthropic', and that 'context' disambiguates common names. This enriches parameter 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 uses specific verbs like 'compare', 'probes', 'ranks', and 'surfaces', and clearly identifies the resource (AI visibility across multiple entities) and the action (side-by-side comparison). It distinguishes itself from siblings like 'ai_visibility_check' by emphasizing multi-entity comparison.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question, implying when to use. However, it does not explicitly state when not to use (e.g., for single entity checks) or name alternatives, though the sibling 'ai_visibility_check' implicitly serves that role.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses key behaviors: it fans out across two services, handles partial failures gracefully with a 'sources_failed' list, and notes that bundlephobia's first measurement can take 5-30s. It also specifies the NPM-only ecosystem scope.

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

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

The description is front-loaded with the main purpose and key actions, but it is a single dense paragraph that could be broken into bullet points for clarity. Every sentence adds value, but the structure could be improved.

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 having no output schema, the description thoroughly enumerates the return fields (summary block with keys, per-advisory detail, links, alternative versions), covers partial failures, timing caveats, and ecosystem limitations. For a tool with complex behavior, this is complete.

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

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

Schema description coverage is 100%—both 'package' and 'version' are fully described in the schema. The description adds no new information beyond what the schema provides (e.g., version defaults to latest, scoped packages accepted). Per the rules, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, combining deps.dev and bundlephobia data. It specifies the verb 'check' and the resource 'npm package', and distinguishes it from sibling tools like entity_profile or validate_claim which serve different purposes.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also tells when not to use: for PyPI/Maven/Cargo/Go, it recommends deps.dev:version directly. This provides clear guidance and alternatives.

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

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

Annotations already indicate read-only/idempotent. Description adds rich detail: returns top-N passages with offsets and scores, uses BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation flag. No contradiction.

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

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

Single paragraph, all sentences add value. Front-loaded with purpose and usage. Slightly dense but well-structured 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?

Describes return format (passages, offsets, scores), default for limit, and char cap. With comprehensive schema and annotations, provides complete context for agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds examples for query and mentions cap, but these are minor additions beyond what schema already 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 it performs 'Semantic search INSIDE a fetched record', specifies the resource (text from a fetched record), and distinguishes from sibling tools like ask_pipeworx_grounded by explaining its role as internal search before grounding.

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

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

Explicitly advises using when records are too large for prompts, mentions char cap and truncation, and suggests pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' but provides clear context.

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

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

Annotations already indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds value by specifying OAuth account requirement, delivery channel constraints (phone verification, 10/day SMS cap, webhook auto-disable), and one-time secret delivery. No contradiction with annotations.

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

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

The description is a single dense paragraph, but front-loaded with the main purpose. Every sentence adds value, though it could benefit from bullet points for types and delivery channels. It is efficiently written but not overly long.

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 subscriptions with multiple types and delivery channels, and no output schema, the description is comprehensive. It covers prerequisites (OAuth account), supported types with examples, delivery options with constraints, and post-subscription behavior (feed always on, webhook auto-disable). Leaves little ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant detail beyond schema, including examples for each type (e.g., sec_8k items:["5.02"]), delivery channel specifics (webhook HMAC signing, auto-disable), and constraints like phone verification. This enriches parameter 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 'Create a proactive monitoring subscription to a live-data event stream,' providing a specific verb and resource. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and includes supported types and delivery channels.

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 does not explicitly mention when to use this tool vs alternatives like recent_alerts or list_subscriptions. It implies usage for proactive monitoring and lists type-specific details, but lacks direct guidance on when not to use it or when to prefer sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value beyond annotations by explaining the return format (category-bucketed example questions with tool+argument shape) and the optional topic filtering behavior. No contradictions with annotations.

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

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

The description is front-loaded with example queries and the core purpose. It contains 3-4 sentences, each adding unique value: purpose, category list, usage pattern, and advice for when to use. It is efficient without being overly verbose, though slightly longer than minimal.

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

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

Given the tool has only 1 optional parameter and no output schema, the description is fully complete. It covers purpose, usage guidance, parameter semantics, relationship to sibling tools, and expected output format. There are no gaps for an agent to understand how and when to invoke it.

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

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

Schema coverage is 100%, and the description adds meaning by clarifying the optional nature of 'topic', enumerating valid focus areas (e.g., 'finance', 'pharma'), and explaining that omitting it yields a cross-category spread. This goes beyond the schema's description of 'Optional focus area' and the list.

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

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

The description uses specific verbs 'returns category-bucketed example questions' and clearly states the resource (Pipeworx capabilities) and the outcome (exact tool + argument shape). It distinguishes from sibling tools by positioning itself as the onboarding entry point to be used first, contrasting with meta-tools like ask_pipeworx and entity_profile.

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

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

The description explicitly states when to use the tool: 'the onboarding entry point' and 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It hints at when not to use (after learning) and mentions alternatives like the meta-tools. It lacks explicit exclusions but provides clear context for when it is 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?

The description adds significant behavioral context beyond annotations: it explains that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. Annotations only hint at non-destructive and idempotent behavior, but the description provides concrete details.

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

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

The description is two sentences, efficient and front-loaded. The first sentence gives action and constraint; the second explains the effect. No unnecessary words, earning a top score.

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

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

For a simple one-parameter tool with full schema coverage, the description covers all relevant aspects: action, ownership, side effects (deactivation), and relation to other tools (recent_alerts). No output schema needed, completeness is high.

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

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

Schema coverage is 100%, with the parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description does not add new parameter details but contextualizes the parameter's role within the cancel action. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the action 'Cancel a subscription by id' and specifies the resource (subscription). It distinguishes itself from sibling tools like 'subscribe' and 'recent_alerts' by detailing the effect (deactivation vs deletion) and ownership constraint.

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 ownership enforcement, limiting usage to cancelling own subscriptions. It implies when to use (cancel subscriptions) but does not explicitly state when not to or provide direct alternatives, though context is clear enough.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds behavioral details such as the return values (verdicts like confirmed, refuted), structured form, actual value with citation, and percent delta. No contradictions.

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

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

The description is well-structured, beginning with query patterns, then usage instruction, scope, and return details. It is front-loaded and each sentence adds value, though slightly verbose for a single-parameter 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?

Given the lack of an output schema, the description sufficiently explains return values. Parameter coverage is complete, and annotations cover behavioral aspects. The description is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already fully documents the 'claim' parameter. The description adds context with examples but does not introduce semantics beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims for US public companies via SEC EDGAR + XBRL. It provides example phrasings and distinguishes itself from siblings by being a specialized composite tool that replaces multiple sequential calls.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims). However, it does not explicitly list alternatives or when not to use, but the context is clear given the sibling tools.

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