Weather

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the bar is lower. The description adds behavioral details: default model is Workers AI Llama-3.3-70b (free), Anthropic requires a BYO key, and returns per-model {score, confidence, signals, raw_response} plus a combined view. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core purpose, followed by key behavioral details and use cases. Every sentence contributes 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?

Given 4 parameters (1 required, all described) and no output schema, the description covers all necessary context: what the tool does, how to use optional parameters (models, _apiKey, context), default behavior, return structure, and typical use cases. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the entity parameter (the thing to ask about), models (which models to probe), _apiKey (passed straight through to api.anthropic.com), and context (disambiguates common names). This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('Probe', 'score visibility') and a clear resource ('one or more LLMs' about 'business/brand/product/topic'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by covering general visibility checks for AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default free model and the optional _apiKey for Anthropic, giving guidance on when to use each. It does not explicitly state when not to use or name alternatives, but the context 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?

Annotations already cover read-only, open-world, idempotent. Description adds that it routes to 3,751 tools across 886 sources and returns stable citation URIs, which is valuable context beyond annotations.

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

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

Description is front-loaded with key preference statement, then details and examples. Each sentence adds value, though it's slightly lengthy. Well-structured and clear.

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

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

Despite no output schema, description explains return format (structured answer with citation URIs) and covers many domains. Complete for a query tool with broad capabilities.

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 aliases for the 'question' parameter. Description doesn't add parameter-specific detail but provides overall usage guidance. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to answer questions using structured data from verified sources, routing to many tools. It distinguishes itself from web search and siblings by emphasizing structured data with citations.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides specific trigger phrases ('what is', 'look up', 'find') and examples. Tells when to use and implies when not to use (web search).

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), the description adds that the tool extracts answers using only tool results, returns explicit refusal reasons (e.g., not_in_source, tool_error), and costs an extra LLM call. No contradiction with annotations.

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

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

The description is a concise paragraph (about 100 words) that front-loads the purpose, then explains mechanism, return format, and usage guidance. Every sentence adds value without fluff.

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

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

Despite lacking an output schema, the description details the return structure (answer, evidence, confidence, source, etc.) and lists all possible refusal reasons. It also addresses cost and use cases, making it complete for a high-stakes retrieval tool.

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

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

Schema description coverage is 100% with each parameter documented. The description does not add new parameter-level semantics beyond repeating the natural language question expectation. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism of routing to tools and extracting answer only from results. It distinguishes from sibling 'ask_pipeworx' by specifying use cases where the answer must not invent facts.

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 whenever an answer will be quoted, cited, or acted on' and provides specific contexts (financial verdicts, legal claims, etc.). It also states to prefer 'ask_pipeworx for casual lookups' and mentions the extra LLM call cost, giving 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?

Annotations declare safe, idempotent, non-destructive. Description adds extensive behavioral context: resolution contract (confidence levels, alternatives, suggestions), parent event extraction, news fallback details, safety short-circuits, cancellation rule parsing, and wide spread tradeability. Exceeds annotation coverage.

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 verbose and long, covering many edge cases and examples in a single block. While structured with sections (CLASSIFIERS, FAN-OUT, RESPONSE SHAPES, etc.), it lacks conciseness and could be streamlined.

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

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

No output schema exists, so the description must explain return values, which it does in detail covering market fields, analysis, evidence keys, confidence contract, parent event, news fallback, safety mechanisms, and cancellation rules. Covers all important aspects for an agent to use the tool correctly.

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

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

Schema description coverage is 100% with descriptive text for each parameter. The description adds extra examples for 'market', explains 'depth' options, and details 'include_raw' response size implications.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by stating use cases like 'should I bet on X'.

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

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

