Openweather

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

Annotations already provide readOnly and idempotent hints. The description adds detail on return values (AQI, pollutants) but no additional behavioral context like rate limits or data source.

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 with a concrete example. No fluff, front-loaded purpose, 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?

Simple tool with good schema and annotations. Description covers core functionality and return types. Lacks mention of geographic scope but sufficient for 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 has 100% coverage with descriptions. The description adds an example and clarifies the optional _apiKey's purpose beyond the schema, adding value.

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

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

The description clearly states it gets current air quality for coordinates, listing AQI and pollutants. While it doesn't explicitly differentiate from siblings like current_weather, the purpose is distinct.

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

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

The description implies use for air quality queries but provides no guidance on when to avoid or alternatives. No explicit exclusions or context for tool selection.

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

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

Discloses that it uses a free default model (Workers AI Llama-3.3-70b) and optionally probes Anthropic with user's own API key, including cost implication. Annotations already indicate non-destructive, read-only, idempotent behavior; description adds details on external API calls and model selection, exceeding 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?

Very concise: two sentences, no wasted words. Front-loaded with main action and key details. Structure is clear and efficient.

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

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

Complete for the tool's complexity: explains inputs, behavior (default vs optional model), output format (per-model and combined view), and use cases. No output schema but description sufficiently covers return structure.

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 meaningful context for each parameter: examples for entity, lists supported models for models, explains _apiKey is optional for Anthropic, and context helps disambiguate. Adds value beyond schema.

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

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

Clearly states it probes LLMs to score visibility for a given entity, with specific use cases (AI-marketing audits, pre-launch brand checks). Distinguishes from siblings by focusing on multi-model probing and scoring, unlike similar tools like scan_competitor_ai_presence.

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

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

Explicitly mentions when to use: AI-marketing audits, pre-launch checks, competitive monitoring. Implies context but does not explicitly state when not to use or list alternatives, leaving some ambiguity.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds that it routes to 3,744 tools, fills arguments, and returns structured answers with citation URIs, providing 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?

The description is front-loaded with key guidance and is informative without unnecessary words. It could be slightly shorter, but every sentence adds value.

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

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

Given the tool's complexity and the annotations covering safety and behavior, the description is complete enough. It covers purpose, usage guidance, and output nature (structured citations). No output schema exists, but the description addresses return values adequately.

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

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

Schema coverage is 100%, with all parameters documented. The description mentions the question parameter and its aliases, but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states that the tool routes questions to a large set of authoritative data sources, distinguishing it from web search. It lists numerous domains and provides a clear purpose: answering factual questions with structured data and 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?

The description explicitly states 'PREFER OVER WEB SEARCH' and provides specific use cases and examples. However, it does not differentiate from sibling tools like 'ask_pipeworx_grounded', which could be a closer 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?

Beyond annotations (readOnly, idempotent, not destructive), describes extra LLM call, explicit refusal reasons, and return structure. 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?

Concise 5-6 sentences, front-loaded with key benefit and usage. Every sentence adds value; no redundancy.

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

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

Covers behavior, output format, refusal reasons, and cost. Complete for a high-stakes answer tool with complex routing.

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 full descriptions. Description adds only that question accepts multiple aliases and natural language, which is helpful but not essential 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results and returns structured response with refusal reasons. Distinguishes from sibling 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 specifies when to use (quoted/cited answers, high-stakes domains) and when to prefer ask_pipeworx (casual lookups). Notes extra LLM cost.

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

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

Annotations already indicate safe/idempotent read behavior. Description adds extensive behavioral detail: fan-out logic per category, response shapes, resolver contract (including match confidence, alternatives, suggestions), parent event extraction, news fallback handling, safety short-circuits for low-confidence and closed markets, wide spread handling, and resolution-rule risk. Goes far 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 very long (multiple paragraphs) and includes extensive detail. While well-structured and front-loaded with core purpose, it is not concise. Agents may need to parse significant text to find key information.

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

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

