Worldbank Climate

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context: default free model, optional Anthropic with BYO key, per-model and combined return structure, and scoring range. 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 four sentences, front-loaded with the main action, and efficiently covers purpose, parameters, and use cases. No superfluous text.

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

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

Despite no output schema, the description explains the return format (per-model score, confidence, signals, raw_response plus combined view). Combined with annotations, this provides sufficient completeness for a probing 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 descriptions for all parameters. The description adds value by clarifying default model behavior, the optional nature of _apiKey and its pass-through, and the purpose of the context parameter for disambiguation.

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility. It specifies verb (probe), resource (LLMs), and output (score 0-100). However, it does not explicitly differentiate from sibling tool 'scan_competitor_ai_presence', which may share a similar purpose.

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

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

The description lists use cases (AI-marketing audits, brand checks, competitive monitoring) but does not provide when-not-to-use guidance or explicit alternatives. The context for when to choose this tool over siblings is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds that it returns structured answers with citation URIs and routes to many tools. No contradiction; the description enriches transparency with behavioral details 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 long but every sentence adds value. It is front-loaded with the key directive to prefer over web search, then details, then usage examples, and finally escalation paths. No waste, perfectly structured for quick 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?

Given the high schema coverage and rich annotations, the description covers purpose, usage guidelines, behavioral traits, and alternatives. Although no output schema, it mentions returning structured answers with citations, which is sufficient. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with all property descriptions including aliases. The description reinforces that the question is in natural language and provides examples, adding context beyond the schema. A slight bump above baseline 3 due to the examples clarifying usage.

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

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

The description clearly states the tool's purpose: answering questions about current/historical data from many sources, routing to 4,482 tools. It uses specific verbs like 'ask' and describes the resource as a gateway to structured data. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research for specific cases.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', lists example queries, and tells when to use alternatives. It clearly states this is the default entry point and when to step up to other tools, offering both context and exclusions.

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

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

Discloses the full behavior: same routing as ask_pipeworx, tool selection from many sources, fetches data, extracts answer only from tool result, returns explicit refusal reasons. Annotations already show readOnly, openWorld, idempotent, non-destructive; description adds process detail and refusal logic, which is beyond annotations.

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

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

Front-loaded with purpose and key feature. Structured well: summary, process, when-to-use, cost mention. Slightly verbose but each sentence adds value. Could be tightened slightly.

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 (grounded QA with refusals), the description is remarkably complete. It explains return format (answer, evidence, confidence, etc.), refusal reasons, and when to use. No output schema, so description fills 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 covers all parameters with descriptions. Description adds context that the question is used for routing and fetching, but doesn't add significant detail beyond schema. Baseline of 3 is appropriate given 100% 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Describes the process: routes, fetches data, extracts answer only from tool results. Distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call and use cases.

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

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

Explicitly lists when to use (high-stakes, financial/legal/medical, when quoting/citing) and when to prefer the cheaper alternative 'ask_pipeworx' (casual lookups). Also mentions cost trade-off.

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

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

The description extensively discloses behavioral traits: market resolution, classification, fan-out to data sources, response shapes, resolver contract, parent event extraction, safety shortcuts (low-confidence, closed markets, wide spreads), and cancellation rules. This far exceeds the information in annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), adding rich behavioral context.

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

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

The description is comprehensive but verbose, spanning multiple details that could be condensed. It is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), which aids readability, but the overall length may overwhelm an agent.

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

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

Given the tool's complexity (3 parameters, no output schema, rich internal logic), the description is exceptionally complete. It covers input formats, internal processing steps, response structure (including result.market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety considerations. An agent has everything needed to use and interpret the tool's output.

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

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