Provides explicit when-to-use examples: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Also mentions blocking conditions (low-confidence, closed markets, wide spreads) but does not directly contrast with sibling tools like polymarket_edges for edge detection.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds extensive behavioral context: it fetches latest 10-K data from SEC EDGAR/XBRL with off-calendar handling, FAERS data for drugs, sorts by primary metric, and returns paired data with 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 information-dense and front-loaded with example queries, but it is relatively long. However, each sentence adds valuable context (e.g., off-calendar handling, citation URIs). A minor reduction would improve conciseness.

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

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

Given the tool's complexity (two entity types, data sources, sorting) and no output schema, the description sufficiently covers return values ('paired data + pipeworx:// citation URIs'), edge cases (off-calendar fiscal years), and replaces 8–15 sequential lookups. No gaps for agent understanding.

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

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

Schema coverage is 100% (2 parameters fully documented), but the description enriches by explaining that type='company' pulls specific financial metrics and type='drug' pulls adverse-event counts, and that values should be tickers/CIKs or drug names. It also clarifies sorting behavior and output format 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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' specifying the verb 'compare' and the resources (companies or drugs). It distinguishes from sibling tools like entity_profile by emphasizing it is for multi-entity comparisons, replacing sequential single-entity lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It does not mention specific alternative tools (e.g., entity_profile) but implies correct usage through examples.

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, not destructive), the description reveals key behaviors: parallel routing to many sources, return of citations and gaps, time expectation (15-60s), and paid plan requirement for thorough depth. 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 comprehensive but slightly lengthy. However, every part adds necessary information: purpose, process, output, requirements, and usage guidance. It is well-organized with clear sentences. Could be trimmed slightly, but still efficient.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers input requirements, depth options, expected output structure (findings with evidence, confidence, source, etc.), prerequisites (account), and limitations (paid plan for thorough). It also addresses sibling tools and fallbacks.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining depth meanings (quick=3, standard=5, thorough=8) and clarifying that broad/multi-part questions are acceptable for the question parameter. This enriches understanding beyond the schema.

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

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

The description clearly states the tool performs multi-source research by decomposing questions into sub-questions and routing them to many tools in parallel. It specifies the output as a structured findings packet. It also distinguishes itself from the sibling tool ask_pipeworx, which is for 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?

Explicit usage guidance: 'Use for broad or multi-part questions ... use ask_pipeworx for single lookups'. It provides clear when-to-use and when-not-to-use with a named alternative.

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 that it returns top-N tools with full input schemas and curated examples, ready to call directly. No contradiction.

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

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

Description is about 100 words, well-structured with purpose, usage, examples, and return format. Slightly dense but not overly verbose.

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

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

Given no output schema, description fully explains return value (names, descriptions, schemas with examples) and notes no second lookup needed. Covers both parameters (query and limit) clearly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about query being natural language and limit controlling 'top-N', and provides domain examples not in schema, but largely repeats schema info.

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 finds tools by describing the data or task, and lists example domains. However, it does not explicitly differentiate from sibling search tools like 'search_within' or 'suggest_questions', though the 'call this FIRST' instruction provides some distinction.

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: browsing, searching, discovering tools; and instructs to call FIRST when many tools are available. No explicit when-not-to-use, but the prioritization is clear.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral context: fans out across multiple sources, lists each source's contribution, notes USPTO API sunset with soft-fail behavior, and mentions parallel execution.

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

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

The description is well-structured with examples first, followed by detailed explanation. It is somewhat lengthy but every sentence adds value; still, it could be slightly more concise without losing information.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is very complete: it lists all return fields, data ordering, and potential failure modes, making it easy for an 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?

Schema coverage is 100%, so baseline 3. Description adds value by explaining 'type' limitations (only 'company' currently) and 'value' format with examples and clarification that names are not supported.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in one parallel call, with examples. It distinguishes from sibling 'resolve_entity' by noting that names are not supported and that tool should be used first.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view' and gives specific input requirements (ticker or zero-padded CIK) and when to use 'resolve_entity' instead.

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 idempotentHint=true. The description adds context about clearing sensitive data and pairing with other tools, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