Covers all critical aspects: input formats, classifiers, fan-out examples, response structure, resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution rules. Completeness is high despite 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 description coverage is 100%, so baseline is 3. Description adds extra meaning: explains market input types with examples, defines quick vs thorough depth, and explains when to use include_raw=true. Provides context that schema alone lacks.

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 researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out, and returning an evidence packet. Provides examples of inputs and use cases. Distinguishes from sibling tools by being the comprehensive single-bet research tool.

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

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

Explicitly says 'Use for “should I bet on X”, “what does the data say about Y”, or “is there edge in Z”.' Provides clear use cases but does not explicitly contrast with 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?

The description details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with URIs. This goes well beyond annotations (readOnly, openWorld, idempotent) with specific behavioral and output characteristics.

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

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

The description is dense but every sentence adds value, starting with example queries then core purpose. It could be slightly more structured (e.g., separate sections), but overall it's efficient and front-loaded.

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

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

Covers data sources, sorting, return format, and use case. Lacks details on error handling or pagination, but for a comparison tool of this scope, it is sufficiently complete. No output schema exists, so description compensates well.

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

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

Schema descriptions are minimal; the tool description massively enriches them, explaining what data each type pulls and providing examples for values. It also clarifies the parallel nature and result sorting, which are not in 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 side-by-side comparisons of 2–5 companies or drugs in one parallel call, with examples like 'X vs Y' and 'compare entities'. It distinguishes from siblings by noting it replaces sequential single-pack lookups.

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

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

Explicit guidance to prefer this tool over sequential lookups ('ALWAYS PREFER...'), along with concrete query examples and mention that it replaces 8–15 individual calls. Provides clear context for when to use.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by listing the specific data returned (temperature, humidity, etc.) and includes an example, which helps the agent understand behavior without contradicting annotations.

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

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

Two short sentences, no fluff. The example is front-loaded and efficient. Every word contributes to understanding the tool's purpose.

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

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

For a simple current weather tool, the description covers the essential information: what is returned, how to specify location and units, and an example. No output schema exists, but the field list compensates. All parameters are explained in the schema, and the tool's behavior is fully described.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description reinforces the meaning by showing an example usage with 'city' and 'units', but does not add new semantic information beyond what the schema provides.

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

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

Description clearly states 'Get the current weather' with specific verb and resource, lists the fields returned (temperature, feels like, conditions, etc.), and implicitly distinguishes from sibling tools like 'forecast' and 'air_quality' by focusing on current conditions.

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

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

The description mentions using city or coordinates and provides an example, which gives clear context for usage. However, it does not explicitly state when not to use or directly compare with alternatives, though sibling tools like 'forecast' are naturally distinct.

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

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

Beyond annotations (readOnlyHint, etc.), the description details the decomposition process, parallel routing to 3,744 tools, structured output with evidence/confidence/source/gaps, and time expectation (15-60s). 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?

Well-structured with front-loaded purpose, then process, then usage guidance, then requirements. Every sentence adds value, though slightly verbose in listing tool count and sources. Could be slightly more concise 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?

No output schema, but description adequately explains return format: structured findings packet with evidence, confidence, source, citations, and gaps. Mentions time expectation. Lacks minor details on confidence interpretation but sufficient for the complexity.

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

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

Schema coverage is 100% with descriptions. The tool description adds semantics: maps depth values to facet counts (quick=3, etc.) and notes plan requirement for 'thorough'. Adds that 'question' can be broad/multi-part. Baseline 3 raised due to added context.

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

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

The description explicitly states the tool performs 'grounded multi-source research in one call' by decomposing questions into sub-questions and routing to parallel sources. It distinguishes from sibling 'ask_pipeworx', which is described as a single lookup.

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: 'Use for broad or multi-part questions' and when not: 'use ask_pipeworx for single lookups'. Also notes prerequisites (Pipeworx account) and plan limitations for 'thorough' depth.

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

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

Annotations indicate read-only and idempotent, and the description adds that it returns top-N tools with full schemas and examples, ready to call directly, which is consistent and adds value.

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

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

The description is a single paragraph that fronts the purpose, but it is slightly lengthy. Every sentence is value-adding.

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

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

