Noaa Swpc

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds behavioral context: it probes multiple LLMs, returns scores and raw responses, and explains cost implications for Anthropic usage. No contradictions.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Every sentence adds value, covering usage, parameters, and returns without unnecessary words.

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

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

Despite no output schema, the description explicitly lists the per-model return fields (score, confidence, signals, raw_response) and mentions a combined view. It covers use cases, parameters, and default behavior completely.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra semantics, such as the default model and supported values for 'models', and clarifies the optional key usage. However, it does not significantly surpass the schema's existing detail.

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 action: 'Probe one or more LLMs for what they know... score visibility (0-100) per model'. It specifies the exact resource (business/brand/product/topic) and differentiates from siblings by focusing on AI visibility scoring rather than general querying.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model behavior and the optional Anthropic key requirement, though it does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds no further behavioral context beyond 'current,' which is minimal. 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 extremely concise (3 words), which is efficient given no parameters. However, it could be slightly more descriptive about what 'current' entails (e.g., time window) without becoming verbose.

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

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

The description is insufficient for the context of many sibling tools. It does not clarify the scope of 'current' (e.g., last hour, today) or differentiate from 'recent_alerts.' The presence of an output schema is noted but not leveraged in the description.

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

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

No parameters exist; schema coverage is 100%. The description is not required to add parameter info. With an output schema present, the return structure is handled externally, so the description adequately avoids redundancy.

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

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

The description clearly states the tool returns 'Current SWPC alerts/warnings,' specifying the resource (SWPC alerts/warnings) and action (current). This differentiates it from siblings like 'recent_alerts' by implying recency, though it does not explicitly distinguish.

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?

No usage guidelines provided. With siblings such as 'recent_alerts,' 'aurora_forecast,' and 'kp_index,' the description offers no guidance on when to choose this tool over alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the routing mechanism to 4,552 tools and the use of pipeworx:// citation URIs, enhancing transparency beyond annotations.

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

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

The description is detailed but well-organized with clear examples and usage guidance. Every sentence adds value, though slightly verbose. Could be trimmed slightly without loss of meaning, but overall efficient for the amount of context provided.

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 (6 parameters, 1 required, many sibling tools), the description is comprehensive. It covers when to use, what it does, how it works, and provides examples. Output schema not needed as behavior is self-explanatory. Completely adequate for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, and the schema already describes the 'question' parameter and its aliases. The description adds minimal extra semantics beyond restating the parameter's purpose. Baseline 3 is appropriate as description does not significantly enhance parameter understanding.

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

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

The description clearly states it answers factual questions using structured data from over 4,552 tools across 1,160 sources, with specific examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It explicitly differentiates itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH' and lists question types (what is, look up, find, etc.). Clearly states when to step up to ask_pipeworx_grounded, deep_research, or other tools, with specific use cases for each.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable detail: extra LLM call, refusal reasons list, and exact return structure. No contradictions.

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

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

Front-loaded with key phrase but runs long with implementation details. Could be more concise for quick agent scanning.

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

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

Explains return structure, failure modes, and usage context well despite no output schema. Covers most agent needs for a high-stakes read tool.

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

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

Schema coverage is 100% and each parameter description already explains alias behavior. Description just restates that they are aliases; no additional usage nuance.

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 defines as 'Hallucination-resistant answer mode for high-stakes reads' with specific verb+resource. Distinguishes from sibling 'ask_pipeworx' by noting extra LLM call and use case for quoted/cited answers.

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 (high-stakes, quoted/cited answers, no invention) and when not (casual lookups prefer ask_pipeworx). Names alternative tool 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, idempotentHint=true, and destructiveHint=false, which cover safety traits. The description adds the '30-min ovation' detail, but lacks behavioral context about rate limits, output size, or what happens if data is unavailable. Annotations carry most of the burden.

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?

Extremely concise—one short phrase. It front-loads the key info. Could arguably be a 5, but the phrase 'ovation aurora forecast' may require domain knowledge, reducing clarity 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?

Despite having an output schema (present but not detailed in the definition), the description does not indicate what the forecast contains (e.g., probability, intensity, map?). For a tool with no parameters and a potentially complex output, more description of the return value is justified. The current text is insufficient for full understanding.

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

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

There are no parameters, so baseline is 4. The description does not need to add parameter details. No issues.

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 the resource (aurora forecast) and the model (ovation) with a time window (30-min). It is clear enough to understand what the tool returns, though 'ovation' may be unclear to some users. It distinguishes from sibling tools like 'forecast_text' which likely provides textual forecasts.

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?