The description is very concise, consisting of two sentences with no unnecessary words. It front-loads the core purpose and efficiently provides usage guidance.

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

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

For a simple tool with one parameter, no output schema, and sufficient annotations, the description provides all necessary context: purpose, when to use, and tool relationships.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description adds no additional semantic meaning beyond the schema, so 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 action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by explicitly mentioning them in context.

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

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

The description explicitly provides usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' While it doesn't mention when not to use, the guidance is clear and relevant.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: fetches page, extracts title/description/links, emits standard markdown format, output is a text blob meant for site-root/llms.txt. 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 plus a bullet list of use cases, front-loaded with the main purpose and output. Every sentence is informative and not redundant.

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 output format and intended usage. Tool is simple with two parameters; description covers all necessary aspects for correct invocation.

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

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

Input schema has 100% description coverage for both parameters, so description adds no extra semantics beyond what schema already provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool generates an llms.txt file for any URL, including details on what it extracts and outputs, and distinguishes from siblings by focusing on the specific output format and use cases like auditing competitor AI visibility.

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 use cases (getting site indexed, drafting own project, auditing competitor), providing clear context for when to use. Lacks explicit alternatives or when-not-to-use, but sibling tools like scan_competitor_ai_presence are not mentioned.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds: returns daily high/low temp, precipitation, conditions, sunrise/sunset, default 7 days. 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?

Five sentences with clear structure: purpose, usage guidance, input method, output items, defaults and siblings. 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?

Fully covers purpose, usage, location input, output details, defaults, and sibling differentiation. Output schema exists so return values are already covered.

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

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

Schema coverage is 100% so baseline 3. Description adds minimal beyond schema: mentions city or lat/lon and default 7 days, but no additional parameter-level details.

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

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

States 'Weather forecast 1–16 days ahead for any location worldwide' with clear verb and resource. Explicitly distinguishes from siblings get_weather and get_historical by specifying their use cases.

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

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

Provides explicit guidance: prefer over web search for specific queries, when to use get_weather (current conditions) and get_historical (climate). Includes example query patterns.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description adds value by stating the source (ERA5 reanalysis), authority, and date range (back to 1940). 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 informative paragraph that front-loads purpose and authority. It could be slightly more concise, but it efficiently covers key points without unnecessary repetition.

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

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

Given output schema exists, return values need no explanation. The description covers all necessary context: source, date range, location types, default behavior, and use cases. Parameter descriptions in schema are already complete.

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

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

Schema coverage is 100%, so baselines at 3. The description adds that defaults to last 30 days if no dates given, which is already implied by optional parameters. No additional detail beyond schema for individual parameters.

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

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

The description clearly states it returns authoritative historical daily weather for any location back to 1940, specifying data types (high/low temp, precipitation, conditions). It distinguishes itself from siblings like get_forecast and get_weather by emphasizing 'historical' and 'daily' over future or current weather.

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 use cases: 'weather in X on date Y', climate baselines, comparing years, retrospective context. It also mentions default behavior (last 30 days). While it doesn't explicitly contrast with siblings, the context and sibling list make the distinction clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false, covering safety. The description adds behavioral details: returns temperature (°F), feels-like, humidity %, wind speed/direction, sky conditions, observation timestamp, and 'Live data.' This enriches transparency beyond annotations.

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

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

The description is a compact three sentences: purpose, usage guidance, return fields. It is front-loaded with 'REAL-TIME current weather' and contains no redundant information. 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 simplicity, full schema coverage, and the presence of an output schema, the description covers purpose, usage context, and return value details adequately. No gaps remain for an agent to understand what the tool does and how to invoke it.

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

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

The input schema covers 100% of parameters with descriptions, so the schema already explains each parameter's purpose. The description adds high-level guidance ('Accepts a city name or lat/lon coordinates') but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves 'REAL-TIME current weather for any location worldwide.' It distinguishes from sibling tools like 'get_forecast' by specifying 'current weather' and emphasizing real-time data, making it easy for an agent to select over alternatives.

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

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