With 100% schema description coverage, baseline is 3. The description adds value beyond the schema by clarifying acceptable input formats (slug, URL, question text), explaining depth options with defaults, and describing the include_raw parameter's effect on response size. The fan-out examples also implicitly demonstrate parameter usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and common use cases ('should I bet on X', 'what does the data say about Y'), effectively distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly mentions when to use the tool ('Use for ...'), providing clear context. However, it does not explicitly mention when not to use it or suggest alternatives among siblings, which would improve guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: pulls latest SEC filings for companies with correct fiscal year handling, FAERS data for drugs, sorts results, and returns citation URIs. 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 somewhat long but front-loaded with key trigger phrases and a clear usage instruction. Every sentence adds value, though a few phrases could be trimmed without loss.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citation URIs), the description covers essential aspects. No output schema exists, but the description hints at the return format (paired data + URIs). Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds examples of acceptable values (tickers for companies, drug names) and explains what each type returns, beyond the schema's basic type 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 performs side-by-side comparison of 2-5 companies or drugs with specific metrics (revenue, net income, etc. for companies; adverse events, approvals for drugs). It also distinguishes itself from siblings like entity_profile by emphasizing it replaces sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides natural language triggers (e.g., 'compare X and Y', 'which is bigger'). While it doesn't explicitly state when not to use, the context is clear and provides an alternative approach.

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 behavioral traits beyond annotations: returns findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and explicit gaps[]; decomposes question into facets; routes to 4,482 tools in parallel; expects 15-60s execution time. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all consistent).

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

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

The description is comprehensive but slightly long. However, it is front-loaded with the most critical info (account requirement and alternative tool). Every sentence provides unique value, and the structure flows logically from constraints to capability to output to usage 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 the tool's complexity (1129 sources, 4482 tools, no output schema), the description fully covers return format, performance, limitations (gaps[]), and alternative tools. The agent has enough context to decide when to invoke and what to expect, despite the absence 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%, and the description adds significant meaning: explains that 'question' should be natural language and multi-part is fine, and clarifies the 'depth' enum values with exact facet counts (quick=3, standard=5, thorough=8). This goes well beyond the schema's minimal descriptions.

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

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