No guidance on when to use this tool instead of siblings like 'boulder_kp' or 'kp_index'. The description does not mention context, prerequisites, or exclusions, leaving the agent to infer 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: resolution matching, short-circuit on low confidence, closed market handling, wide-spread tradeability, cancellation rule parsing, and safety mechanisms. Far exceeds annotation coverage.

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

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

Description is very long (multiple paragraphs) and densely packed, but well-organized with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Could be more concise, but structure aids readability.

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

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

Given the tool's complexity (multiple data sources, classifiers, response fields), the description is thorough. Covers resolution confidence, parent event extraction, news fallbacks, safety short-circuits, and cancellation rules. No output schema, but response shape is described in detail.

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. Description adds value beyond schema: examples for market, rationale for include_raw default, and explanation of depth options. Provides context that helps agents choose parameters effectively.

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 action (research a Polymarket bet), input types (slug, URL, question text), and output (evidence packet + comparison). It distinguishes from siblings by focusing on specific bet analysis vs. other Polymarket tools like arbitrage or edge tracking.

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 use cases are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Fan-out examples illustrate when each classifier fires. However, no explicit when-not-to-use guidance or comparison to siblings for exclusion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'real-time' which provides behavioral context beyond annotations. However, the description does not elaborate on any other behavioral aspects.

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 sentence that is front-loaded and contains no unnecessary words. Every word adds value, making it 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?

Given the tool has no parameters and an output schema exists, the description is mostly complete. However, it assumes the agent knows what 'Boulder K-index' is, which may not be universally understood. Slightly more context could improve completeness.

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?

There are no parameters, and schema description coverage is 100%. The description does not need to explain parameters. Baseline for 0 parameters is 4, and the description meets that without adding redundancy.

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

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

The description 'Boulder K-index real-time.' uses a specific verb/implied action (provides data) and clearly identifies the resource (Boulder K-index). It distinguishes from the sibling tool 'kp_index' which likely provides global Kp, making the purpose clear and unique.

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?

No guidance is given on when to use this tool versus the sibling 'kp_index' or other similar tools. The agent is left to infer context, which may lead to confusion.

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, the description reveals data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with key trigger phrases and efficiently packs all necessary information. Every sentence adds value, though slightly verbose in listing examples.

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

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

Given complexity (two entity types, multiple data sources, no output schema), the description covers data provenance, constraints (2-5 items), sorting behavior, and output characteristics, making it fully informative.

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

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

Schema coverage is 100%, but the description adds valuable context: examples of ticker/drug names, off-calendar handling, and specific metrics pulled per type. This exceeds baseline 3.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific trigger phrases and contrasts with sequential lookups, making it distinct from siblings.

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

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

The description explicitly advises when to use (comparing entities) and prefers it over sequential single-pack lookups. However, it does not reference specific sibling tools (e.g., entity_profile) or state when not to use it.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds rich behavioral context beyond annotations: returns 'findings packet' with verbatim evidence, confidence, source, fetched_at, and stable pipeworx:// citations; reports explicit gaps for unanswered facets; explains decomposition and parallel execution; notes expected response time (15-60s); and specifies that depth='thorough' requires paid plan. 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 packed with essential information and is front-loaded with the critical account requirement. While it is relatively long, every sentence adds value covering usage, behavior, parameters, and example questions. Minor verbosity in listing source categories (SEC filings, FRED/BLS, etc.) could be condensed, but overall it is well-structured and 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?

Given the tool has only 2 parameters and no output schema, the description is exceptionally complete. It explains the tool's purpose, input requirements, output format (findings packet), performance expectations, account prerequisites, usage notes (when to use vs. alternatives), and known limitations (returns gaps for non-structured topics). The description covers all aspects an AI agent would need to decide whether and how to invoke 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?

Both parameters (question, depth) have descriptions in the schema and enumeration for depth. Schema coverage is 100%. The description adds meaningful context: specifies default depth (standard=5), explains that quick=3, standard=5, thorough=8, and notes that thorough requires paid plan. It also clarifies that question should be natural language and broad/multi-part. This adds value beyond the schema definitions.

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

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

