Airnow

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds context that probing is free for Workers AI but requires a BYO key for Anthropic with direct billing from Anthropic, which is valuable behavioral info 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 three concise sentences, front-loaded with the main action, and includes all key details 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 fully explains return structure (per-model score, confidence, signals, raw_response + combined view). All four parameters are documented, and the tool's purpose 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 coverage is 100%; description adds meaning: explains default model, that _apiKey is needed for Anthropic, provides examples for entity and context, and notes that models array is optional.

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 probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the default model and the option to add Anthropic. This distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence, which are more 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?

Description mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly state when not to use this tool or provide direct comparisons to siblings, missing some guidance.

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

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

Annotations already signal read-only, open-world, idempotent behavior. The description adds that it routes to 3,816 tools, returns structured answers with stable citation URIs, and does not destructively modify anything. 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 somewhat lengthy but front-loaded with the key preference statement. Every sentence adds value, though minor redundancy exists. It is well-structured for quick comprehension.

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

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

Given the tool's complexity (3816 tools, 910 sources), the description is remarkably complete. It covers purpose, use cases, internal routing, and output format. No output schema, but citations are mentioned, which suffices.

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

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

Schema coverage is 100% with all parameters described. The description adds natural language examples demonstrating usage, which aids the AI in understanding parameter semantics beyond the schema.

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

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

The description clearly states it answers factual questions about real-world entities using authoritative data. It lists specific domains (SEC filings, FDA drugs, FRED/BLS, etc.) and provides concrete examples, distinguishing it from 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 states 'PREFER OVER WEB SEARCH' and enumerates when to use (e.g., 'current US unemployment rate'). It gives a broad set of example queries, leaving no ambiguity about appropriate usage.

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

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

Beyond annotations (readOnly, idempotent, openWorld), description reveals critical behavioral details: refusal reasons, cost of extra LLM call, and that answers are extracted solely from tool results, preventing hallucination.

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

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

Single paragraph with clear front-loading of core concept, followed by mechanism, return format, usage guidance, and cost tradeoff. 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?

Despite no output schema, description fully documents return fields and refusal reasons. Covers purpose, behavior, usage, and result structure sufficiently for high-stakes operation.

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

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

Schema already covers all parameters with 100% description coverage, but the description adds context that the question should be in natural language, which is helpful for the agent's 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 it is a 'Hallucination-resistant answer mode for high-stakes reads,' specifies the routing mechanism, and distinguishes from sibling tool ask_pipeworx by emphasizing grounded extraction without invention.

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

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

Explicitly tells when to use this tool (quotable, citable, high-stakes answers) and when to prefer ask_pipeworx (casual lookups), with concrete examples like financial verdicts, legal claims, medical lookups.

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

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

The description discloses extensive behavioral traits beyond annotations, including market resolution, classification, fan-out logic, response shapes, safety mechanisms (low-confidence short-circuit, closed market handling), and resolution-rule risk. Annotations only indicate readOnly and idempotent, but the description adds critical details about edge cases and data processing flow.

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 with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the primary purpose and usage, and every sentence adds value. Minor reduction in length could be possible without losing essential content.

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 thoroughly explains return shapes, resolver contract, parent event extraction, news fields, safety features, and resolution rules. It covers error states (low confidence, closed markets, wide spreads) and provides actionable guidance for agents. The level of detail is appropriate 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?

With 100% schema description coverage, the description still adds significant value by explaining the 'depth' enum options, the flexible 'market' input types (slug, URL, question text), and the 'include_raw' parameter's effect on response size. It provides concrete examples and usage guidance that the schema alone doesn't convey.

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.' This specifies the verb 'research', resource 'Polymarket bet', and scope 'in one call'. It differentiates from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive data gathering for a single bet.

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

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

The description explicitly recommends using the tool for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', providing clear usage context. However, it lacks explicit exclusion criteria or comparison to alternatives, which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is clear. The description adds behavioral details: single parallel call, data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradictions with annotations.

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

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

The description is a single paragraph that front-loads example queries, making it scannable. It is concise given the amount of information, though a more structured format could improve readability.

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

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