The description uses specific verbs (decomposes, routes, returns) and clearly identifies the resource (structured data across Pipeworx's 1129 sources). It distinguishes the tool from siblings like ask_pipeworx (single lookup) and mentions it is not open-web search, making it easy for the agent to select correctly.

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 when-to-use (broad/multi-part questions over structured data), when-not-to-use (for breaking news or single lookups, prefer ask_pipeworx), and prerequisites (account required; alternative ask_pipeworx if not signed in). Also explains the depth parameter meaning (quick=3, standard=5, thorough=8 facets).

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. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' which provides behavioral context beyond the 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 a single well-structured paragraph that starts with purpose, then usage, then returns, then when to call. It is informative without being verbose. Slightly more concise could be possible, but it is 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?

Given no output schema, the description explains return values adequately: names, descriptions, schemas, callable. Parameter count 6 with many aliases is covered. No major gaps for a discovery tool.

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

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

Schema coverage is 100% but the description adds value by naming aliases for the query parameter (task, q, description, search) and explaining the limit default and max. This surpasses the schema's 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's purpose: 'Find tools by describing the data or task.' It lists many specific domains and emphasizes that it returns top-N relevant tools with full schemas. This distinguishes it from sibling tools, which are specific single-purpose 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 says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context on when to use, though it does not explicitly state when not to use or list alternatives beyond the sibling list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: it fans out across multiple sources, describes output fields, and mentions the patents soft-fail (USPTO sunset May 2025). This goes well beyond the annotations.

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

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

The description is fairly long but each sentence adds essential information. It is front-loaded with example queries and the main action. Minor redundancy could be trimmed, but overall 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?

No output schema exists, so the description must cover return values. It lists fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details. It mentions the patents soft-fail. It does not address pagination or rate limits, but for a single-call profile tool it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that names are not supported and that a ticker or zero-padded CIK is required, and it references 'resolve_entity' as the alternative. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with example queries and a list of data sources. It distinguishes itself from chaining individual lookups and from sibling tools like 'resolve_entity' by specifying when to prefer this tool.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It specifies required input format (ticker or zero-padded CIK) and directs to 'resolve_entity' if only a name is available.

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 destructive and idempotent behavior. The description adds context about clearing sensitive data and pairing, but no additional behavioral details beyond what is in annotations.

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

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

Three sentences, no wasted words, front-loaded with the action and key details.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and pairing with siblings.

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

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

Schema coverage is 100%, so the description does not add meaning beyond what the schema provides for the 'key' parameter. Baseline score of 3 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 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and recommends pairing with siblings.

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

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

The description adds significant behavioral context beyond annotations: it explains that the tool fetches a page, extracts title/description/key links, and emits standard llms.txt markdown format. The annotations (readOnlyHint=true, idempotentHint=true) are consistent, and no contradictions exist.

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 with four front-loaded sentences, each adding value: purpose, process, output, and use cases. No wasted words.

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

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

Given the tool's moderate complexity (generating a file from a URL with one optional parameter), the description covers core aspects. Minor details like error handling are omitted, but with strong annotations, this is acceptable.

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

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

Schema description coverage is 100% (both url and max_links have descriptions in schema). The tool description does not add new parameter-level information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('production-ready llms.txt file'), clearly distinguishing it from siblings. No other tool in the list appears to generate llms.txt files, so the purpose is unambiguous.

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 includes explicit use cases ('useful for: ...') but does not provide when-not-to-use or alternatives. However, the tool's unique functionality implicitly guides the agent when to invoke 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), description adds critical behavioral details: return format (keyed by ISO3, inner key format), warnings about some collections not returning data in testing, and the fact that default periods and scenarios vary by product. This is transparent about limitations and behavior.

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

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

Description is front-loaded with core purpose and parameter overview, followed by three worked examples. While it is somewhat long, every sentence adds value, and examples are justified. Could be slightly tighter but remains efficient.

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

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

Given 8 parameters with no required ones, no output schema, and no enums, the description covers defaults, return format, error handling (indicator_code fallback), and data sources comprehensively. It provides sufficient context for proper invocation without external references.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the assembly logic, default behaviors, and mapping examples to actual results. It also clarifies the composite indicator code structure, which goes beyond schema descriptions.

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

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

Description clearly states the tool retrieves World Bank CCKP climate data, specifying both historical observations and CMIP6 projections, and lists the variables (mean temperature, max/min, precipitation). It provides a specific verb+resource combination and distinguishes itself from siblings by being the only climate data tool in the list.

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 gives clear usage guidance: pass components as separate args, and the tool assembles the composite indicator code. It provides worked examples covering various scenarios, and advises using indicator_code if assembly fails. However, it does not explicitly state when not to use or provide alternatives, though none are needed given sibling tools are unrelated.

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 mark it as read-only, idempotent, and non-destructive. The description adds that it returns a 'static reference object,' confirming idempotency, and describes the content (variables, scenarios, etc.), which goes beyond annotations.

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

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

Description is two sentences, front-loaded with purpose. The second sentence mostly repeats the first instruction; could be slightly more concise, but overall efficient.

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

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

With zero parameters and no output schema, the description adequately explains the tool's output (list of components) and its role as a prerequisite for get_climate_data. Annotations fill safety details. Complete for a simple reference 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?

No parameters are defined in the schema, and description correctly states 'Takes no arguments.' With schema coverage at 100% (trivially), the description adds no further param info, but baseline for 0 params is 4.

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

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

The description clearly specifies the tool returns a static reference object documenting all verified CCKP indicator-code components, listing variables, scenarios, periods, products, aggregations, and code order. It distinguishes from sibling get_climate_data by noting it should be called beforehand.

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 before get_climate_data to learn valid parameter combinations, and repeats that it takes no arguments. Provides clear when-to-use and implies when not needed (after parameter knowledge).

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

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

Annotations already declare readOnly and idempotent. Description adds useful context on returned fields, no contradictions.

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

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

Two sentences, front-loaded with purpose and outputs, followed by usage guidance. Efficient and 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?

With one simple parameter, no output schema, and strong annotations, the description fully covers what the agent needs.

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

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

Schema coverage is 100% with parameter description. Description doesn't mention parameter, so no added value beyond schema.

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

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

Clearly states 'List the caller's active subscriptions' with verb and resource. Lists return fields, distinguishing from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. No explicit exclusions but context is clear.

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

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

Annotations are minimal, so description carries the burden. It discloses rate limits (5 per identifier per day), free usage, no quota impact, and how feedback is used (digest, roadmap). No contradictions with annotations.

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

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

Concise but comprehensive. Two sentences cover usage guidelines, then behavioral details. Every sentence earns its place. Well-structured, front-loaded with purpose.

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

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

Given no output schema, the description could mention acknowledgment or what happens after submission, but it's not essential. It covers purpose, usage, constraints, and parameter semantics sufficiently. Slightly incomplete for a feedback tool.

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

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

Schema coverage is 100%, but description adds meaning: explains enum values for type (bug, feature, etc.), recommends message length (1-2 sentences, 2000 chars max), and clarifies that context is optional structured reference. This adds value beyond schema.

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

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

Description clearly states the tool's purpose: send feedback about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools by being a feedback mechanism, whereas siblings are query/analysis tools. The verb 'tell' and resource 'Pipeworx team' are specific.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user's prompt). Provides alternatives implicitly by listing sibling tools. This is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds valuable behavioral details: caching behavior (5min-1h), source (CF analytics-engine), and privacy (no PII). 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 compact (~100 words) and front-loaded with the core purpose. Uses enumeration for use cases. Every sentence adds value; no unnecessary filler.

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 read-only tool with one optional parameter and no output schema, the description fully covers return contents (top tools, packs, volume), caching policy, and data source. Annotations confirm safety. Nothing missing.

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

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