The description explicitly advises to 'PREFER OVER WEB SEARCH' for common weather queries and lists typical questions it answers. This provides clear when-to-use guidance and implicitly excludes forecast or historical queries, which are handled by sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds value by listing the specific fields returned (id, type, params, etc.), which provides behavioral context beyond annotations. No contradictions.

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

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

Two sentences, each purposeful. The first states action and output, the second gives 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?

The tool is simple (one optional boolean parameter, no required params). No output schema provided, but the description compensates by listing return fields. The description is complete for the complexity level.

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

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

Schema coverage is 100% (one parameter with a clear description). The tool description does not add additional meaning beyond what the schema already provides for the parameter.

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

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

The description clearly states the verb 'List' and the resource 'subscriptions' with a specific scope ('caller's active subscriptions'). 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?

The description provides explicit guidance on when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly state when not to use it or mention alternatives, but the context of sibling tools implies them.

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

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

Annotations are neutral (not read-only, not destructive, not idempotent). Description adds rate limit (5/identifier/day), free quota, and team's reading frequency. 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?

Front-loaded with purpose, then usage, then constraints. Every sentence provides value. No fluff, efficient and clear.

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

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

Given 3 params (1 enum, 1 nested), no output schema, the description covers all necessary context: feedback types, rate limits, quota, and how to write the message. Complete for a feedback tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds extra meaning by explaining enum values concisely and advising to describe issues in terms of Pipeworx tools/packs, which helps with writing the message.

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

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

The description states it's for sending feedback to the Pipeworx team, specifying types like bug, feature, data_gap, praise. It uses a specific verb+resource and clearly distinguishes from sibling tools that are mainly for data queries.

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: for wrong/stale data, missing features, praise. Also advises against pasting end-user prompts. This clearly guides appropriate usage.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds details: data source (CF analytics-engine), no PII, and caching behavior, which are beyond annotation coverage.

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 concise sentences: first defines output, second lists rationales, third explains aggregation. Front-loaded, no redundancy, every sentence earns its place.

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

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

For a single-parameter, read-only tool with full annotation coverage, the description covers return values, use cases, caching, and data privacy. No gaps for an agent to select and invoke correctly.

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

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

Schema has 100% coverage with a descriptive enum. The description enhances by explaining the semantic difference between short and long windows (hot vs steady-state), adding value beyond the schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a window. It distinctively positions itself as aggregating what other AI agents call on Pipeworx, differentiating from siblings like ask_pipeworx or discover_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?

Three explicit use cases are provided, and window selection guidance is given. Sibling alternatives are not explicitly mentioned, but the context is sufficient for appropriate 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 read-only, open-world, and idempotent. The description adds behavioral details: Jaccard similarity threshold (≥0.30), partition filter (dropping placeholder slugs), fill check against live CLOB depth, and conditions for not trading (realizable_edge_pp ≤ 0). 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 detailed and well-structured but somewhat lengthy. Every sentence adds value, though some redundancy exists (e.g., reiterating modes). Still, the complexity justifies the 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?

Despite no output schema, the description thoroughly explains the response structure (opportunities, partition_check, fill check fields), covers algorithmic details, limitations, and cross-references related tools, making it comprehensive 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%, and the description adds significant meaning beyond schema: explains modes, gives concrete examples of event slugs and topics, and details what happens with each parameter (walks child markets, searches related events).

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, specifying two modes (event and topic). It distinguishes itself from siblings by mentioning polymarket_fill_risk for custom sizing.

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 that one of event or topic is required, recommends which mode to use based on need (specific market vs cross-event scanning), provides example inputs, and mentions an alternative tool for custom sizing (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?

The description heavily enriches the annotations (readOnlyHint, idempotentHint) by detailing caching ('Cached 1h at the KV level'), output structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market details, 24h-move warning), and internal model logic (lognormal barrier, GDELT ratio, partition_overround corrections). 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 verbose and multi-paragraph, but well-organized into sections (segments, knobs, response structure, diagnostics). Given the tool's complexity (9 parameters, 3 model families), the detail is warranted, though it could be more condensed without losing clarity.

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

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

The description covers all aspects: purpose, model internals, all parameters, output structure (including diagnostics for empty results), caching, and edge cases (Fed bets excluded). Since there is no output schema, the detailed return value descriptions compensate fully.

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

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

With 100% schema coverage, the description adds substantial practical context: min_liquidity explanation ('set to 5000 to drop thin-book opportunities'), slippage_pp advice ('Polymarket has zero trading fees... 20-50bp per trade'), and min_partition_leg_kelly rationale ('partition arbs always return kelly_fraction_half=0'). Every parameter is given real-world usage nuance 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 scans Polymarket markets to find mispricings where Pipeworx data disagrees with market price, explicitly targeting 'what should I bet on today'. It details three model segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use this tool (daily betting discovery) and provides parameter guidance (e.g., slippage_pp suggestion '20-50bp per trade', min_liquidity 'set to 5000'). It does not explicitly contrast with alternatives like polymarket_arbitrage, but the detailed model explanations imply use cases.

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

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

Annotations already indicate readOnlyHint and non-destructive. Description adds useful behavioral details: limitations (60-day TTL, decay from daily closes), response structure (tracked, expired, snapshot_dates), and caveats (gaps mean no scan). No contradiction with annotations.

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

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

The description is a single dense paragraph but front-loaded with the purpose and key usage. Every sentence adds value, though structuring could be improved for 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 no output schema and moderate complexity, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and how trends/decay are computed, making it sufficient for correct tool invocation.

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

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

Schema covers both parameters fully (100% coverage). Description restates defaults and acceptable values but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, distinguishing it from sibling tools like polymarket_edges by focusing on time-series and trend analysis.

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

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

It explicitly answers when to use ('how long has this edge existed and is it shrinking?') and explains the difference between fresh and old edges, but does not mention alternatives like polymarket_edges for simpler 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 declare readOnlyHint, idempotentHint, and openWorldHint. Description adds concrete behavioral details: walks the order book ladder, returns specific fill statistics, and highlights basket-mode risks like 'thin_legs[]' and 'forced_directional_risk'. No contradiction with annotations; substantial value added beyond structured fields.

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

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

The description is comprehensive but lengthy. It is front-loaded with the purpose and uses clear sectioning (single-market vs basket). However, the text is dense and could be more concise without losing critical information. Every sentence serves a purpose, but the verbosity slightly reduces 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 no output schema, the description thoroughly covers what the tool returns for both modes, including edge cases like thin legs and directional risk. It explains behavior for both modes, default values, and risk warnings. A user or agent has sufficient information to use the tool correctly without external documentation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description goes further by clarifying side defaults ('auto from partition sum'), size_usd interpretation differences between modes, and the mutual exclusivity of market and event. Adds meaningful usage context beyond the schema.

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

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

Description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth.', a specific verb+resource combo. It explicitly differentiates from siblings by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', making purpose and scope 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?

Provides explicit when-to-use guidance: 'before acting on any polymarket_arbitrage... or any polymarket_edges trade above ~$500'. Explains risks of theoretical overround and partial fills. Does not explicitly state when not to use (e.g., small trades), but the positive use case is well-defined.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds crucial context beyond annotations: explains compatibility_warning with two cases, temporal alignment, skipped cross-type/subtype counters, and that real spreads are rare. This richly describes behavior that annotations alone do not cover.

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

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

Description is verbose (over 200 words) and somewhat stream-of-consciousness. While it front-loads purpose and key facts, it could be more structured with bullet points or sections. Some redundancy exists (e.g., warning repeated). Concise but not optimally structured.

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

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

Given no output schema, description thoroughly explains response fields (leg-by-leg prices, matched spread, top_spreads_pp, safety fields, temporal_alignment, skipped counters). It covers edge cases (compatibility warnings) and failure modes. Missing explicit JSON structure but overall complete for a complex 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 100% of parameters with descriptions. Description adds value by elaborating on the two modes, providing example values, and clarifying override semantics (e.g., explicit parameters override topic-mapped ones). This context aids correct parameter usage beyond schema.

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

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

Description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute spread) and resource (two prediction market venues), and distinguishes from siblings like polymarket_arbitrage by emphasizing cross-venue comparison. No tautology.

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 explains when to use: to find arbitrage or signal between Kalshi and Polymarket. It provides two modes (topic shortcuts and explicit pairs) and warns that pre-mapped topics often yield compatibility warnings, implying when not to rely on them. However, it lacks explicit comparison to sibling tools like polymarket_arbitrage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds scoping by identifier and clarifies behavior for listing keys. No contradictions.

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

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