Given no output schema, the description explains what is returned (top-N tools with names, descriptions, schemas) sufficiently for an agent to understand the result.

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%. The description explains the query parameter accepts multiple aliases and provides examples, adding meaning beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many domains, distinguishing this meta-tool from the many specific sibling tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use and when-not guidance.

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

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

Beyond annotations (readOnlyHint, etc.), description details exact data sources and fields: SEC EDGAR, XBRL, USPTO (with sunset warning), GDELT→GNews fallback, GLEIF. It also mentions soft-fail for patents, which is valuable behavioral context.

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

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

While information-dense and front-loaded with examples, the description is slightly lengthy. However, every sentence adds value without repetition, so it remains efficient.

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

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

Covers all major data sources and fields despite no output schema. Includes notes on fallback behavior and limitations (patents sunset). Minor gaps like handling of missing entities are not addressed, but openWorldHint partially covers this.

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

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

Both parameters are fully described in schema (100% coverage). The description adds examples ('AAPL', '0000320193'), clarifies type is only 'company', and reinforces that names are not supported, providing meaning beyond schema alone.

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

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

The description provides numerous example queries ('Tell me about X', 'research Acme') and states it returns a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools like resolve_entity by specifying input requirements.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity if only a name is available, providing clear usage boundaries.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds value by disclosing the interval structure, data fields (temperature, conditions, wind, precipitation), and the optional API key for rate limits. 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 and an example form a concise, front-loaded structure. 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?

With no output schema, the description adequately explains return data (temperature, conditions, wind, precipitation) and intervals. It covers parameter combinations (city vs lat/lon) but could mention that lat/lon takes precedence or that timestamps are included. Overall 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?

Schema coverage is 100% with parameter descriptions. The description adds an example and default count behavior but does not significantly expand on the schema. Baseline of 3 is appropriate given high coverage.

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

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

The description clearly states it returns a multi-step weather forecast at 3-hour intervals for a city or coordinates, specifying the data fields. It distinguishes from siblings like 'current_weather' and 'air_quality' by its multi-step nature.

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

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

The description implies usage via example and schema, but does not explicitly state when to use this tool vs alternatives like 'current_weather' or 'air_quality'. There are no when-not or alternative recommendations, leaving the agent to infer based on naming.

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 like 'clear sensitive data' and 'stale context', which provides additional behavioral insight beyond annotations.

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

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

Two sentences, no fluff. Efficiently conveys purpose and usage. Could be slightly more structured, but very concise.

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

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

For a simple delete tool with one required parameter and no output schema, the description covers purpose, usage, and behavioral context sufficiently. No major gaps.

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

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

Schema coverage is 100% and the description only mentions 'by key', which aligns with the schema. No extra semantics added beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, specifying the verb 'delete', resource 'previously stored memory', and identifier 'key'. It also distinguishes from siblings by explicitly mentioning 'remember' and 'recall'.

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

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

Provides explicit guidance on when to use: when context is stale, task done, or clearing sensitive data. It mentions pairing with 'remember' and 'recall', but does not list exclusions or directly contrast with 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions. Provides behavioral context beyond annotations, e.g., 'ready to drop at site-root/llms.txt'.

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 paragraph of 4 sentences. Front-loaded with main purpose. Every sentence adds value: defines output, mentions AI crawlers, specifies use cases. No repetition or fluff.

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

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

For a simple tool with 2 params and no output schema, the description fully explains what it does, what it outputs, and when to use. Annotations cover safety. No missing details.

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 and schema both describe 'url' as the site to summarize and 'max_links' as max entries. No additional semantic value beyond the schema's descriptions.

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

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

Clearly states the tool generates an llms.txt file for AI crawlers, with specific verb 'generate' and resource 'llms.txt file'. Distinguishes from siblings by focusing on AI indexing, while siblings like 'search_within' or 'validate_claim' have different purposes.

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

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

Lists three explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. Provides context but does not explicitly state when not to use or list alternatives, though siblings don't overlap directly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that the tool returns coordinates, which is helpful, but does not disclose additional behavioral traits like rate limits or error handling. With annotations covering the key aspects, a 3 is appropriate.

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

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

The description is two sentences and an example. It is front-loaded with the purpose and efficiently provides a use case. No wasted words.

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

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