The description clearly states the tool conducts 'grounded multi-source research' across 1160 structured data sources, decomposes questions into facets, routes to 4552 tools in parallel, and returns a findings packet with citations. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its purpose unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it requires an account (free tier with paid depth), recommends ask_pipeworx for single lookups if not signed in or for breaking/current-news topics, and best for broad/multi-part questions over structured data. It also names alternative tools (ask_pipeworx) and failure modes (returns empty gaps for uncatalogued topics).

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that it returns the top-N most relevant tools with full schemas and curated examples, ready to call directly. This discloses what the agent can expect from the response.

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 (5 sentences) and front-loaded with key information. Every sentence adds value: purpose, use cases, return format, and when to call.

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 adequately describes the return structure: a list of tools with names, descriptions, and input schemas. Parameter count is high but schema covers all. The description is complete for this discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing aliases (task, q, description, search) and providing example queries. This helps the agent understand the flexibility of the query parameter.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (find/browse/search) and the resource (tools), and distinguishes it from siblings by focusing on discovery of available tools rather than querying data directly.

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

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

Explicitly says when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when this tool is appropriate 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) indicate safe, non-destructive behavior. The description adds rich context: fans across multiple sources, returns specific data structures, mentions USPTO API sunset soft-fail, and notes the presence of pipeworx URIs. No contradictions with annotations, and the description significantly enhances transparency.

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

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

The description is verbose but justified by the tool's complexity. It is front-loaded with examples and clear intent. Every sentence provides essential information (sources, return fields, constraints). Could be slightly trimmed but remains 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?