Two sentences, front-loaded with main action, no wasted words. Efficient and clear.

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

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

For a simple tool with one optional param, good annotations, and no output schema, the description covers scope, usage pattern, and pairing with remember/forget. Complete enough.

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

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

Schema coverage is 100% with a clear description for the key parameter. Description reinforces the same info (omit to list all) but doesn't add new semantic nuance beyond what schema provides.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, using specific verbs and mentioning sibling tools (remember, forget). It distinguishes from alternatives effectively.

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

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

Provides explicit examples of when to use (look up stored context like ticker, address, notes) and mentions omitting key to list all. No explicit when-not-to-use, but guidance is strong.

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

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

Description contradicts annotations: mark_read parameter allows mutation (flagging events as read), while annotations declare readOnlyHint=true. This is a clear contradiction, so score is 1 per rules. Description otherwise adds useful behavior details.

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

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

Concise, four-sentence description. Front-loaded with purpose and key details. 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?

No output schema, but description explains return fields (source, citation_uri, payload) and usage patterns (polling, alternative access). Sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by explaining each parameter's purpose (e.g., mark_read sets read flag for subsequent calls, type filters by subscription type) and mentions response fields, going 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 pulls fired events from the subscription feed, specifying the resource (alerts) and action (returns). It distinguishes itself from sibling tools like list_subscriptions by focusing on fired events rather than subscription management.

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?