Schema covers 100% of the single parameter (window) with enum. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Enhances understanding beyond the schema.

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

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

Clearly states 'Returns the top tools, top packs, and total call volume' — a specific verb-resource pair. Distinguishes from siblings like discover_tools by focusing on trending usage derived from other agents' 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?

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, checking alignment) with practical context. Does not specify when not to use, but the use cases are clear and the tool's niche is well-defined.

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 read-only, open-world, idempotent, non-destructive. Description adds detailed behavioral context: walks child markets, checks ordering, partition_sum check, semantic anchor with Jaccard similarity, partition filter, fill check with realizable edge, and response structure. No contradictions.

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

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

Description is lengthy but well-structured, front-loaded with requirements, then mode explanations, then fill check. Every sentence adds value; for a complex tool, it balances detail and clarity without being overly verbose.

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 complexity, no output schema, and 100% schema parameter coverage, the description thoroughly explains return structure (opportunities, partition_check, fill_check), filters (partition, similarity), and trade signals. It is complete for an agent to understand tool behavior and output.

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

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

Schema covers both parameters with descriptions. Description adds usage guidance: event for single-event mode (recommended), topic for cross-event scanning, with examples. Provides meaningful context beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event for single-event, topic for cross-event), which differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states REQUIRES one of 'event' or 'topic' and that calling with no args fails. Recommends event for specific market and topic for cross-event scanning, and mentions custom sizing should use polymarket_fill_risk. Provides clear context but lacks explicit 'when not to use' beyond that.

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, and destructiveHint. The description adds significant behavioral context: caching strategy (1h KV cache), response structure (by_segment, diagnostics), explanation of edge calculation and Kelly sizing, and a caveat 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 lengthy but well-structured, using section-like formatting (e.g., 'TRADEABLE-EDGE KNOBS', 'RESPONSE TOP-LEVEL') and front-loading the purpose. Some details could be more concise (e.g., repeated explanation of model families), but overall it is organized and information-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 response), the description is highly complete. It explains the three response segments, diagnostics, Fed bets exclusion, and all parameters in detail. Without an output schema, the description fully covers the response structure and edge calculation, ensuring an agent can understand and invoke the tool correctly.

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

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

All 9 parameters are fully described in the schema (100% coverage). The description adds extra meaning: default values, recommended settings, and usage context (e.g., slippage_pp explains Polymarket fees; min_partition_leg_kelly clarifies its applicability). The extensive additional information elevates the score above the baseline.

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

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

The description clearly states the verb ('scan' and 'return') and the resource ('Polymarket markets'), with the specific purpose of finding opportunities where Pipeworx data disagrees with market price. It explicitly positions the tool for 'what should I bet on today' and differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear guidance on when to use the tool (e.g., discovering edges without paging hundreds of markets) and describes tradeable-edge knobs and diagnostics for handling empty segments. However, it lacks explicit when-not-to-use instructions or comparisons with sibling tools like polymarket_arbitrage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: it explains the telemetry comes from daily snapshots, describes the response structure (tracked, expired, snapshot_dates), notes data limits (60-day TTL, decay from daily closes), and clarifies that it is read-only and non-destructive. 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 dense but well-structured, front-loading the core purpose before detailing response fields and limits. It uses clear sections with inline definitions. Though lengthy, every sentence adds necessary information; no redundancy. Slightly verbose but appropriate for the data-heavy 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?

Without an output schema, the description comprehensively explains the response format (tracked, expired, snapshot_dates) and their fields. It covers parameter defaults, limitations (60-day TTL, daily closes), and how decay is computed. An agent can fully understand what the tool returns and how to use 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?