With no output schema, the description thoroughly explains return values: CIK, company_name, recent_filings (up to 5 with URIs), fundamentals (latest 10-K details), patents (with sunset note), news (GDELT→GNews fallback), and LEI (GLEIF). This provides sufficient completeness for a complex aggregator tool.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: clarifies that 'type' only supports 'company', and explains 'value' requires ticker or zero-padded CIK (names unsupported). It also reiterates the 'names not supported' constraint. This adds value without being redundant.

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 full cross-source profile of a US public company. It provides multiple examples of user queries ('Tell me about X', 'research Acme', etc.) and lists the specific data sources and fields returned (SEC EDGAR, XBRL, USPTO, news, GLEIF). This distinguishes it from sibling tools like resolve_entity (name lookup) and compare_entities (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 when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input requirements (ticker or zero-padded CIK, not names) and directs users to resolve_entity for names. This provides clear and actionable usage 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds 'raw text' but no additional behavioral detail about content updates or side effects. With good annotation coverage, this is adequate but not improved.

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 concise sentence that front-loads the key information (source, time range, format). Every word is informative with no 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?

Given the tool has no parameters and has an output schema (though not shown), the description fully explains what the tool returns and its temporal scope. It is complete for a straightforward data retrieval tool.

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

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

The tool has no parameters and schema description coverage is 100%. Baseline for zero parameters is 4. The description correctly implies no input is needed, though it could explicitly state 'No parameters required for use'.

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 '3-day SWPC forecast discussion (raw text)', specifying the source (SWPC), time range (3-day), and format (raw text). It distinguishes itself from sibling tools like aurora_forecast, boulder_kp, and kp_index which provide numerical data rather than narrative text.

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?

No usage guidelines are provided. The description does not indicate when to use this tool over siblings like aurora_forecast or solar_wind. Users are left to infer its purpose from context, which is insufficient for an agent deciding among alternatives.

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

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

The description aligns with annotations (destructiveHint=true, idempotentHint=true) by stating 'Delete', but adds no further behavioral detail beyond what annotations provide. 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 short sentences that efficiently state purpose and usage guidelines with no superfluous information. Front-loaded and clear.

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

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

For a simple tool with one required parameter and no output schema, the description adequately covers purpose, usage, and context, pointing to siblings for complete understanding.

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

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

Schema covers 100% of parameters with description 'Memory key to delete'. The description only mentions 'by key', adding no additional meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and resource ('memory'), distinguishing it from siblings like 'remember' and 'recall' which are explicitly mentioned.

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 scenarios ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with siblings, giving clear guidance on alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints, and the description adds detail about fetching the page, extracting title/description/key links, and emitting markdown format. No contradictions. While it doesn't mention rate limits or auth needs, it is sufficiently transparent.

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

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

The description is three sentences: first sentence states purpose, second describes process, third lists use cases. It is front-loaded, concise, and every sentence adds value with no unnecessary words.

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

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

Given no output schema, the description clearly states the output is a single text blob ready for deployment. It also explains what is extracted. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description adds extra value by providing an example for 'url' and specifying default/max for 'max_links', which goes beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, explicitly naming the verb (generate) and resource (llms.txt). It distinguishes itself from siblings by specifying the output format and use cases like indexing by AI crawlers.

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

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

The description lists three specific use cases (getting a client's site indexed, drafting for own project, auditing competitor) which clearly indicate when to use. However, it does not explicitly mention when not to use or provide alternatives, so it's slightly less than perfect.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no additional behavioral context, such as data freshness, rate limits, or pagination. For a tool with such rich annotations, the description is expected to add value beyond what annotations provide.

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

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

The description is extremely concise at three words, but it sacrifices helpfulness for brevity. It lacks structure and elaboration, making it minimally viable.

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 low complexity (one parameter, no nested objects), rich annotations, and complete schema, the description is adequate but leaves room for improvement. It does not explain the return format or how the tool fits into the broader set of space weather tools.

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 fully documents the 'window' parameter with examples and allowed values. The description adds no extra meaning or context for the parameter, resulting in a baseline score of 3.

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

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

The description 'GOES X-ray flux history' clearly states the tool returns historical data for GOES X-ray flux. It specifies the resource (GOES X-ray flux) and the action (history retrieval), but it does not distinguish from sibling tools like 'solar_wind' or 'aurora_forecast'.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks any context about typical use cases, prerequisites, or scenarios where this tool is preferred over other space weather tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint(false). The description adds that it 'returns timestamped Kp measurement array', providing output format clarity. No additional behavioral details (rate limits, data freshness) are needed given annotations. The description complements annotations well.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose, valid options, and output. No unnecessary words; every element is 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?

Given the tool's simplicity (single parameter, output schema present, rich annotations), the description is complete. It covers the parameter semantics, output format, and data source. No gaps.

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

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

The input schema covers the 'window' parameter with description of allowed values. The tool description adds semantic context: '1-day observed, 7-day forecast, 30-day 1-minute estimated, or current value', explaining the real-world meaning of each option beyond the enum-like schema description.

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

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

The description clearly states the tool's function: 'Fetch NOAA planetary K-index (global geomagnetic activity 0–9) for a time window'. It specifies the resource (NOAA planetary K-index), the action (Fetch), and the scope (time windows: 1-day, 7-day, 30-day, now). This distinguishes it from siblings like 'boulder_kp' (local Kp) or 'aurora_forecast' (aurora prediction).

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 enumerates the valid time windows and their meanings (observed, forecast, estimated, current). This guides the agent on which window to use based on need. However, it does not explicitly exclude use cases (e.g., 'do not use for local Kp, see boulder_kp'), but the context of siblings implies differentiation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety. The description adds value by explaining the return structure, though it doesn't mention any additional behavioral traits (e.g., pagination, rate limits).

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, front-loading the purpose, listing return fields, and providing usage guidance. Every sentence is informative with no redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers all essential aspects: what it does, what it returns, and when to use it. The listed fields substitute for an output schema.

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

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

The input schema has 100% description coverage for the single optional parameter (include_inactive). The description does not add any 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 and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It differentiates from sibling tools like subscribe and unsubscribe which are write operations.

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

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

The description explicitly tells when to use the tool: to review current subscriptions before adding more or to find an id for cancellation. This provides clear guidance on appropriate usage context.

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

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

Annotations are sparse (all false), so description adds value: states it's free, doesn't count against quota, rate-limited to 5 per identifier per day. No contradiction.

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

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

Description is concise and well-structured: front-loaded with purpose, followed by usage guidance and constraints. 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?

Tool is simple (feedback). Schema covers all parameters, no output schema needed. Description provides complete context for successful invocation and appropriate use.

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

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

Schema covers all parameters (100%), but description adds context beyond schema: explains each enum for 'type', advises specificity for 'message', and clarifies use of 'context' (pack/tool/vertical).

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 explicitly states the tool is for sending feedback about bugs, features, data gaps, or praise. It clearly distinguishes from sibling tools (none serve a feedback purpose).

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

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

Provides explicit guidance on when to use (broken/missing/praise) and what to avoid (don't paste end-user prompt). Mentions rate limit and that it doesn't count against quota.

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

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

Adds details beyond annotations: self-aggregated, no PII, caching duration. 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?

Concise: core action first, then uses, then technical details. No 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?

Covers return values, caching, data source, and privacy. Complete for a read-only aggregated tool without 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?

Parameter 'window' already has enum and description in schema; description adds semantics about hot vs steady-state demand.

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 returns top tools, top packs, and total call volume over recent windows, with specific use cases. Differentiates sufficiently from siblings.

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 and caching behavior. Lacks explicit when-not-to-use instructions, but context is clear enough.

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

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

The description goes well beyond the annotations (readOnly, idempotent, etc.) by disclosing scanning scope (~200 markets), similarity filter (Jaccard ≥0.30), partition filter (drops placeholder slugs, >20% placeholder returns null), and the fill check mechanism (theoretical vs realizable edge). It warns about not trading if realizable edge ≤0. This is rich behavioral context not captured in the annotations.

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

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

The description is well-structured with clear sections and bold labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the main purpose and detailed but not overly verbose. However, it could be slightly trimmed; some sentences are dense. Overall, it earns its length.

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

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

Given the complexity (two optional parameters, no output schema), the description is remarkably complete. It explains scan scope, filters, edge cases (placeholders, low similarity), output structure (opportunities[], partition_check), and trading advice (fill check). It also references sibling tools for further customization, covering everything an agent needs to use the tool effectively.

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

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

Schema coverage is 100%, providing baseline 3. However, the description adds substantial meaning: it explains the difference between event and topic modes, gives concrete slug examples, and describes internal logic (partition checks, similarity thresholds, fill checks). This is valuable context beyond the simple schema descriptions, raising the score to 5.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities), and methodology. It distinguishes between two modes (event and topic) and explains their different use cases. This differentiates it from siblings like 'polymarket_edges' and 'polymarket_fill_risk'.

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

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

The description provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event mode for specific markets and explains the benefits of cross-event scanning. It also warns against trading when fill check yields ≤0. However, it does not explicitly compare to all sibling tools or state when not to use this tool, missing some exclusion criteria.

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 as true, and destructiveHint false. The description adds significant behavioral context: detailed methodology for five model families, edge calculation (including slippage and Kelly fractions), caching at KV level keyed on knobs, and diagnostic output so callers understand empty segments.

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

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

The description is quite long but well-structured with clear sections (model families, segments, response structure). Front-loaded with main purpose. Slightly verbose for an agent but comprehensive; a small reduction for potential information overload.

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

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

Despite no output schema, the description thoroughly details the response format: by_segment, fed_candidates, _diagnostics, and individual opportunity fields (edge_pp_net, kelly_fraction, etc.). Also explains caching behavior. Given the tool's complexity and 9 parameters, the description is complete and self-contained.

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

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

All 9 parameters have schema descriptions (100% coverage), but the tool description adds substantial value: explains how slippage_pp is used, why min_kelly doesn't apply to partition arb opportunities, and the rationale behind min_liquidity and max_spread_pp knobs. This goes well beyond baseline and aids correct parameter selection.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, explicitly framing it as 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge discovery across multiple model families.

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

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

The description explains that the tool is for discovering opportunities without paging through hundreds of markets, and provides guidance on tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) and why Fed bets are excluded. However, it does not explicitly state when not to use this tool versus alternatives, leaving some ambiguity for siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: history depth bounded by 60-day TTL, decay computed from daily closes (not intraday), and details about snapshot gaps. This 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 lengthy but well-structured: purpose first, then key behavioral details, response structure, and limitations. It is front-loaded but every sentence adds value, especially given no output schema.

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

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

With no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and limitations. For a tool with 2 optional parameters, this provides complete contextual understanding.

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

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

Schema description coverage is 100% with both parameters described. The description repeats defaults and constraints (days default 14, window default '1wk') but adds little new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes from siblings like polymarket_edges by focusing on historical tracking.

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

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

The description explains when to use this tool (for analyzing edge longevity vs freshness) and provides context contrasting fresh vs old edges. It does not explicitly state when not to use or name alternatives, but the context is sufficient for an agent to differentiate.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral context: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains risks like thin_legs and forced_directional_risk. No contradiction with annotations.

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

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

The description is front-loaded with purpose and requirements, then structured by mode. It is somewhat verbose (over 200 words) but every sentence adds value. Minor redundancy in mode headers could be tightened, but overall well-organized.

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

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

Given the tool's complexity (two modes, no output schema), the description comprehensively covers inputs, behavior, return fields, and risks. It lists all return fields for both modes, explains thin legs and forced directional risk, and provides usage guidance. No gaps perceived.

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% for 4 parameters. The description adds extra meaning beyond the schema: explains default values for side and size_usd, clarifies size_usd in basket mode as 'settlement notional S (shares per leg; each share pays $1)', and defines single-market vs basket modes. Adds value above the baseline of 3.

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

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

The description starts with a clear verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly states when to use this tool before `polymarket_arbitrage` and `polymarket_edges`, differentiating from siblings.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about partial basket fills converting an arb into an unhedged directional position, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral details: compatibility warnings, temporal alignment, skipped cross types, and warning that most shortcuts are untradeable. This enriches understanding 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 dense but structured: purpose first, then modes, response, safety fields. Every sentence adds value. Slightly verbose but appropriate given complexity.

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

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

No output schema, so description fully covers return values: leg-by-leg prices, matched spreads, safety fields. It explains edge cases like compatibility warning conditions and temporal alignment, making it complete for complex tool behavior.

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

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

Schema coverage is 100%, and the description adds meaning: 'topic' auto-fetches matching events, explicit tickers override. It explains both modes clearly, adding value beyond schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It identifies two distinct modes (topic shortcuts and explicit pairings), which distinguishes it from siblings like polymarket_arbitrage.

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

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

The description provides context on when to use it, noting that most pre-mapped topics return compatibility warnings and that real spreads are rare. It explains conditions for meaningful spreads (temporal alignment, compatibility). However, it doesn't 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?

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds scoping info ('Scoped to your identifier') and pairing with remember/forget. This is valuable but not extensive beyond annotations, so a score of 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 three sentences covering action, use cases, and scope. It is efficient and front-loaded, but the third sentence on scoping could be integrated more concisely. Still, it is 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 low complexity (1 optional param, no output schema), the description covers purpose, usage, scope, and relations to siblings. It lacks details like return format or error handling, but those are likely obvious. Score 4.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the dual behavior: retrieving a specific key vs. listing all keys when omitted. This goes beyond the schema's property description, scoring a 4.

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

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

The description explicitly states the action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It provides specific examples of use cases (ticker, address, notes) and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description clearly indicates when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains how to list all keys by omitting the argument. While it doesn't explicitly state when not to use, the context is clear and practical.

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 states that setting 'mark_read:true' flags events as read, implying a state mutation. This directly contradicts the annotation 'readOnlyHint: true', which signals no side effects. According to rules, a contradiction scores 1. Additionally, the annotation already covers safety, so the description adds a misleading behavioral trait.

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

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

The description is four sentences, front-loaded with the core purpose. It is clear and includes essential details like returned fields, filter options, and alternative access. A minor improvement could be merging the alternative URL mention to keep it tighter, but it's well-structured overall.

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 5-parameter, optional, read-oriented tool, the description covers return fields, filtering, polling, and alternative access. However, the contradiction about mark_read undermines completeness because it describes a side effect that the annotations say does not exist. This gap prevents a higher score.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context beyond schema (e.g., example for 'type', behavioral effect of 'mark_read'), but mostly rephrases schema descriptions. It does not significantly enhance understanding beyond what the schema provides.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies the returned fields (source, citation_uri, payload), and mentions filtering options. It is specific about the verb 'pull' and the resource 'fired events from your subscription feed'. However, it does not explicitly differentiate from the sibling 'alerts' tool, so not a full 5.

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

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

The description mentions that polling works fine and gives an alternative REST endpoint for scripts, but provides no guidance on when to use this tool versus other tools like 'alerts' or 'list_subscriptions'. There is no explicit when-not or alternative tool context.

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

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

Annotations already declare safety profile; description adds valuable behavioral details like fan-out strategy, fallback logic (GDELT→GNews), and USPTO soft-failure, beyond annotations.

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

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

Front-loaded with example queries and packed with useful info. Slightly verbose but every sentence contributes value. Well-structured for agent comprehension.

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

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

Given no output schema and complexity (multiple sources, fallbacks), description covers return structure and parameter nuances. Missing minor error handling, but overall comprehensive.

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?

Despite 100% schema coverage, description adds meaning: explains since accepts ISO or relative with examples, suggests '30d', and clarifies value can be ticker or CIK. Enhances schema.

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

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

The description clearly states the tool returns a change feed for a company with example queries, specifies fan-out to multiple sources, and distinguishes from sibling tool entity_profile.

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

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

Explicitly says when to use this tool vs entity_profile, and gives guidance on since parameter format. Does not exclude other siblings but provides clear 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 (idempotentHint true), the description adds that memory is scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. It aligns with annotations and adds useful 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 well-structured in 5 sentences: definition, usage, storage details, persistence, and pairing. It is clear and concise without unnecessary words, though could be slightly more compact.

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

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

Given 2 parameters, no output schema, and rich annotations, the description covers purpose, usage, parameter semantics, and behavioral details. It is sufficient for an agent to use correctly, though output schema could add completeness.

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

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

Schema coverage is 100% with both key and value described in the schema. The description reinforces usage with naming conventions ('subject_property', 'target_ticker') but doesn't add significant meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, with a specific verb 'save' and resource 'data' (key-value memory). It explicitly distinguishes from sibling tools recall and forget, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also explains persistence duration for authenticated vs. anonymous sessions. It doesn't explicitly mention when not to use, 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 read-only, idempotent, and non-destructive behavior. The description adds significant context: cascading internal lookups, auto-disambiguation for companies, and explicit return fields with citations. No contradictions.

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

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

Description is well-structured and informative, starting with purpose and moving to details. A few extra phrases could be trimmed, but each sentence adds necessary context. Not overly verbose.

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

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

For a resolution tool with two simple parameters and no output schema, the description fully explains input handling, return format, and internal behavior. It leaves no obvious gaps for the agent to use it correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description enriches both parameters by detailing accepted input formats for each type (ticker, CIK, name; brand/generic) and explaining the enum values for 'type' with expected outputs. Adds meaning beyond schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples (ticker, CIK, RxCUI). It distinguishes itself from sibling tools by emphasizing the 'name to ID' conversion role.

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

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

Provides explicit usage instruction: 'Use FIRST whenever you have a name but need an ID.' It also notes it replaces manual lookups, but does not explicitly mention when not to use or list alternatives, though 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 declare read-only, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. Also mentions API key requirement for Anthropic model, which is useful beyond annotations.

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

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

Three sentences: purpose, mechanism, use case/return format. No wasted words, front-loaded with action. Efficient and clear.

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

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

No output schema, but description details return format: ranked list with score, confidence, signal density. Covers all parameters and their roles. Adequate for agent to understand inputs and outputs.

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

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

Schema covers all 4 parameters. Description adds narrative meaning: first entity treated as subject, example for context parameter ('B2B SaaS'), and clarifies models parameter behavior. Adds value beyond schema.

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

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

Description clearly states verb 'compare', resource 'AI visibility', and side-by-side ranking. Distinguishes from sibling 'ai_visibility_check' by specifying it probes multiple entities and returns a ranked list.

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

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

Explicitly gives use case for competitive AI-marketing audits. Implies when to use vs single entity check via 'side-by-side' language, but does not explicitly state when not to use or list alternatives.

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

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

Adds significant context beyond annotations: composite call, partial failure handling, bundlephobia's first measurement taking 5-30s, and the sources_failed field. 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 clear sections (purpose, usage, return, limitations, behavior). Slightly verbose (~120 words) but each sentence adds value; no redundancy.

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

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

For a tool with no output schema, the description provides a detailed list of return fields, explains partial failure and timing, and covers caveats. Very complete for the complexity level.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra meaning: 'Scoped packages accepted' and clarifies version defaults. Provides useful clarification beyond schema.

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

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

The description clearly states the composite check purpose for evaluating npm packages, naming both data sources (deps.dev and bundlephobia). It distinguishes itself from sibling tools by focusing on 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 states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and excludes other ecosystems ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also explains graceful degradation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds crucial behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also notes that passages have offsets for verification. 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 (under 100 words) and well-structured. It front-loads the core idea, then adds use-case guidance, alternatives, and technical details. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description fully explains the return values: 'top-N passages with character offsets and similarity scores.' It also covers input constraints (max 200K chars, truncation flag) and use-case context. The description is self-contained and answers likely agent questions.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema: it provides examples for the query parameter (e.g., 'supply-chain risk') and explains the limit parameter's default and range. The text parameter's character cap is reiterated. While helpful, the gain over the schema is modest.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies input (text and natural-language query) and output (top-N passages with offsets and scores). It distinguishes from sibling tools like 'ask_pipeworx_grounded' by explaining the pairing and preferred 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 advises when to use: 'Use when the record is too big to cram into the prompt.' It also suggests an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear context and exclusion criteria.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the source (DSCOVR) and data type (plasma + magnetometer), but does not elaborate on response format, caching, or limits. Minimal added value beyond annotations.

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

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

The description is a single, front-loaded sentence with no fluff. Every word adds context: 'Recent' indicates time range, 'solar wind' indicates data type, and 'DSCOVR plasma + magnetometer' specifies source and components.

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

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

Given the simple tool (one optional parameter, no required params, output schema exists), the description is nearly complete. It covers what data is returned and the source. Minor gap: default window behavior is only in schema, not description.

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

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

Schema description coverage is 100% with the 'window' parameter fully described. The tool description adds no additional semantic value for the parameter; it only mentions 'recent' without explaining the available windows. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool provides recent solar wind data from DSCOVR, combining plasma and magnetometer readings. This distinguishes it from sibling tools like aurora_forecast or kp_index, which focus on different space weather parameters.

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?

No explicit guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, typical use cases, or when to avoid using it, leaving the agent without context for 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 behavioral traits beyond annotations: requires OAuth, returns subscription id, delivery always includes feed, email/sms/webhook with specific restrictions (phone verification, 10/day SMS cap, webhook HMAC signing and auto-disable after 10 failures). 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?

Front-loaded with main purpose, well-structured with examples and bullet points. All sentences add value, though slightly lengthy; could be more succinct without losing clarity.

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

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

Covers prerequisites, supported types, parameter details, delivery options, return value, and behavioral constraints. Missing error handling or exact response format, but overall comprehensive for a mutable tool with 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 coverage is 100%, but description adds significant meaning: explains each type's filter parameters with examples, delivery channel constraints (phone must be verified, webhook secret returned once), and conditions for auto-disable.

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?

Explicitly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' with specific verb and resource, distinguishing it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Provides clear context on when to use (creating subscriptions) and prerequisites (Pipeworx OAuth account). Details supported types and delivery channels with constraints (SMS cap, webhook auto-disable), but does not explicitly compare with sibling tools for alternative actions.

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 safety (readOnly, idempotent, openWorld, non-destructive). Description adds behavioral context: returns examples drawn from live catalog, exact tool+argument shape, no side effects. No contradiction.

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

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

Description is moderately long but highly informative, front-loaded with alternative query phrases. Could trim a few words, but every sentence serves a purpose.

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

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

Given the tool has only one optional parameter and no output schema, the description fully explains inputs, outputs, and usage context. Covers when to use, what to expect, and how to vary calls.

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

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

Schema coverage is 100% and description adds value beyond schema: lists allowed topic values (finance, pharma, etc.) and explains effect of omitting topic (cross-category spread).

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

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

The description clearly states the tool returns category-bucketed example questions with tool/argument shapes, serving as an onboarding entry point. It distinguishes from siblings like 'discover_tools' by focusing on learning what to ask and how to call meta-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?

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do' and directions to call with no arguments for full spread or pass a topic to focus. Also explains how it helps learn to call meta-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?

Description reveals that the row is deactivated, not deleted, preserving historical events for recent_alerts. This adds behavioral context beyond annotations (idempotentHint, destructiveHint). No contradiction with annotations.

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

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

Two concise sentences, front-loaded with the action and followed by important constraints. No extraneous text.

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

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

Given the tool's simplicity (single parameter, no output schema), the description is fully adequate. It explains what happens and the side effect (deactivation) without needing more.

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 'id' parameter already described thoroughly. The description does not add extra semantic information beyond what is in the schema, so baseline 3 is appropriate.

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

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

The description clearly states it cancels a subscription by ID, distinguishing it from sibling tools like subscribe and list_subscriptions. The verb 'cancel' and resource 'subscription' are specific, and the scope is explicitly defined.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use this tool. It does not explicitly mention alternatives, but the context from sibling tools and the description itself implies it is for cancellation only.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds significant context: it returns a verdict, extracted form, actual value with citation, and percent delta, and mentions it replaces sequential calls. No contradictions.

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

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

The description is well-structured, starting with example queries and then stating purpose, domain, returns, and benefits. It is slightly verbose due to the list of example phrases, but still concise overall.

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 (one parameter) and the detailed description covering purpose, domain, return values, and advantage, it is complete. No output schema is needed as the return is 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 description coverage is 100% with a clear description of the 'claim' parameter. The main description adds extra context about the type of claims (company-financial) but is not necessary for understanding the parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims. It provides examples and explains the return verdicts. It is distinct from sibling tools, which are mostly unrelated.

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 whenever the agent needs to check whether something a user said is factually correct.' It specifies the domain (company-financial claims via SEC EDGAR). It does not explicitly mention when not to use, but the specificity implies limitations. A score of 4 for clear context without exclusions.

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