Given the tool's simplicity (3 params, no output schema, good annotations), the description covers the necessary information: purpose, when to use, an example, and key parameter explanation. It doesn't explain the return format in detail, but the purpose implies a lat/lon structure. Slightly above average.

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

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

Schema coverage is 100%, so the schema already documents all parameters and their descriptions. The description adds an example with query and limit but does not introduce new semantics beyond what's in the schema. Baseline 3 is correct.

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 a place name to geographic coordinates. It also explicitly links to a sibling tool (air_quality), distinguishing its purpose and providing 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 provides explicit guidance on when to use this tool: 'Useful before calling air_quality, which needs lat/lon.' It could be improved by mentioning when not to use (e.g., if coordinates already known), but the given context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds context on return fields (id, type, params, timestamps, fire_count) and that it returns only the caller's subscriptions. This is consistent and adds value beyond annotations.

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

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

The description is two short sentences. The first sentence states the purpose and return fields; the second provides usage guidance. No wasted words, well-structured.

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

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

Given the simple schema (1 optional boolean, no output schema), the description covers purpose, return fields, and usage context. It lacks any mention of pagination or limits but is otherwise complete for this tool.

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

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

Schema coverage is 100% with the single parameter 'include_inactive' having a clear description. The tool description does not add extra meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, a specific verb-resource pair. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe'. The return fields are also listed, enhancing clarity.

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

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

The description explicitly suggests use cases: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for when to use it, though it could be stronger on when not to or specific alternatives.

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

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

Annotations indicate the tool is not read-only, not destructive, etc., and the description adds important behavioral details: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. No annotation contradiction, but could mention return value.

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?

Every sentence adds value: purpose, use cases, constraints, and behavioral notes. It is front-loaded and appropriately sized for the tool's complexity.

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

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

Despite having nested objects and no output schema, the description covers purpose, usage, rate limits, and message guidelines. It could mention expected acknowledgment, but overall 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%, but the description adds value by explaining each enum option for 'type' and providing usage context for 'message' and 'context'. It also clarifies that context is optional and which fields to include.

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 ('Tell') and resource ('Pipeworx team'), clearly stating the tool's purpose: submitting feedback about bugs, missing features, or praise. It distinguishes well from sibling tools which are data retrieval or analysis tools.

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

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

The description explicitly enumerates when to use each feedback type (bug, feature, data_gap, praise) and includes a clear 'don't' instruction: 'don't paste the end-user's prompt'. It also mentions rate limits and quota-free usage, providing comprehensive guidance.

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

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

Annotations already provide readOnly, openWorld, idempotent, destructive hints. Description adds valuable context: data source (CF analytics-engine), no PII, caching window (5min-1h). 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?

Well-structured with clear sections: result description, use cases, data source. Slightly verbose but earned, could be tightened slightly.

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

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

Given 1 optional parameter, no output schema, and rich annotations, the description comprehensively covers purpose, parameters, use cases, data provenance, caching, and privacy.

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 (1 parameter with enum). Description adds semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing agent 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?

Description clearly states what the tool returns: top tools, packs, and total call volume, with specific verb 'Returns'. Distinguishes from siblings like discover_tools by focusing on aggregate trending data.

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

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

Explicitly lists three use cases (discovering hot data, confirming canonical tool, aligning with agent needs). Does not explicitly mention when not to use or alternatives, but the context is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond by detailing the algorithms (monotonicity checks, partition-sum, Jaccard similarity threshold, placeholder filtering), the fill check mechanism, and edge cases such as skipped_low_similarity. It also explains when signals are actionable, providing comprehensive behavioral context.

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

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

The description is relatively long but well-structured with clear sections for requirements, modes, algorithmic details, response format, and fill check. Every sentence adds necessary detail for a complex tool. A slight reduction in verbosity (e.g., merging redundant explanations) could improve conciseness, but the current structure is functional.

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

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

Given the tool's complexity (two modes, multiple algorithmic checks, fill check), the description covers all key aspects: input requirements, mode selection, algorithmic steps, response structure (opportunities array, partition_check, fill check results), and actionable warnings (realizable_edge_pp ≤ 0). No output schema exists, so the description fully compensates by detailing return values and interpretations.

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

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