Describes when to use the tool for polling and offers an alternative (direct API endpoint). Lacks explicit 'when not to use' but provides sufficient context for typical usage.

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

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

Annotations already indicate safe read (readOnlyHint, idempotentHint, destructiveHint=false). Description adds valuable context: fan-out to multiple sources, fallback logic, and soft-fail for USPTO due to API sunset. No contradiction.

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

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

Description is detailed yet efficient, front-loaded with example queries. Every sentence adds value. Could be slightly more compact, but still well-structured.

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

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

Despite no output schema, the description explains return structure (changes[] grouped by source + total_changes count + citation URIs). All required params are covered, and context is complete 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%, but description adds meaning: relative shorthand for 'since' ('7d', '30d', '3m', '1y') with recommendation for monitoring, and explains 'value' accepts ticker or CIK. Enriches beyond schema.

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

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

The description clearly states it returns a change feed for a company from SEC EDGAR, GDELT/GNews, and USPTO for a given time window. It explicitly differentiates from sibling 'entity_profile' by noting the static profile use case.

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

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

Provides example queries ('What's new with X', 'latest on Y') and explicitly says when to use entity_profile instead. Explains fallback behavior (GDELT→GNews when rate-limited or 5xx) and soft-fail for USPTO.

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 behavioral context beyond annotations: key-value pair scoped by identifier, persistence details (authenticated vs anonymous). 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?

Five sentences with no fluff; front-loaded purpose, each sentence earns its place (usage, storage, lifecycle).

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 2-param tool with no output schema, description covers purpose, usage, behavior, and param context comprehensively.

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 reinforces with examples (e.g., 'subject_property') and context, adding value without redundancy.

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 it saves data for reuse across conversations/sessions, uses a specific verb ('save'), and distinguishes from siblings like 'recall' and 'forget'.

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

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

Provides clear when-to-use scenarios (discover worth-carrying info) and pairs with recall/forget, offering explicit guidance on alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds behavior: cascading internal lookups replacing 2-3 manual steps. No contradictions; supplements annotations well.

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

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

Well-structured with example queries upfront. Every sentence contributes useful information; slightly verbose but justified given tool complexity.

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

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

No output schema, but description fully details return values per type (ticker, CIK, company_name, URI for company; RxCUI, ingredient, brand, URI for drug). 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%. Description adds value beyond schema by explaining auto-disambiguation and accepted input forms (ticker, CIK, name for company; brand/generic for drug).

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 verbs and examples. It distinguishes from siblings like entity_profile and compare_entities by focusing on ID lookup from names.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context. Lacks explicit when-not-to-use and alternative sibling names, but the guidance is strong.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it probes each entity with ai_visibility_check, ranks, and returns ranked list with score, confidence, signal density. No contradictions; adds valuable behavioral context beyond annotations.

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

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

Three sentences front-loaded with main action. Contains some extra usage context and output description. Efficient but could be marginally tighter without losing clarity.

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

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

Given complexity (multiple entities, optional Anthropic API), description explains probe mechanism, ranking, and output fields (score, confidence, signal density). No output schema, so covering return values is good. Adequate 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?

Schema has 100% description coverage. Description adds semantic meaning: entities: first entry is 'subject' for narrative, rest competitors; models: 'workers-ai' free default, 'anthropic' requires _apiKey; context: disambiguates common names. This goes beyond schema descriptions.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side using ai_visibility_check, ranks by score, and surfaces most/least recognized. Verb 'scan' and resource 'competitor AI presence' is specific, and it distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (more general).

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 example of when to use: 'for competitive AI-marketing audits' with concrete question. It implies not for single entity checks (use ai_visibility_check). While it doesn't explicitly state when not to use, context is clear enough for an AI agent to decide.

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

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

Adds significant behavioral context beyond annotations: describes partial failure graceful degradation, bundlephobia first-measurement delay (5-30s), and lists returned fields including 'sources_failed'.

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 block is dense but well-structured: purpose first, then usage guidance, then return details and limitations. Every sentence adds value with no waste.

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

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

Despite no output schema, the description fully covers return values (summary block fields, per-advisory, links, alternatives), error handling, and performance characteristics, making it self-sufficient.

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 value beyond the schema by clarifying that 'version' defaults to latest, accepts scoped packages, and giving usage example ('adding lodash'). Schema coverage is 100% but description enhances 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 a specific verb (composite check) and resource (npm package addition decision), and explicitly scopes to NPM ecosystem in v1, distinguishing it from other tools.

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

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

Provides explicit use cases ('is X safe / popular / small') and mentions when bundlephobia may timeout, but does not name alternative tools for non-npm ecosystems (only implies direct deps.dev 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?

Adds critical details beyond annotations: truncation at 200K chars, embedding model (BGE-base-en), window size (500-char overlapping), cosine similarity, offset return, and flagging of truncated inputs. No contradiction with annotations.

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

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

Three sentences: core purpose, usage context and benefits, technical details. Efficiently front-loaded, no redundant 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?

Despite no output schema, describes return type (passages with character offsets and similarity scores). Covers input constraints, behavior, and interoperable tool (ask_pipeworx_grounded). Fully adequate for agent to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions. The description adds practical usage context (e.g., 'text you already pulled, e.g. a SEC 10-K body') and clarifies query as natural language. Provides moderate added value beyond schema.

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

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

Clearly states verb 'search', resource 'inside a fetched record', and scope 'semantic search'. Differentiates from siblings by mentioning pairing with ask_pipeworx_grounded and contrast with full document fetching.

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 the record is too big to cram into the prompt', explains benefits (saves context, returns offset-verified passages). Mentions pairing with ask_pipeworx_grounded as alternative workflow. No explicit when-not, but strong contextual guidance.

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

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

The description adds significant behavioral context beyond annotations: creation (not read-only), idempotent (implied by 'proactive monitoring'), non-destructive. It details auth requirements, delivery limits (10/day SMS), webhook signing, and auto-disable. 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 informative and well-structured, starting with purpose and requirements, then types, then delivery. It is slightly long but each sentence adds value; no redundancy.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers types, filters, delivery details, constraints, and return value. Missing output schema details are partially compensated by the stated return of subscription id.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining type-specific filter semantics with concrete examples (e.g., 'items:["5.02"] = officer change') and delivery field constraints (verified phone, cap).

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 ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides explicit requirements ('Requires a Pipeworx OAuth account'), supported types with examples, and delivery channel options. It lacks explicit 'when not to use' but gives sufficient context for usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description is not required to repeat these. It adds valuable context: that the tool returns example questions drawn from 'the live catalog of thousands of tools' and includes 'exact tool + argument shape'. This goes beyond the annotations and helps the agent understand the dynamic, non-destructive nature.

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

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

The description is front-loaded with alias questions that quickly convey purpose. It is somewhat verbose but each sentence adds value: aliases, output description, parameter guidance, and usage directive. The structure is logical and easy to parse.

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

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

Despite lacking an output schema, the description fully explains the return value (category-bucketed example questions with tool+argument shapes). It covers purpose, usage context, parameter behavior, and connects to sibling meta-tools. For a first-contact tool, this is complete and informative.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning by listing concrete topic examples ('finance | pharma | economics ...') and clarifying that omitting the parameter yields a cross-category spread. This enriches the schema's description and helps the agent choose appropriate values.

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

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

The description clearly states the tool's purpose as the onboarding entry point for an agent to discover what Pipeworx can do. It lists multiple natural language aliases (e.g., 'What can I ask Pipeworx?', 'give me ideas') and explicitly describes the output: category-bucketed example questions with tool+argument shapes. This distinctively differentiates it from sibling tools like 'discover_tools' and '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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools'. Provides context for the optional 'topic' parameter ('omit for cross-category spread'). While it doesn't explicitly state when not to use it, the guidance is clear and actionable for an AI agent.

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

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

Adds value beyond annotations: ownership enforcement, deactivation vs deletion, historical data preservation. No contradiction with annotations (idempotentHint true matches 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, front-loaded with purpose, no unnecessary words.

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

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

Fully describes behavior, constraints, and side effects for a simple unsubscribe with one parameter and no output schema.

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

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

Schema already fully describes the single parameter (id, uuid from subscribe). Description adds minimal extra meaning beyond confirming source.

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 'cancel' and resource 'subscription by id'. Distinguishes from sibling '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 ('you can only cancel your own subscriptions') and explains that the row is deactivated not deleted, preserving history.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by detailing return verdict types (confirmed, refuted, etc.), extracted structured form, actual value with citation, and percent delta. Also notes version scope (v1 supports company-financial). 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 detailed but well-structured: trigger phrases, scope, replacement benefit, and output format all present. Every sentence adds value; slightly long but appropriate for 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?

No output schema exists, so description must explain return values. It covers verdict types, extracted form, actual value with citation, and delta. Also explains it replaces multiple calls and states scope (v1). Fully adequate for agent decision.

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

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

Schema has 100% coverage with a description, but the tool description adds crucial context: parameter is a natural-language claim, and provides specific examples. This helps the agent formulate correct inputs beyond schema type info.

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

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

Clearly states the tool verifies natural-language factual claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. Trigger phrases and example claims make purpose unmistakable, and it distinguishes itself from sibling tools by replacing 4-6 sequential calls.

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

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

Explicitly says to use whenever factual correctness check is needed, and provides claim types (company-financial). Lacks explicit when-not-to-use or alternatives, but context implies scope boundaries.

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