Input schema has 100% coverage with descriptions for both parameters (days and window). The description restates defaults and max for days, and default for window, but adds no new semantic information beyond what the schema provides. Therefore, value is marginal, earning baseline 3.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers specific questions about edge duration and decay. It names the resource (daily snapshots) and distinguishes it from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description implicitly guides when to use the tool by contrasting fresh vs old wide edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly list alternatives or state when not to use it, though the sibling list includes closely related tools like polymarket_edges.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: it checks live order-book depth, walks the ladder, returns a verdict (clean/degraded/cannot_fill), and warns about forced directional risk and thin books. No contradictions with annotations; instead, it enriches understanding of the non-mutating, analytical nature.

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

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

The description is relatively long but well-structured with clear sections (SINGLE-MARKET:, BASKET:) and front-loaded purpose. Every sentence adds value, though some could be tightened. The structured format aids readability without being verbose.

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 (two modes, 4 parameters, no output schema), the description is exceptionally complete. It details both modes, lists all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains the verdict and forced directional risk, and provides use-case context. It covers every aspect needed for safe invocation.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema descriptions: for 'side', it explains default auto determination for basket based on partition sum; for 'size_usd', it clarifies interpretation (spend vs. target proceeds for single-market, settlement notional for basket) and constraints (default 1000, clamp 10–1,000,000). This helps the agent select correct 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 states the tool's purpose: performing a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by recommending usage before acting on their signals. The verb 'check' and resource 'edge' are specific and non-redundant.

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

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

The description provides explicit usage guidelines: it requires either 'market' or 'event', explains the default behavior for 'side' and 'size_usd', and details single-market vs. basket operation. It includes when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and why (partial basket fills convert an arb into an unhedged directional position). This is comprehensive directive.

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?

Goes far beyond annotations by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), the spread formula (Kalshi − Polymarket), and limitations (real spreads rarer than shortcuts suggest). Annotations indicate readOnly=true, consistent with non-destructive nature.

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

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

The description is comprehensive but verbose, with many technical details that could be condensed. Front-loaded with main purpose and modes, but the safety field breakdown is lengthy. Adequate but not lean.

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 (dual venues, multiple modes, compatibility logic), the description is fully complete. Explains response format (leg-by-leg prices, top_spreads_pp), safety checks, and temporal alignment. No output schema, so description bears responsibility and delivers.

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 100% with descriptions for each parameter. The description adds context: lists 10 topic shortcuts, explains how explicit tickers override mapped ones, and provides examples. Adds meaning beyond schema by clarifying behavior when parameters are omitted.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb 'Cross-venue spread' and resource. It distinguishes from siblings like polymarket_arbitrage by focusing on two venues.

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

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

Explicitly describes TWO MODES (topic shortcuts and explicit tickers) with examples and explains when to use each. Warns that most pre-mapped topics return compatibility_warning, guiding against assuming tradeability. Could explicitly contrast with sibling tools but sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping context (anonymous IP, BYO key hash, account ID) and relationships with remember/forget, which provides added 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?

Description is concise, front-loads the main action, and each sentence adds value. Slight room for trimming but overall well-structured.

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

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

Given the tool's low complexity (1 optional param, no output schema), the description fully explains behavior (dual mode: get/list), scoping, and related tools, leaving no gaps.

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

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

Schema coverage is 100% (1 parameter described). The description adds meaning by explaining that omitting 'key' lists all keys, and provides an example, going beyond the schema.

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

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

The description clearly specifies the verb 'Retrieve' or 'list', names the resource 'value saved via remember' or 'all saved keys', and distinguishes from siblings 'remember' and 'forget' by mentioning pairing.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch'. Omits explicit when-not-to-use, but the purpose 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 declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: the return fields, the effect of mark_read on subsequent calls (stateful cursor behavior), and that polling works fine. This goes beyond the annotations.

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

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

The description is concise and well-structured: front-loaded with the main purpose, then detailed features in separate clauses. 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 absence of an output schema, the description explains the return fields (source, citation_uri, payload) and covers parameters, usage patterns, and an alternative access method. It is complete for this retrieval 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%, so the bar is lower. However, the description adds examples for 'type' and explains the impact of 'mark_read', providing practical meaning beyond the schema descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed, using a specific verb and resource. It implies retrieval of recent alerts, which distinguishes it from subscription management tools like list_subscriptions, though not explicitly.

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

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