Schema descriptions for `event` and `topic` are already clear (single-event vs cross-event mode). The description adds value by specifying that `event` accepts slugs or full URLs, and that `topic` is a seed question. It also explains the behavioral implications of each mode, enriching the parameter semantics beyond the schema alone.

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

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

The description specifies that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes between single-event and cross-event modes, and references specific technical concepts. The sibling tools list includes other Polymarket utilities like polymarket_edges, making the unique purpose evident.

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

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

The description explicitly states that one of `event` or `topic` must be provided, and recommends which mode to use for specific scenarios (event for a specific market, topic for cross-event scanning). It also provides guidance on when not to trade. However, it does not explicitly contrast this tool with other Polymarket siblings, which would strengthen the guidelines.

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 convey read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: caching (1h at KV level), model families and their methodologies, diagnostics for empty segments, and warning mechanisms (24h-move). This goes beyond annotations to explain how the tool works and what to expect.

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

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

The description is lengthy but well-structured with clear segments for model families and knobs. Every sentence adds unique information without repetition. It could be slightly more concise, but given the complexity (9 params, 3 segments), the length is justified and front-loaded with essential purpose.

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

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

Despite no output schema, the description fully outlines the response structure (by_segment, fed_candidates, diagnostics) and explains caching and filtering logic. All 9 parameters are addressed with practical usage advice. The tool's complexity is well-covered for agent decision-making.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds value by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp) and their practical effects, and clarifies edge cases like min_kelly vs min_partition_leg_kelly. This enriches the semantics beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific actions ('scan', 'return opportunities') and resources ('Polymarket markets', 'Pipeworx data'), and distinguishes itself from siblings by targeting discovery without paging, making it unlikely to be confused.

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

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

The description provides clear context for use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies discovery and opportunity identification, though it does not explicitly exclude other tools or name alternatives. It also gives guidance on knob usage but lacks direct comparison with 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?

The description adds significant behavioral context beyond the annotations: explains the response structure (tracked, expired, snapshot_dates), computed fields (trend, decay_pp_per_day), and limits (TTL, gaps). Annotations already indicate read-only, idempotent safe operations, and the description reinforces this with detailed non-destructive behavior.

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

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

The description is well-organized with a clear purpose first, then detailed response fields, then limits. It is slightly verbose but every sentence adds value. Some restructuring could improve readability, but it is effective.

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

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

Given the tool's complexity (time series, multiple computed fields, no output schema), the description thoroughly explains all output components (tracked, expired, snapshot_dates) and edge cases (gaps, TTL, computed trends). It leaves no major gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% with descriptions for both 'days' and 'window'. The description adds default values, enumeration examples, and business meaning (lookback, snapshot family), improving clarity beyond the schema alone.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from snapshots, answering a specific question about edge longevity. It uses specific verbs and resources, distinguishing it from sibling tools like polymarket_edges.

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

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

The description gives a clear use case (comparing fresh vs. old edges) and context for when the tool is valuable. However, it does not explicitly state when not to use it or name alternative tools for exclusion, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it 'walks the ladder', returns fill details and a 'verdict', and warns that partial basket fills convert arb into an unhedged directional position. 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?

Well-organized with clear sections (SINGLE-MARKET, BASKET) and bullet-like lists. Though lengthy, each sentence adds value. Could be slightly more terse but remains highly informative.

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, yet description comprehensively lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict for single; theoretical_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk for basket). Also covers edge cases like thin books and partial fill risks.

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

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

Input schema has 100% coverage, but description adds significant context: explains size_usd in basket mode as 'settlement notional — shares per leg', side logic for basket (auto based on partition sum), and details return fields for both modes. 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 states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', clearly distinguishing single-market and basket modes. It differentiates from siblings like polymarket_arbitrage (which likely executes trades) by focusing on pre-trade risk assessment.

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

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

Explicitly instructs: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why (theoretical overround not capturable, partial baskets create unhedged positions) and contrasts single-market vs basket modes.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds detailed behavioral context: two operational modes, response fields (matched spread, top_spreads_pp), safety fields (compatibility_warning with two cases, temporal_alignment, skipped_cross counters), and warns that real spreads are rare. No contradiction with annotations.

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

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