Despite no output schema, the description covers return format (paired data + citation URIs) and data sources for both entity types. No critical information is missing; it is complete for its intended use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by specifying that 'values' can be tickers/CIKs for companies or names for drugs, with min and max items. It also explains what data is pulled for each type, 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?

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call. It uses specific verbs like 'compare', 'rank', and 'head to head', and distinguishes itself from sibling tools (e.g., 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 provides explicit guidance on when to use this tool (comparing entities) and when to prefer it over alternatives (sequential lookups). It includes typical query phrases but does not explicitly mention when to use other tools like entity_profile.

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, so the description's value is limited. It adds no behavioral details beyond indicating it returns the latest observed AQI, which is already implied by 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 a single, efficient sentence with no wasted words. It conveys the essential information succinctly.

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

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

Given the simple read-only nature, the presence of an output schema, and comprehensive annotations, the description is mostly complete. However, it could mention the behavior when no station is within the radius or the selection algorithm for multiple stations.

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 covers 100% of parameters with descriptions. The tool description adds no additional meaning 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 clearly states the tool returns the latest AQI for the AirNow station nearest a given lat/lon. It uses specific verbs and resources, distinguishing it from siblings like current_by_zip (zip-based) and forecast_by_zip (forecast).

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 no guidance on when to use this tool versus alternative tools such as current_by_zip or observations_in_bbox. It does not mention conditions where this tool is preferable or any exclusions.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, destructiveHint false. Description adds behavioral context: returns per-pollutant records, nearest site, typical pollutants (O3, PM2.5), and output 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, no redundancy. First sentence immediately states purpose, second adds relevant detail. Every word earns its place.

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

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

Given that output schema exists, description adequately covers return value semantics (per pollutant, fields). Could mention behavior for invalid ZIP codes, but overall sufficient for a simple lookup tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add new information about parameters beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Clear verb+resource: 'Latest observed AQI for a US ZIP code.' Explicitly states output structure (one record per pollutant, fields included). Distinguishes from sibling 'current_by_location' by specifying ZIP code vs. location coordinates.

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

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

Implies use for current AQI by ZIP but does not explicitly state when to use this tool vs. siblings like 'current_by_location' or 'forecast_by_zip'. No 'when-not' or alternative guidance is provided.

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

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

Description adds significant context beyond annotations: decomposition, parallel execution, extraction of verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[] array. Also mentions time expectation (15-60s). Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and description is consistent with 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 front-loaded and well-structured, but slightly verbose. Every sentence adds value, including examples, comparison, requirements. Could be trimmed slightly but remains clear 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?

Given complexity and lack of output schema, description covers: operation mechanics, return structure (findings packet with evidence, citation, gaps), prerequisites (account, paid plan), time estimate, and comparison to siblings. No gaps in required information for agent to use tool correctly.

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

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

Schema coverage is 100% and description adds context: depth enum meanings (quick=3, standard=5, thorough=8) and that thorough requires paid plan. Question parameter is described as natural language, which is helpful beyond the schema's generic description.

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

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

Description clearly states it performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to 3,816 tools. It distinguishes from sibling ask_pipeworx by explaining this is for broad/multi-part questions versus single lookups.

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

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

Explicitly says 'Use for broad or multi-part questions' and gives examples like 'compare X and Y's exposure to Z'. Also says 'use ask_pipeworx for single lookups'. Mentions requirements: Pipeworx account, 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 indicate read-only and idempotent behavior. The description adds key behavioral context beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This informs the agent about the richness and usability of the output.

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, starting with a clear purpose, followed by use cases, and ending with output description. It is concise enough at three sentences. However, it could be slightly more terse by removing redundant phrases like 'with curated examples' since examples are already in the schema.

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 6 parameters (only 1 required) and no output schema, the description is fairly complete. It explains the purpose, when to use, and what is returned. It does not cover all edge cases (e.g., exact behavior of limit), but those are in the schema. The description fills the gaps well 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 description coverage is 100%, so the base is 3. The description adds value by listing aliases (task, q, search, description) and providing example queries ('look up FDA drug approvals'). However, it doesn't elaborate on the 'limit' parameter beyond what the schema states. Overall, it adds marginal clarity but doesn't significantly exceed the schema's documentation.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists specific use cases (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by focusing on discovery rather than direct data access. The verb 'discover' and resource 'tools' are specific and 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 explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides context: 'Use when you need to browse, search, look up, or discover what tools exist for...' While it doesn't explicitly state when NOT to use, the guidance is clear and helpful for an agent deciding between tool discovery and direct queries.

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. Description adds significant context: fans out across multiple sources, lists specific return fields (CIK, filings, fundamentals, patents, news, LEI), and notes patent dependency sunset. No contradictions.

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

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

Single paragraph with dense information; covers all relevant points without unnecessary fluff. Could be slightly more structured (e.g., bullet points) for easier scanning, 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?

For a tool with no output schema, the description thoroughly enumerates the return fields and their sources. It also notes limitations (patents may fail, names not supported) and cross-references sibling tools. Complete for the tool's complexity.

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

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

Description adds meaning beyond the input schema: clarifies type must be 'company', value must be ticker or zero-padded CIK, and explicitly states names are not supported (directing to resolve_entity). Provides examples like 'AAPL' and '0000320193'.

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

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

Clearly states it provides a full cross-source profile of a US public company, with example queries and a list of returned data. Distinguishes from sibling tools by noting it should be preferred over chaining single-pack lookups and that names require a prior call to 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 tells when to use (holistic company view) and when not to (names not supported; use resolve_entity first). Also notes that patents may soft-fail due to API sunset, setting proper expectations.

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

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

Annotations already cover readOnly, idempotent, and destructive hints. The description adds the date default and use case, consistent with 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?

Two concise sentences: first defines the tool, second gives a usage example. 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 simple tool, rich annotations, and existing output schema, the description is complete enough for an agent to understand purpose and usage.

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

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

Schema descriptions cover all parameters at 100% coverage. The description does not add meaningful semantics beyond what is already in the schema, so baseline 3 is appropriate.

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

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

The description clearly states it provides an AQI forecast for a US ZIP code on a given date, distinguishing it from siblings like current_by_zip which gives current AQI.

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 clear use case ('is tomorrow ok for outdoor activity'), implying when to use it, but does not explicitly exclude alternatives or state 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 already indicate destructiveHint=true, and the description reinforces the destructive nature by mentioning deletion and clearing sensitive data. It adds context beyond annotations about the purpose of clearing stale or sensitive data. 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 extremely concise with two sentences that front-load the core action and then provide usage guidance. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers what the tool does, when to use it, and how it relates to siblings. It is fully complete.

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

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

Schema coverage is 100% with the 'key' parameter well-described in the schema. The description adds value by emphasizing 'by key' and contextualizing it with examples, even if no new parameter details are provided.

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 (a previously stored memory by key). It also provides specific use cases (stale context, task done, clear sensitive data) and references sibling tools (remember, recall) for differentiation.

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

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

The description explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and hints at its relationship with remember and recall. It lacks explicit exclusion criteria but provides sufficient 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?

Discloses the process (fetch, extract, emit) and output format beyond annotations. Aligns with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, adding value 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?

Three tight sentences: purpose, process, use cases. No redundancy, every sentence adds unique 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?

Fully covers tool use given low parameter count, no output schema, and complete high-level explanation. Agent can confidently invoke.

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?

Adds default and max values for 'max_links' (25, max 50) not in schema. Provides example for 'url'. Since schema coverage is 100%, description still enriches with practical 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?

Clearly states verb ('generate') and specific resource ('llms.txt file') for any URL. Differentiates from sibling tools like 'scan_competitor_ai_presence' by focusing on generating the standard AI-crawler 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?

Explicitly lists three concrete use cases (client site indexing, own project, competitor audit) and provides context for when to use, making selection unambiguous.

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

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

Annotations already indicate read-only and idempotent. Description adds return field details and the effect of include_inactive parameter, providing beyond annotation info.

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, front-loaded with purpose and return fields, then usage guidance. No wasted words.

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

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

Tool is simple with one optional param and no output schema. Description fully covers purpose, return fields, and usage scenarios.

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 reinforces that default is active only, adding clarity 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 'List the caller's active subscriptions' with specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly states when to use and what to use it for.

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, indicating safe read-only behavior. The description adds contextual details (historical, bbox, date range, parameters) but no major behavioral traits beyond what annotations imply. 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 sentences, each conveying essential information without redundancy. Purpose, parameters, and format are front-loaded and concise.

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

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

Given six parameters (three required) and an existing output schema, the description sufficiently covers purpose, parameters, and formatting. It does not explain data_type options in detail, but schema covers that. Adequate for agent usage.

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

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

Schema coverage is 100%, so schema already documents parameters. The description adds examples and format guidance (e.g., 'OZONE,PM25,PM10,CO,NO2,SO2' and 'minLon,minLat,maxLon,maxLat'), enhancing 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 'Historical AQI observations inside a bounding box for a date range,' specifying the verb (retrieve historical observations), resource (AQI observations), and scoping (bounding box and date range). This distinguishes it from sibling tools like 'current_by_location' (current data) and 'forecast_by_zip' (forecast).

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 formatting guidance for parameters and bbox but does not explicitly state when to use this tool vs alternatives or exclude cases. Usage is implied but lacks explicit context or when-not scenarios.

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

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

Annotations provide no behavioral hints, but the description discloses rate limits (5 per identifier per day), cost (free), and quota impact (doesn't count against tool-call quota). 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?

Four concise sentences front-loaded with purpose, then usage guidelines, then constraints. Every sentence adds essential 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?

Tool is simple; description covers all necessary aspects: purpose, when to use, how to structure parameters, rate limits, and quota. No output schema needed 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 covers all parameters with descriptions (100% coverage). Description adds guidance on message content (be specific, 1-2 sentences, 2000 chars) and reinforces context optionality. Provides extra 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?

The description clearly states the tool is for sending feedback to the Pipeworx team, specifying types like bug, feature, data_gap, or praise. It distinguishes itself from sibling tools, none of which are feedback 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 when to use (bug, missing tool, data gap, praise) and provides a negative example ('don't paste the end-user's prompt'). Gives clear context for each feedback type.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: data source (CF analytics-engine), no PII guarantee, and caching durations (5min-1h). This enriches the behavioral understanding 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: purpose in the first sentence, then bullet-pointed use cases, followed by metadata. 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?

Despite no output schema, the description covers all needed context: what is returned (top tools, top packs, volume), data source, privacy, caching, and parameter guidance. It is complete for an an AI agent to use correctly.

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

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

Schema coverage is 100% with the 'window' parameter fully described (enum, default). The description adds value by explaining the trade-off: shorter windows for hot trends, longer windows for steady-state demand. This is meaningful but not essential, warranting a 4 rather than a 5.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows (24h, 7d, 30d). It specifies the resource (trending data on Pipeworx) and the action (returning aggregates), distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

The description explicitly lists three distinct use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It also notes the tool is self-aggregating, contains no PII, and mentions caching behavior, providing clear when-to-use guidance.

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

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

Annotations indicate read-only, open world, idempotent, non-destructive. The description adds extensive behavioral detail: monotonicity violation checks, partition sum checks, Jaccard similarity threshold, placeholder filtering, fill check against live CLOB depth, and advice on when not to trade. 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 comprehensive but slightly verbose; it front-loads the requirement and mode selection well. Every sentence adds value, though some details like fill check and custom sizing could be more concise or separated.

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 the description enumerates response fields for both modes, including partition_check details and fill_check outputs. Covers all key aspects of a complex tool with two modes and multiple checks.

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 meaning: explains the two modes, provides example slugs, and describes how each mode works (walks child markets vs. searches related events). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, and 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?

Explicitly requires one of event or topic, with recommendations for each mode. It warns against calling with no args. However, it does not explicitly list when not to use the tool or compare to specific sibling alternatives beyond noting custom sizing via polymarket_fill_risk.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description goes far beyond, detailing the internal model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation (edge_pp_net, Kelly fractions), caching at KV level, and diagnostic fields that show why segments might be empty. 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 quite long and dense, packing a lot of technical detail. While well-structured with sections for model families, segments, and knobs, it could be more concise. The volume of information is justified by the tool's complexity, but it borders on being overly verbose 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?

Despite lacking an output schema, the description thoroughly explains the response top-level structure (`by_segment`, `fed_candidates`, `_diagnostics`) and field meanings. It covers edge composition, filters, and caching. Minor gaps: no explicit format for return values (e.g., data types of fields like `edge_pp_net`, `kelly_fraction`), but overall sufficient for an AI agent to understand what to expect.

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 have schema descriptions, achieving 100% coverage (baseline 3). The description adds significant value by explaining the rationale behind knobs like `slippage_pp` (Polymarket zero fees but bid/ask depth), `min_partition_leg_kelly` (different from min_kelly for partitions), and practical guidance on setting values (e.g., bump for thin partitions, drop to 0 with smarter fill model).

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly targeting the 'what should I bet on today' use case. It distinguishes itself from the sibling `polymarket_arbitrage` by focusing on model-driven and structural opportunities rather than simple 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 usage context ('what should I bet on today') and explains that it avoids paging through hundreds of markets. However, it does not explicitly contrast with siblings like `polymarket_arbitrage` or `polymarket_edge_tracker`, leaving some ambiguity about when to use this tool versus those.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: history bounded by 60-day TTL, snapshot creation on cache-miss, gaps possible, and response structure (tracked, expired, 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 relatively long but front-loaded with the core purpose and question it answers. It then provides a concise explanation of response fields. While it could be slightly tighter, each sentence adds value. The structure is logical, starting with intent, then args, then response.

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

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

No output schema exists, but the description fully details the response structure: tracked[] (with fields like edge_pp_net, first_seen, trend, decay_pp_per_day), expired[] (with lifespan_days), and snapshot_dates[]. It explains trend categories and decay computation. This is thorough for a moderate-complexity tool.

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

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

Schema coverage is 100%, and the description adds default values (default 14 for days, default '1wk' for window), explanation of 'window' as snapshot family, and the meaning of days as lookback. It clarifies the parameter purpose beyond the schema definitions.

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

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

Specific verb-resource pair: 'track edge persistence and decay telemetry' from polymarket_edges snapshots. Distinct from sibling tools like polymarket_edges (current edges) by focusing on historical persistence. The question 'how long has this edge existed and is it shrinking?' succinctly defines the tool's unique 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?

Provides clear context: 'a fresh wide edge and a 3-week-old wide edge are different trades' and explains that decay is from daily closes (not intraday). It does not explicitly exclude alternatives, but the context implies when to use historical analysis vs. current edges. Limitations like 60-day snapshot TTL and data gaps are stated.

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, openWorldHint=true, etc., and the description adds substantial behavioral context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and details forced directional risk in basket mode. This goes well beyond what annotations alone 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 detailed but well-structured with headings and clear separation of modes. It is front-loaded with the core purpose. While longer than average, every sentence adds value; no redundancy. A slight reduction in verbosity would be possible, but current structure aids readability.

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

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

Given the tool's complexity (two modes, many return values, no output schema), the description is remarkably complete. It covers all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc., per-leg details, thin_legs, max_clean_notional_usd, forced_directional_risk) and explains edge cases like partial fills and thin books. No gaps remain for an agent to safely use the 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 four parameters. The description enriches these by explaining that size_usd means different things in single-market vs basket mode (max spend vs target proceeds vs settlement notional) and clarifies default behavior for side in basket mode. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making its unique role unmistakable.

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: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the consequences of not using it (uncapturable overround, unhedged directional positions), providing clear when-to-use and when-not-to-use guidance.

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

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

Adds extensive behavioral context beyond annotations: explains safety fields (compatibility_warning, temporal_alignment), skipped cross-type/subtype counters, and why spreads may be invalid. 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?

While lengthy, every sentence adds value and the description is front-loaded with the core purpose. Could be slightly more concise, but well-structured for the complexity.

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

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

Very complete given tool complexity: covers modes, response structure, safety fields, edge cases, and caveats despite no output schema. Addresses both typical and problematic usage scenarios.

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 substantial meaning: explains the two modes, gives topic examples, and clarifies that explicit tickers override topic mappings, providing far more than the bare schema.

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

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

The description clearly states the tool's function as a cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage and compare_entities.

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 pairing), provides examples, and warns that most pre-mapped topics currently return compatibility_warning, guiding agents on 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context beyond annotations: 'Scoped to your identifier' and 'Pair with remember to save, forget to delete.' 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 two sentences with no wasted words. It is front-loaded with the main action and includes essential 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 retrieval tool with one optional parameter and no output schema, the description covers the use case, scoping, and pairing with sibling tools completely.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by explaining that omitting the key lists all saved keys, which goes beyond the schema's description.

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

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

The description explicitly states the verb 'Retrieve' and the resource 'a value previously saved via remember, or list all saved keys'. It distinguishes from sibling tools 'remember' and 'forget' by naming them.

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: 'Use to look up context the agent stored earlier' and how to list all keys by omitting the argument. However, it lacks explicit when-not-to-use or alternative tools beyond the named siblings.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the tool is safe and idempotent. The description adds context on the effect of mark_read (flags events read so next call shows only newer ones) and confirms polling suitability. 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, each with a clear role: main purpose, returned data, filtering parameters, mark_read behavior, and additional access method. No unnecessary words, well front-loaded, and structured logically.

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

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

The description covers the main return fields but lacks full detail on the payload structure or error conditions. No output schema exists, so the description should compensate. It mentions polling and alternative endpoint, which is helpful. However, missing specifics on limit behavior beyond the range in schema and no mention of pagination or error handling.

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 5 parameters are described in the schema (100% coverage), and the description adds meaningful context: explains the effect of mark_read and unread_only, mentions that since is an ISO timestamp, and indicates that type filters by subscription type. This goes beyond the schema descriptions, e.g., not just 'optional filter' but clarifies purpose.

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

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

The description clearly states the tool's purpose: pulling fired events from the subscription feed. It specifies the return content (source, citation_uri, raw payload) and mentions filtering by type and ISO timestamp, distinguishing it well from siblings that are about subscriptions or other data.

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

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

Provides clear usage context: filtering via type and since, managing read state with mark_read. Explicitly states that polling is fine and points to an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. Does not explicitly say when not to use, but the guidance is sufficient.

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

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

The description adds significant behavioral context beyond annotations: fan-out to multiple sources, fallback logic (GDELT→GNews on rate limits or 5xx), soft-fail for USPTO, accepted input formats (ISO date or relative shorthand), and return structure (changes[] grouped by source, total_changes, citation URIs). This complements the annotations (readOnlyHint, idempotentHint, etc.) 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 information-dense but still readable. It could be slightly more structured (e.g., separate lines for sources or return format), but every sentence adds necessary detail. No fluff; efficient 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?

Given the complexity (multiple sources, fallback, future deprecation), the description covers key aspects: input formats, behavior, return structure. However, it omits specifics like error messages or handling of invalid tickers, and the return structure is described only at high level. Still largely complete for an AI agent.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining the 'since' format with examples ('2026-04-01', '7d', '30d', '3m', '1y') and recommending typical values. It clarifies that 'value' accepts ticker or CIK, and that 'type' only supports 'company'. This goes beyond the schema's own 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 concrete example queries like 'What's new with X' and 'latest on Y' to illustrate the tool's purpose. It clearly states 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists specific data sources (SEC EDGAR, GDELT, GNews, USPTO), distinguishing it from siblings (e.g., 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?

Explicit guidance is provided: 'Use entity_profile instead when you want the static profile...'. Also, recommendations for the 'since' parameter ('Use "30d" or "1m" for typical monitoring') help the agent choose correctly.

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

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

Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds scoping by identifier and persistence duration, which are key behavioral traits. No contradiction.

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

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

Three sentences: purpose, usage guideline, behavioral detail. Every sentence adds value. No wasted words.

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

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

Covers purpose, usage, parameter semantics, behavioral traits, and pairing with siblings. No output schema, so no need to explain 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% with clear descriptions for key and value. Description adds usage examples ('subject_property', 'target_ticker') that enhance understanding without repeating 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 saves data for reuse later, with specific verb 'Save' and resource 'data'. It distinguishes from siblings (recall, forget) and gives concrete examples of when to use.

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 mentions pairing with recall and forget. Also clarifies persistent vs 24-hour memory based on auth status.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds behavioral context: it cascades through several endpoints internally, auto-disambiguates, and returns 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 purpose and usage, followed by structured details on types. It contains useful examples and internal context, though slightly verbose. Overall efficient for the information conveyed.

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 2 parameters and no output schema, the description compensates by detailing return values for each type, including citation formats. It covers the essential aspects needed for an agent to use it correctly.

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

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

Schema coverage is 100% and baseline is 3, but the description adds substantial meaning: examples of valid inputs, explanation that type determines return fields (ticker+CIK for company, RxCUI+ingredient+brand for drug), and mentions citation URIs. This goes beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples and a clear distinction from siblings by positioning it as the first step when an ID is needed. It explicitly lists supported types and what each returns.

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,' providing clear when-to-use guidance. It also explains that it replaces manual lookups, but does not explicitly contrast with sibling tools, though the context implies 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 indicate it's read-only, idempotent, and not destructive. The description adds that it probes each entity with 'ai_visibility_check' and returns a ranked list with score, confidence, and signal density, providing behavioral insight 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 extremely concise: three sentences covering purpose, mechanism, and use case. No redundant or vague language; 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 tool's moderate complexity (multi-entity comparison, ranking) and no output schema, the description adequately covers what the tool does and what it returns. Missing details on error handling or limits, but sufficient for correct usage.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that the first entity is the 'subject', but this is already stated in the schema's entity property description. No additional semantic value beyond what the 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 the tool compares AI visibility across multiple entities, using 'ai_visibility_check', ranking by score, and identifying most/least recognized. It distinguishes from sibling 'ai_visibility_check' which is a single-entity probe.

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, giving clear context. It implies usage for multi-entity comparison but does not explicitly exclude single-entity scenarios, though the sibling 'ai_visibility_check' covers 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 already indicate safe, idempotent behavior. The description adds valuable behavioral details: fans out to two services, returns specific fields, degrades gracefully with partial failure info, and mentions potential 5-30s delay for first bundlephobia measurement.

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 that front-loads the purpose and then covers details. No wasted words, but slightly dense; could be broken into multiple sentences for easier scanning. Still very efficient.

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

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

Despite no output schema, the description details every return component: summary block content, per-advisory detail, links, alternative versions. Also covers partial failure behavior with sources_failed field. Fully adequate for an agent.

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

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

Schema coverage is 100%, but description adds context: explains that 'package' accepts scoped packages and 'version' defaults to latest. This provides meaning beyond the schema's basic 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 composite purpose: checking npm packages via deps.dev and bundlephobia for safety, size, and popularity. It distinguishes from siblings by explicitly scoping to NPM ecosystem and mentioning that other ecosystems fall under a different 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 when-to-use guidance: 'whenever an agent asks "is X safe / popular / small"'. Also provides clear exclusions (NPM only v1, alternatives for other ecosystems) and timing caveats for partial failures.

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

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

Annotations already declare safe read-only, open-world, idempotent behavior. Description adds technical details: BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation flag—discloses all important behavioral traits beyond annotations.

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

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

Concise, well-structured description with front-loaded purpose and key features. Every sentence adds value; no redundant or vague statements.

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 semantic search tool without output schema, the description fully covers what it does, when to use, how it works (embeddings, windowing, char limit), and pairing suggestions. 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% but description adds meaning by providing natural-language query examples, explaining the text parameter in context (e.g., SEC 10-K body), and clarifying default limit (5) with range.

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 description: 'Semantic search INSIDE a fetched record.' Specifies input (text, query), output (passages with offsets and scores), and distinguishes from sibling tools like 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.' Also pairs with ask_pipeworx_grounded, providing alternative usage pathway.

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 annotations already indicate it is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds further behavioral details such as authentication requirements, delivery channel limitations (SMS 10/day cap, webhook auto-disable after 10 failures), and the fact that return includes a subscription id. 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 detailed but well-organized: starts with purpose, then requirements, types, and delivery. It is slightly long but every sentence adds value, making it appropriate for the tool's complexity.

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

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

Given the tool's complexity (nested objects, no output schema), the description covers all essential aspects: purpose, prerequisites, type options, parameter details, delivery behaviors, and return value. The agent can correctly invoke the tool with this information.

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 substantial meaning by detailing each subscription type with examples, required/optional fields, and delivery channel constraints. It compensates fully for the lack of output 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and providing subscription types and delivery options.

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 context on when to use the tool (setting up proactive monitoring) and requirements (Pipeworx OAuth account). It also gives examples and limitations, though it does not explicitly state when not to use it 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 indicate read-only, idempotent, open-world (non-destructive). Description adds details: returns category-bucketed example questions with tool+argument shapes, living catalog. 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 front-loaded with common user queries and well-structured, but slightly verbose. Could trim some redundancy ('what can I ask Pipeworx?' repeated). Still earns its place.

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

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

Despite no output schema, the description fully explains return format (category-bucketed example questions with tool+argument shapes). Completeness is high for an onboarding tool with one optional 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?

Schema coverage is 100% for the single parameter 'topic'. Description adds examples of valid topics (finance, pharma, etc.) and explains behavior when omitted (full spread), adding meaning beyond schema.

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

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

The description clearly states the tool returns example questions categorized by topic, with tool and argument shapes. It distinguishes itself from sibling tools by being the onboarding entry point, answering queries like 'what can you do?' and 'give me ideas'.

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 to use this tool first when unsure of Pipeworx capabilities, and to learn meta-tools. Provides guidance on optional topic parameter and when to omit 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 beyond annotations: row is deactivated (not deleted), retains historical events. Annotations indicate idempotent and non-destructive, description adds context on deactivation.

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

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

Two sentences, no fluff, front-loaded with core action and constraint.

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 simple parameter set and no output schema, description fully covers purpose, constraints, and side effects. 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?

Only one parameter 'id' with schema description already clear; description adds no extra info. Schema coverage is 100%, so 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?

Clearly states the verb 'Cancel' and resource 'subscription', and distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement, guiding the agent to use only for own subscriptions, and notes the effect on historical data via 'recent_alerts'.

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 non-destructive nature. The description adds valuable behavioral context: it returns a verdict (confirmed/refuted/etc.), extracted structured form, actual value with pipeworx:// citation, and percent delta. It also discloses the data source (SEC EDGAR + XBRL) and current support scope. No contradictions with annotations.

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

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

The description is relatively long but well-structured: trigger phrases, usage guidance, scope, return details. Each sentence contributes useful information. A minor reduction in length could be considered, but the content earns its place.

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

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

Given only one parameter and no output schema, the description thoroughly covers the tool's purpose, input requirements, return format, source, and use case. It leaves little ambiguity for the agent to invoke the tool correctly.

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

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

Schema coverage is 100% (single 'claim' parameter with description). The description adds value by providing example claims and clarifying acceptable formats, which goes beyond the schema description. It helps the agent format the input correctly.

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

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

The description starts with explicit natural-language triggers (e.g., "fact check", "verify the claim") and clearly states it performs claim verification against authoritative sources. It specifies the domain (company-financial claims via SEC EDGAR + XBRL), which distinguishes it from generic fact-checking tools among siblings like deep_research.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains what the tool replaces (4–6 sequential calls). However, it does not explicitly state when not to use it or list alternative tools for non-financial claims, though the sibling list provides implicit comparison.

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