The description provides usage context (filtering, polling, mark_read) and mentions an alternative access URL, but does not explicitly compare with sibling tools or state when not 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 readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavioral context: fans out to multiple sources, fallback logic, USPTO soft-fail, and structured response with URIs. 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?

Description is well-structured: front-loaded with usage intent, then behavior, then parameter details, then alternative tool. Every sentence adds information 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?

Despite no output schema, description explains return structure (changes[], total_changes, pipeworx:// URIs). Covers multiple data sources, fallback, soft-fail, and parameter constraints. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions. Description adds value by explaining since accepts ISO or relative shorthand with examples, and notes type currently only supports company. Could mention value parameter accepts ticker or CIK, but schema already does.

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 specifies verb ('change feed'), resource ('company'), and scope ('last N days/weeks/months'). Clearly distinguishes from sibling tool entity_profile by explicitly stating when to use the alternative.

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 examples ('What's new with X'), explains fallback behavior (GDELT to GNews), and directs to entity_profile for static profile. No ambiguity about when 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?

Describes key-value storage, scoping by identifier, persistence differences (authenticated vs anonymous), and absence of destructive behavior. Annotations already indicate idempotentHint=true, no contradictions.

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

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

Four concise sentences front-loaded with purpose, then usage, then details. No wasted words.

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

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

For a simple two-parameter tool with no output schema, description covers purpose, usage, persistence behavior, and sibling relationships completely.

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

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

Schema has 100% coverage with descriptions for key and value. Description adds naming conventions and value types, providing extra context beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference), distinguishing it 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 says 'Use when you discover something worth carrying forward' and 'Pair with recall to retrieve later, forget to delete', providing clear context and alternatives.

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

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

Annotations already mark readOnly, idempotent, etc. Description adds that it cascades through multiple internal endpoints and auto-disambiguates inputs, providing deeper operational insight. 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 efficiently front-loads example queries, then gives purpose, supported types, and detailed output. Every sentence provides unique value with no redundancy.

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

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

Despite no output schema, description fully explains return objects for both entity types. Covers input variants, internal cascading, and sets expectations about replacing multiple lookups. Complete for a resolution 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 covers both parameters (enum for type, string for value). Description enriches with concrete examples, accepted formats per type, and specifics of what each entity type returns (ticker, CIK, RxCUI, citation URIs), adding substantial meaning beyond schema.

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

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

Description starts with concrete user queries, then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifier'. It explicitly lists supported types and their outputs, clearly distinguishing from siblings 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?

Description says 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. While it doesn't enumerate when not to use it, the context is clear. Sibling tools like compare_entities suggest usage after resolution.

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, etc. The description adds context about internally calling ai_visibility_check and returning a ranked list with specific fields, which is 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?

Three sentences, front-loaded with main purpose, no unnecessary words.

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

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

Sufficiently describes output format (ranked list with score, confidence, signal density). Lacks handling of probe failures or rate limits, but given idempotent and read-only annotations, it's acceptable.

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 critical semantic info: first entity is treated as 'subject' for narrative, and mentions probing with ai_visibility_check, explaining how entities are used.

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

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

The description clearly states it compares AI visibility across multiple entities, differentiates from the sibling ai_visibility_check by specifying side-by-side comparison and ranking, and uses specific verb-resource pair.

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 a concrete use case ('competitive AI-marketing audits') and an example question, implying when to use. Lacks explicit exclusions or alternatives beyond mentioning ai_visibility_check.

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

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

Adds significant behavioral context beyond annotations: describes partial failure handling, 5-30s bundlephobia delay, sources_failed list, and graceful degradation. 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?

Efficiently front-loaded with purpose and composite nature. Every sentence adds value, but the paragraph is dense and could be more scannable with bullets or shorter sentences. Still very clear.

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

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

Complete for a 2-param no-output-schema tool. Lists all return fields including summary, detail, links, alternatives. Also covers edge cases like partial failures and first measurement delay.

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 3. The description adds no extra meaning beyond schema; it repeats that version defaults to latest. No deeper context about parameters.

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

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

The description clearly states it is a composite check for npm packages, using deps.dev and bundlephobia. It distinguishes from siblings by specifying NPM ecosystem only, and contrasts with other ecosystem tools.

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

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

Explicitly states when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides when not to use: for other ecosystems, use deps.dev directly.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds technical details: embedding model, window size, character cap with truncation. No contradictions.

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

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

Three sentences, front-loaded with main purpose. No filler; every sentence adds unique information (usage guidance, tech details, pairing).

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

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

No output schema, but description explains return format (top-N passages with offsets and similarity scores). Covers truncation behavior and pairing. Complete for a search 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%, baseline 3. Description adds value with examples for query, and clarifies limit range and default. Provides extra context beyond schema.

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

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

Clear verb+resource: 'semantic search INSIDE a fetched record'. Distinguishes from siblings by specifying it works on already-fetched records and pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Mentions pairing with another tool. Lacks explicit negative cases but provides strong contextual 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?

Beyond annotations (readOnlyHint false, idempotentHint true, etc.), the description discloses critical behavioral details: auth requirement, return of new subscription id, delivery constraints (10/day SMS cap, webhook auto-disable after 10 failures), and one-time webhook secret retrieval. No contradictions with annotations.

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

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

The description is well-structured with clear sections and front-loaded information, though it is somewhat lengthy. It effectively uses listing and examples without being overly verbose.

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 (nested parameters, multiple types, delivery options, no output schema), the description covers all essential aspects: purpose, auth requirement, parameter usage, return value, and delivery behavior. It is virtually complete for an agent to invoke correctly.

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

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

Even with 100% schema description coverage, the description adds significant value: it explains the always-on feed channel, provides usage examples for each subscription type, and details constraints like SMS cap and webhook auto-disable. This goes beyond what the schema provides.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and explicitly distinguishes the tool from sibling tools like unsubscribe and list_subscriptions by its unique purpose of creating new subscriptions.

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

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

The description provides clear context for when to use the tool, including the requirement for a Pipeworx OAuth account and detailed examples for each subscription type. It could be more explicit about when not to use it (e.g., for one-time queries), but overall usage guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by explaining the return structure (category-bucketed examples with tool shapes), which is beyond what annotations provide.

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

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

Front-loaded with the core purpose, but includes a detailed list of categories which adds length. Could be slightly more concise, but the structure is clear and 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?

Description fully explains the return format and behavior. Given no output schema, it adequately covers what the agent can expect, making it complete for its use case.

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

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

Schema coverage is 100% with a single optional parameter. Description reinforces that omitting the parameter gives the full spread and lists concrete topic values, adding context beyond the schema.

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

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

Description clearly states it is the 'onboarding entry point' and explicitly defines what it returns: category-bucketed example questions with exact tool+argument shapes. It also distinguishes itself from siblings by being the tool to use first when unsure.

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

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

Explicitly advises to 'Use this FIRST' when you don't know what Pipeworx can do. Implies alternatives by mentioning topic focus but doesn't 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 important behavioral traits beyond annotations: ownership enforced, soft-deactivation instead of hard deletion, and impact on historical data. No contradiction with annotations.

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

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

Two concise sentences with no wasted words. Front-loaded with core purpose, then adds key behavioral details.

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

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

Covers all necessary aspects for a simple tool: purpose, ownership, side effects. Lacks explicit mention of return value or success indication, but with no output schema, this is acceptable.

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

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

Schema has 100% coverage and already describes the 'id' parameter as a UUID returned by subscribe. The description only repeats 'by id' adds minimal additional value.

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

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

Clearly states the action ('cancel a subscription') and the resource ('by id'). Distinguishes from related sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), which guides appropriate use. Notes the row is deactivated, not deleted, preserving historical events. Could be more explicit about when not to use, but context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, and not destructive. The description adds details about the return format (verdict types, actual value with citation, percent delta) and domain limitations (company-financial claims, US public companies, SEC EDGAR + XBRL), which enhances transparency beyond annotations.

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

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

The description is relatively long but well-structured, starting with example phrases and use cases before diving into specifics. Every sentence adds value, though some redundancy might be trimmed.

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

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

Despite lacking an output schema, the description fully explains the return verdict types and additional data (citation, delta). It also covers domain scope and the tool's efficiency improvement over sequential calls, making it self-contained.

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

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

Input schema has 100% coverage with a description for the single parameter 'claim'. The description provides example claim formats ('Apple's FY2024 revenue was $400 billion'), adding context that helps agents formulate correct input.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides example query phrases and distinguishes itself by noting it 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 advises 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives example phrasings but does not specify when not to use or mention alternative tools, though sibling context provides differentiation.

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