The description is comprehensive but verbose at over 300 words. It is well-structured with clear sections (modes, response, safety fields), but could be more concise for quick AI parsing. The front-loading is moderate; key usage guidance appears early.

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

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

Given no output schema, the description fully explains the response structure: leg prices, matched spread, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases (non-equivalent bet shapes, temporal misalignment) and provides instructions for interpretation. Complete for a moderately 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?

The schema already covers all three parameters with descriptions. The description adds value by explaining the two modes (topic vs explicit), listing all topic values, and providing examples. It effectively enhances the schema without repeating it.

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

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

The description clearly identifies the tool as computing the cross-venue spread between Kalshi and Polymarket for identical outcomes. It distinguishes two modes (topic shortcuts and explicit tickers) and differentiates from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use each mode and warns that pre-mapped topics often yield compatibility warnings, clarifying that 'pre-mapped ≠ tradeable'. It explains interpretation of warning fields but does not explicitly compare with alternative tools like 'bet_research' for single-venue analysis.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint. Description adds scope (per identifier) and behavior when key is omitted (lists all keys), providing useful context beyond annotations. No contradiction.

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

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

Three sentences, each serves a purpose: core function, use-case examples, and scope/pairing. No extraneous words, highly 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?

Covers key aspects: function, usage, scope, pairing. Lacks details on output format (e.g., whether list returns keys or values), but given simplicity, this is adequate. No output schema, so description carries the burden.

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 already describes the key parameter. The description adds context: omitting key lists all keys, and explains the purpose of the stored values. This adds 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 dual function: retrieve a specific value saved via remember, or list all saved keys. It identifies the resource (previously saved values) and distinguishes from siblings (remember saves, forget deletes).

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

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

Explicitly tells when to use ('look up context the agent stored earlier') with concrete examples (ticker, address, research notes). Also explains scoping to identifier and pairs with remember/forget, guiding tool selection.

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=false. Description adds value by explaining feed persistence, mark_read effect on subsequent calls, and polling suitability.

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

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

Single paragraph, front-loaded with purpose, then return details, filter options, behavioral note, and external URL. Every sentence adds value, 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, description covers return fields (source, citation_uri, raw payload), all parameters, and usage context (polling, alternative API). Complete for a read-only tool.

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

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

Schema coverage is 100%. Description adds concrete examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains the effect of mark_read, going beyond the schema.

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

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

Clearly states the tool pulls fired events from a subscription feed, with specific return fields and filtering options. Distinguished from sibling tools like 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?

States polling works fine and provides an alternative HTTP endpoint for scripts/dashboards. Does not explicitly compare to sibling tools but gives clear context for when to use.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the fan-out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), fallback behavior, USPTO soft-fail, and output structure (grouped changes, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is concise (around 100 words) and well-structured: starts with usage examples, then explains the parallel call logic, sources, parameter details, output, and finally a sibling comparison. Every sentence is informative and no filler.

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

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

Given the complexity (multiple sources, fallback, relative dates) and lack of output schema, the description is remarkably complete. It covers input formats, source behavior, output structure, and when to use an alternative. The agent has sufficient information to invoke the tool correctly.

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

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

The input schema already has clear descriptions, but the description adds valuable details: relative shorthand formats ('7d', '30d', '3m', '1y'), recommendation for typical monitoring ('30d' or '1m'), and clarification that value accepts ticker or zero-padded CIK. This enriches the schema further.

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: returning a change feed for a company in a recent time window. It provides specific example queries ('What's new with X', 'latest on Y', etc.) and distinguishes itself from the sibling tool entity_profile, which is for static profiles.

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

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

The description explicitly indicates when to use this tool (for updates, recent news, changes) and offers a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains the tool's scope with example 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?

Disclosure goes beyond annotations: persistence is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations already indicate idempotent and non-destructive, but description adds crucial scoping and retention 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?

Four sentences, each adding value: purpose, use case, scoping/retention, sibling hints. No fluff, front-loaded with main action.

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 two parameters and no output schema, the description explains persistence, scoping, and usage context fully. Sibling pairing is addressed.

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

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

Schema coverage is 100% with clear descriptions for 'key' and 'value'. The description repeats the key-value nature but does not add new syntactic or formatting constraints 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 verb ('save') and resource ('data the agent will need to reuse later') with specific examples (e.g., ticker, address, preference). It distinguishes itself from sibling tools 'recall' and 'forget' by mentioning them as pairs.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and provides alternatives ('recall' for retrieval, 'forget' for deletion). Clear 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 indicate readOnlyHint, idempotentHint, and non-destructiveHint. The description adds useful behavioral details: internal cascade through several endpoints and that it replaces manual lookups. It also describes return format per type, which goes beyond annotation data. No contradictions with annotations.

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

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

The description is well-structured, starting with example queries, then a clear verb-resource statement, usage guidance, detailed type sections, and an efficiency note. Each sentence adds value, and the overall length is appropriate for the tool's complexity. A minor improvement could be slightly more compact phrasing.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description provides comprehensive guidance: purpose, when to use, detailed return information per type, and internal behavior. It fully covers what an agent needs to correctly select and invoke this tool, especially with the sibling context provided.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by explaining auto-disambiguation for company type and the specific return fields for each type (e.g., 'company' returns ticker, CIK, company_name, citation URI). This adds practical insight beyond the schema's concise descriptions.

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

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

The description clearly states that the tool resolves user-spoken names to canonical/official identifiers, with specific examples like 'What's the ticker for...' and supported types 'company' and 'drug'. It distinguishes itself by advising 'Use FIRST whenever you have a name but need an ID', setting it apart from sibling tools that likely take IDs as input.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context for when to use this tool. It mentions that it replaces 2-3 manual lookups, implying efficiency. However, it doesn't explicitly state when not to use it or name specific alternatives beyond the general sibling list.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details such as probing each entity, ranking by score, and returning a ranked list with score, confidence, and signal density. No contradiction with annotations.

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

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

The description is concise with no wasted words. It front-loads the core action and purpose, then provides context and output details in a compact paragraph.

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 return values (ranked list with score, confidence, signal density). It covers the process, parameters, and use case adequately for an AI 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 description coverage is 100% with all parameters having descriptions. The description adds value by noting that the first entry in 'entities' is treated as the subject for narrative, which is not in the schema. This enhances understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each using ai_visibility_check, ranks by score, and identifies most/least recognized. It provides a specific use case example ('does Claude know about us as well as our competitors?') and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly states the tool is useful for competitive AI-marketing audits and gives an example question. While it does not explicitly state when not to use, the context is clear enough for an AI agent to infer appropriate usage scenarios.

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

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

Annotations already indicate readOnly+idempotent+non-destructive; description adds significant behavioral context: composite behavior across deps.dev and bundlephobia, partial failures listed in 'sources_failed', and returns summary block with details. 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 thorough but not overly long; it front-loads the core purpose and then provides necessary details. While every sentence earns its place, it could be slightly more concise. Still, it's well-structured and readable.

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 sources, partial failures, latency), the description is complete. It explains output structure (summary block, per-advisory detail, links, alternatives), ecosystem scope, and graceful degradation. No output schema exists, so the description adequately covers return values.

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

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

Schema coverage is 100% with good descriptions. The description adds extra meaning: scoped packages (e.g. '@types/node') are accepted, and version defaults to latest. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check in one call, covering license, advisories, bundle size, and more. It distinguishes from siblings as no other sibling tool performs this specific npm dependency assessment.

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

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

Explicitly provides usage guidance: 'Use whenever an agent asks "is X safe / popular / small"'. It also specifies limitations: NPM ecosystem only in v1, and warns about bundlephobia latency (5-30s) with graceful degradation. This helps the agent decide when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., but description adds rich behavioral details: BGE-base-en embeddings, cosine, 500-char windows, 200K char cap with truncation flag. No contradiction.

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

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

Single paragraph efficiently packs all key information without redundancy. Every sentence earns its place—purpose, examples, when-to-use, technical details, and pairing hint.

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 specifies return values (passages, offsets, similarity scores) and constraints (cap, truncation). No gaps given the tool's complexity and sibling context.

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

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

Schema coverage is 100% with solid descriptions, but description adds contextual examples (e.g., SEC 10-K for text, query examples like 'supply-chain risk') that enhance understanding 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 it performs semantic search inside a record, with specific examples (SEC 10-K, article) and distinguishes from sibling ask_pipeworx_grounded by indicating pairing and 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?

Explicitly says to use when record is too large for prompt, and pairs with ask_pipeworx_grounded. Lacks explicit when-not cases, but context is clear enough from sibling list.

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

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

Annotations include readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: subscription creation, OAuth requirement, delivery channel constraints (e.g., 10/day SMS cap, phone verification), and webhook signing. No contradictions with annotations.

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

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

The description is relatively long but well-structured with clear paragraphs and examples. It is front-loaded with the main purpose and every sentence adds value. Minor reduction possible in the delivery section, but overall efficient for the complexity.

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

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

Despite no output schema, the description covers return value (subscription id), all subscription types with parameters, delivery channels and their constraints, and prerequisites (OAuth account, phone verification). It is complete for a tool with this complexity.

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

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

Schema coverage is 100%, but the description enriches parameter understanding with concrete examples for each type (e.g., sec_8k with items, polymarket_edge with topic), and detailed delivery sub-schema explanations (email, sms, webhook). This adds significant meaning beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create), resource (subscription), and return value, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 extensive guidance: requires a Pipeworx OAuth account, lists supported types with examples, and explains delivery channels. While it doesn't explicitly state when not to use this tool compared to alternatives, the context is rich enough for an agent to make informed decisions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context by explaining the return format (category-bucketed example questions with tool+argument shapes) and the purpose of the tool. No contradictions with annotations.

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

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

The description is well-structured: starts with trigger phrases, states purpose, describes return format, and gives usage instructions. Every sentence adds value, though it is slightly verbose. Could be tightened but remains 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 parameter and no output schema, the description fully covers what the tool does, when to use it, and what it returns. It also lists categories and explains the tool's role relative to siblings, providing complete context 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% (single optional topic parameter). The description adds examples ('finance', 'pharma', 'betting') and explains the behavior when omitted (full spread). This goes beyond the schema description, which only lists categories.

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 suggesting questions about Pipeworx, with specific verbs like 'returns' and 'use this first'. It distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on generating example questions rather than answering or discovering tools.

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

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

Explicitly states when to use: 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. It also explains the effect of the topic parameter and provides examples, offering clear 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 provide readOnlyHint:false, destructiveHint:false, idempotentHint:true. The description adds valuable behavioral details: ownership enforcement and that rows are deactivated (not deleted) so historical events remain available via recent_alerts. 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?

Two sentences, no fluff, front-loaded with action. Every sentence adds value: action, ownership rule, deactivation behavior.

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

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

Given simple tool (1 param, no output schema) and good annotations, the description is complete enough. It explains effect and relationship with recent_alerts. Could optionally mention response format.

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 description 'Subscription id (uuid) returned by subscribe.' The description does not add new parameter info beyond reinforcing the id source. 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 action: cancel a subscription by id, with specific verb 'Cancel' and resource 'subscription'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear context: ownership enforcement (only your own subscriptions) and explains the effect (deactivation, not deletion). It implies when to use but does not explicitly state when not to use or mention 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 provide readOnlyHint, idempotentHint, etc. Description adds context about data sources (SEC EDGAR+XBRL), return structure (verdict, actual value, citation), and version (v1), 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?

Description is front-loaded with examples and usage intent. Somewhat lengthy but every sentence adds value. Could be slightly more concise but not wasteful.

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

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

No output schema, but description details return structure (verdict, actual value, citation, percent delta). Low parameter count. Good coverage of what the tool returns and how it works.

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

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

Only one parameter with good schema description (100% coverage). Description adds examples but does not significantly extend beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is for natural-language claim verification against authoritative sources, with example queries and specific domain (company-financial claims). It distinguishes from siblings like prediction market tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies domain. Could add explicit when-not-to-use, but overall clear.

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