Hurricanes

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds key facts: 'Keyless' (no auth needed) and 'Returns an empty list in the off-season', which provide behavioral context beyond the annotations.

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

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

The description is concise, using bullet-like phrasing (dash-separated fields) and separate short sentences for filters, keyless, and seasonal behavior. Every sentence adds unique value with no redundancy.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description covers purpose, capabilities, and edge cases (off-season). Missing aspects like data freshness are minor given the tool's simplicity.

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

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

Schema coverage is 100% with a clear description of the 'basin' parameter. The description only repeats 'Filter by basin', adding no new semantic value 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 explicitly states 'List currently active tropical cyclones' with a specific source (US National Hurricane Center) and enumerates the returned fields. It distinguishes from sibling tools by focusing on active storms listing, while 'storm_details' likely provides per-storm info.

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

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

The description implies usage for listing active storms and notes that empty list is returned in off-season. However, it does not explicitly compare to alternatives like storm_details or specify when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: default model (free), optional Anthropic probe with BYO key, and return structure (score, confidence, signals, raw_response). No contradictions. This additional context enhances transparency beyond annotations.

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

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

Three sentences, no filler. Essential information is front-loaded: the tool's core function, default model, optional API key behavior, and return structure. Every sentence carries weight.

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 parameter set (4 params, 100% schema coverage) and rich annotations, the description covers all relevant aspects: purpose, use cases, model selection, API key handling, and return format. No output schema exists, but the description summarizes the return fields sufficiently. The tool's complexity is low, and the description matches it.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining the default model behavior, how the API key is passed, and the optional context parameter's purpose. This raises the value beyond the schema alone, justifying 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 uses a specific verb-resource pair ('Probe...LLMs for what they know...score visibility') and clearly distinguishes the tool from siblings by focusing on multi-model visibility scoring. Siblings like 'compare_entities' or 'scan_competitor_ai_presence' have different purposes, so this tool's unique role is well established.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and when to use an API key. However, it does not explicitly state when not to use this tool or name direct alternatives among siblings, leaving some ambiguity for the agent.

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

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

Although annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: it explains the internal routing and argument-filling behavior, the structured output with citation URIs, the coverage of live news, and performance characteristics ('one fast call'). No contradiction with annotations.

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

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

The description is long but densely informative. It front-loads the most important instruction ('PREFER OVER WEB SEARCH') and then methodically covers use cases, examples, alternatives, and scope. Every sentence contributes either usage guidance, differentiation, or behavioral detail, so it earns its length despite being wordy.

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 meta-routing tool with no output schema, the description is remarkably complete: it explains the return type (structured answer with citations), when to use versus alternatives, what domains it covers, example queries, and when to escalate to grounded or deep research. This is more than sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already has 100% coverage with descriptions for the main 'question' parameter and aliases. The description adds value by providing example queries and explaining when to use the tool (trigger phrases), which implicitly clarifies the expected format and scope of the question parameter. However, it doesn't elaborate on the alias mechanics 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 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This gives a specific verb and resource, and it explicitly contrasts with web search and sibling tools, so it distinguishes itself effectively.

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

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

Usage guidance is highly explicit: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). It also provides trigger phrases like 'what is', 'look up', and concrete examples, making it unmistakable when to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds that this is an experimental edge with candidate routing under test, currently matches stable, and results are compared for merges. This is useful behavioral context 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?

Three sentences, each informative: beta status, current behavior, and usage instruction. No filler, though slightly longer than strictly necessary.

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 beta variant of a known tool, it covers purpose, usage, experimental context, and references the same response shape, compensating for the lack of an output schema. It is sufficiently complete for an agent to use correctly.

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

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

All 6 parameters are fully described in the schema (100% coverage), so the description adds minimal parameter semantics. It references 'same arguments' but provides no additional detail beyond the schema's alias descriptions.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router, and distinguishes it from the stable ask_pipeworx and the grounded variant. It specifies the verb 'ask' and describes the tool's role in routing questions with experimental improvements.

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 to use when you want the newest routing, and notes it currently behaves exactly like ask_pipeworx, implying the stable alternative. It provides clear selection context and mentions that results are compared against the stable router for merge decisions.

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

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

Description details return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and refusal reasons (not_in_source, no_tool_match, etc.), adding to the annotations' readOnly/openWorld/idempotent hints. It also flags the extra LLM call cost, providing behavioral context beyond the annotations.

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

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

The description is long but every sentence adds value: purpose, routing, extraction constraint, return/refusal contract, usage guidance, cost tradeoff. It is front-loaded with the core purpose before details.

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

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

The tool has no output schema, so the description correctly compensates by specifying exact return fields and refusal reasons. It also explains the tradeoff vs sibling ask_pipeworx, making it complete for a high-stakes decision 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?

All six parameters are aliases of the single question string, and the schema already documents them at 100% coverage. The description adds no new parameter-specific semantics beyond the schema, so baseline 3 applies.

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

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

Description states 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with ask_pipeworx by noting it extracts answers only from tool results. This distinguishes it from sibling tools with the same routing and makes the specific verb/resource/mode clear.

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

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

Description gives explicit use case: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative: 'prefer ask_pipeworx for casual lookups.'

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral context: market resolution, classification, fan-out, response shapes, resolver contract, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule 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?

Very long description but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Front-loaded with purpose and usage. Slightly verbose but necessary given tool complexity.

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

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

No output schema, but description fully compensates by detailing market fields, analysis fields, evidence keys, resolver contract, parent event extractor, news fields, safety behaviors, and resolution-rule risk. Comprehensive for a complex research 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 description significantly enhances understanding: explains market parameter accepts slug, URL, or question text; describes depth enum (quick vs thorough) and include_raw boolean with clear trade-offs. Adds practical examples.

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

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

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. Distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on deep-dive research for a specific question.

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

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

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Lacks explicit when-not-to-use or named alternatives, but the context with sibling tools provides enough 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, openWorldHint, etc. Description adds valuable behavioral details: company data from latest 10-K with off-calendar fiscal year handling, drug data from FAERS, results sorted by primary metric, 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?

Front-loaded with trigger phrases, then explains data sources and behavior. Every sentence adds value, though slightly dense. Could be slightly more streamlined but efficient for the information density.

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 2 params and no output schema, description covers input types, output (paired data + citations), sorting order, and replaces 8-15 lookups. Fully complete for the tool's purpose.

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

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

Schema coverage is 100%. Description adds meaning with examples (tickers vs drug names), clarifies off-calendar handling, and explains sorting behavior. Baseline 3 but extra context justifies 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?

Description uses specific verbs like 'compare', 'rank', 'head to head' and clearly states it provides 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by emphasizing one call vs sequential lookups.

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

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

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example query patterns. No explicit when-not-to-use, but context is clear.

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

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

Annotations already provide readOnlyHint/openWorldHint/idempotentHint/destructiveHint, and the description adds substantial behavioral context without contradiction: account/paywall requirements, parallel execution, latency (15-60s, up to ~90s), gap recovery, contradictions[], semantic excerpting, and fetchable citation_uri semantics. This is far beyond what annotations alone convey.

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

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

The description is long, but nearly every sentence adds critical operational detail (signup, latency, fallback, citation fetching, excerpt behavior). It is front-loaded with account warning and uses well-delineated sentences. Some repetition could be trimmed, but it remains focused and information-dense.

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

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

Despite no output schema, the description fully defines what the tool returns: findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], and hop field. It also covers edge cases (empty gaps[], non-fetchable citations, long-record excerpting) and runtime expectations. This is comprehensive for a complex research tool.

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

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

Schema coverage is 100% and the schema already describes question and depth, but the description adds rich meaning: it explains what each depth tier actually does (facet count, gap recovery, contradiction scan, paid 'thorough'), and clarifies that question is natural-language and best used for broad/multi-part queries. This significantly enhances agent understanding beyond the raw 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with clear mechanics: decomposes, routes, returns a findings packet. It strongly distinguishes from siblings like ask_pipeworx and compare_entities by explicitly contrasting use cases.

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

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

Explicit guidance is given: 'Best for broad/multi-part questions over structured data', and clear alternatives are named: 'For a single lookup use ask_pipeworx', and for breaking news 'prefer ask_pipeworx'. It also specifies when deep_research is a poor fit, saying it returns mostly empty gaps[] for non-catalog 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?

Annotations provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral traits beyond annotations: returns top-N most relevant tools, each result ready to call directly without second schema lookup. No contradiction; description adds useful 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 approximately 5 sentences, front-loaded with the core purpose. Every sentence contributes value: purpose, usage context, supported domains, return value details, and a call to action. 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 explains return values (top-N tools with names, descriptions, schemas). It covers parameter aliases and limits. For a discovery tool with 6 parameters (1 required), the description provides sufficient context for an agent to invoke 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 all 6 parameters documented. The description explains the main parameter 'query' with natural language description and aliases, and notes the 'limit' parameter's default and max. This adds meaning 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's purpose: 'Find tools by describing the data or task.' It lists many domains (SEC filings, financials, etc.) and indicates it returns top-N relevant tools with names, descriptions, and schemas. This distinguishes it from sibling tools, which are domain-specific, making its unique role clear.

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

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

The description gives explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides example queries and a list of supported domains. While it lacks explicit when-not or alternatives, the context is clear for a discovery tool.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint. The description adds valuable behavioral details: it runs in parallel, USPTO API sunset May 2025 with soft-fail, and GDELT→GNews fallback. 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 fairly detailed but each sentence adds value. It front-loads with examples and the primary purpose. Could be slightly more concise, but given the complexity of the tool, the length is justified.

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?

Even without an output schema, the description enumerates all major return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). It also mentions known caveats (USPTO sunset, name resolution). This gives the agent a solid understanding of what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'type' is currently only 'company' and 'value' can be ticker or zero-padded CIK, reinforcing and clarifying 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 produces a 'full cross-source profile of a US public company in ONE parallel call' and lists numerous specific data sources and outputs. It distinguishes itself from chaining single-pack lookups and sibling tools like compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and specifies that names are not supported, advising to use resolve_entity first. This provides 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 destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no behavioral context 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?

Two concise sentences, front-loaded with action, no wasted words.

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

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

Simple tool with one parameter and no output schema; description fully covers purpose, usage, and parameter meaning.

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 'key' described as 'Memory key to delete'. Description adds no additional semantics beyond the schema.

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

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

Description states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings by mentioning 'remember and recall'.

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

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

Explicitly states when to use it: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with siblings for 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 indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. It also states the output is a single text blob ready for deployment. 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 two sentences with a bulleted list of use cases. It is front-loaded with the core action ('Generate a production-ready llms.txt file...') and provides all necessary information without redundancy. Every sentence contributes to understanding.

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 (2 params, no output schema, no nested objects), the description is fully complete. It covers purpose, usage, behavior, and output format. It does not need to describe return values since no output schema exists, and it clearly states the output is a markdown text blob.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description adds meaning by explaining that the 'url' parameter is the site to summarize and that the tool extracts title/description/key links. It does not explicitly mention 'max_links', but the schema covers it with a default and max value. The description adds value beyond the raw 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, specifically targeting AI crawlers like ChatGPT, Claude, and Perplexity. It uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and a clear resource (llms.txt file). The tool is distinct from sibling tools, which focus on weather, betting, research, etc.

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 explicit use cases: getting a client's site indexed, drafting for own projects, auditing competitors. It provides clear context for when to use the tool. However, it does not explicitly state when not to use it or provide alternatives, though the uniqueness of the tool makes exclusions less necessary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return field details but no additional behavioral traits.

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

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

Two sentences, no redundant information, front-loaded with purpose and return details.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description fully covers purpose, usage, and return fields.

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

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

Schema coverage is 100% for the single boolean parameter. Description adds no extra meaning beyond what the schema provides.

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

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

Description clearly states verb 'List' and resource 'caller's active subscriptions', and specifies return fields. Distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel', providing context for usage vs 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 are all false, so the description carries the full burden and excellently discloses behavior: claim_token return for anonymous filing, later retrieval by re-invoking with the token, rate limit (5/day/identifier), free-of-charge, and no quota impact. No contradictions with annotations.

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

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

The description is a single dense paragraph but every sentence earns its place: purpose, use cases, exclusions, claim_token flow, rate limit, and cost. It's front-loaded with the primary action and quickly moves to actionable guidance. No filler or tautology.

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

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

Despite no output schema, the description fully explains return behavior: anonymous filing returns a claim_token, later invocation with that token returns status and resolution details. It also covers rate limiting, free access, and who reads the feedback. Complete for a feedback tool.

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

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

Schema has 100% parameter descriptions already, but the tool description adds crucial semantics beyond the schema: clarifies claim_token is for reading prior feedback responses, explains the 'no other arguments' condition when using it, and gives message content guidance ('don't paste the end-user's prompt'). This adds value above the structured fields.

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

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

Description states a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise) which distinguishes it from sibling tools like ask_pipeworx or discover_tools, none of which serve feedback.

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

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

Explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides a clear exclusion for tools from other MCP servers and a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds unique behavioral insights: data source ('CF analytics-engine'), no PII, and caching behavior ('Cached 5min-1h depending on window'). No contradictions.

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

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

Three sentences: first defines the output, second lists use cases, third adds technical details. Information is front-loaded and every sentence earns its place 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's simplicity (1 optional param, no output schema, all safety annotations), the description fully covers input meaning, real-world use cases, data provenance, privacy, and caching. No gaps remain.

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

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

Schema coverage is 100% with one optional parameter (window) having a full enum. The description enriches the enum: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds context beyond the enum labels.

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

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

The description uses a specific verb ('Returns') and identifies the exact resources ('top tools, top packs, and total call volume') over configurable windows. It clearly distinguishes itself from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on agent call activity data.

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

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

Three explicit use cases are listed, covering discovery ('what data sources are hot'), verification ('confirming a popular tool'), and alignment ('whether your use case aligns'). Lacks explicit when-not-to-use or alternative tool mentions, but the guidance is clear and helpful.

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

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds critical behavioral context: partition-check logic (sum of YES prices ≈1), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check against CLOB depth, and conditions where trades should not be executed. No contradictions with annotations.

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

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

The description is lengthy but well-organized with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though the density of information could be slightly reduced for skimmability without losing critical details.

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

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

Despite having no output schema, the description fully specifies the response structure (opportunities[] with gap_pp, suggested_trade, etc., partition_check fields). It covers all modes, fill check, and error conditions (e.g., placeholder fraction >20% returns null). No gaps remain for agent understanding.

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

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

With 100% schema description coverage, both parameters already have descriptions. The tool description significantly enriches them by explaining the internal behavior of each mode (e.g., event mode walks child markets, topic mode searches related events) and providing specific examples of accepted values.

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

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

The description explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes three modes: no-args trending scan, event mode for specific markets, and topic mode for cross-event scanning. This provides precise purpose and differentiation from sibling tools.

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

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

The description offers detailed guidance on when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains the limitations of single-event mode and when cross-event mode is needed. It also references polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral details: 1-hour caching at the KV level, edge calculation net of slippage, per-segment response structure, and diagnostic information. No contradictions with annotations.

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

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

The description is well-structured with clear sections (model families, knobs, response details) and front-loaded with a concise purpose statement. However, it is quite long and could be slightly tightened without losing critical technical details.

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

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

Despite the tool's complexity (9 parameters, no output schema), the description covers all essential aspects: return structure (by_segment with diagnostics), model family details, edge calculation methodology, parameter knobs, and caching policy. No gaps are apparent.

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

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

Schema coverage is 100% with good descriptions. The description further enhances parameter understanding by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and their interaction with the edge calculation, adding context beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for daily opportunity discovery ('what should I bet on today') and clearly distinguishes itself from sibling tools like polymarket_arbitrage by covering 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 provides context for usage (daily opportunity scanning, avoiding paging through hundreds of markets) but does not explicitly mention when to use alternatives or when not to use this tool. Sibling tools like polymarket_arbitrage or polymarket_edge_tracker exist for more specific tasks, but no guidance is given on when to prefer them.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety. It adds useful behavioral details: how trends and decay are computed, that snapshots are daily with gaps, and the 60-day TTL limitation.

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 and front-loaded with purpose, but it is verbose and could be more concise. It contains multiple clauses and details that, while informative, could be streamlined for quicker 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?

The description compensates for the lack of output schema by thoroughly explaining the response structure: tracked[], expired[], snapshot_dates[]. It also describes limitations and data sources, providing a complete picture for a 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?

Schema coverage is 100%, and the description adds default values and explains the effect of 'days' (lookback) and 'window' (snapshot family). This provides marginal value beyond the schema, but does not significantly enhance understanding of parameter semantics.

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, answering 'how long has this edge existed and is it shrinking?'. It uses specific verbs like 'tracked', 'expired', and distinguishes from the sibling 'polymarket_edges' by focusing on time-series and decay.

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

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

The description implies the tool is for historical analysis of edge persistence but does not explicitly state when to use it versus alternatives or provide exclusions. The context is clear but lacks direct guidance on when-not-to-use or comparisons with siblings.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds significant behavioral context: explains ladder walking, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), partial fill risks, 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?

Description is long but well-structured with clear sections for single-market and basket modes, using all-caps keywords for emphasis. Front-loaded with purpose. Could be slightly trimmed but appropriate for complexity.

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

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

No output schema, but description thoroughly lists return fields for both modes, explains failure modes (thin_legs, cannot_fill verdict), and provides risk warnings. Covers everything an agent needs to understand tool behavior 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 coverage is 100% so baseline is 3. Description adds value by explaining auto behavior for side in basket mode, details on size_usd interpretation for buys vs sells and settlement notional, and defaults. Goes beyond schema but schema already covers basics.

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 it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific inputs and outputs. It also differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it before acting on those signals, making purpose very 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?

Provides explicit guidance on when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It warns about partial basket fills converting arb to unhedged directional position, the dominant loss mode. This gives clear when/why/alternatives 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?

Beyond annotations (readOnlyHint, openWorldHint), the description discloses detailed behavioral traits: compatibility_warning conditions, temporal alignment checks, skipped counters for non-equivalent bet shapes. This rich context about when spreads are mathematically meaningful goes far 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 well-structured: introduction, modes, response fields, safety fields. It is verbose but each section adds necessary detail, with front-loaded main purpose. Minor verbosity prevents a 5.

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

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

Despite no output schema, the description thoroughly explains response structure (raw prices, spread array, compatibility_warning, temporal_alignment, skipped counters). For a complex cross-venue comparison tool, this provides complete context for an agent to interpret results 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 inline descriptions. The description adds usage context (topic list, overriding behavior) but does not significantly enhance parameter meaning beyond the schema.

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

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

The description explicitly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and distinguishes two modes (topic shortcuts and explicit tickers), clearly differentiating it from siblings like polymarket_arbitrage which is single-venue.

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

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

The description provides clear guidance on two usage modes, including when to use topic shortcuts vs. explicit tickers, and warns that most pre-mapped topics are not tradeable. It lacks explicit 'when not to use' statements but the context is sufficient.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds scoping detail (by identifier) and pairing behavior, providing useful context beyond annotations without contradiction.

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

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

The description is three sentences, each serving a purpose: action, usage scenario, and scoping. It is front-loaded with the primary function and is free of 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?

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what the agent needs: behavior, scope, and pairing with siblings. No gaps remain.

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 parameter description already explains the key's behavior. The tool description restates this but adds the listing behavior hint, which is helpful but not necessary given 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 retrieves a saved value or lists all keys, with specific examples (ticker, address, research notes). It explicitly distinguishes from sibling tools 'remember' (save) and 'forget' (delete), making the purpose unmistakable.

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

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

The description provides clear usage context: 'look up context the agent stored earlier' and indicates when to omit key to list all. While it pairs with remember/forget, it lacks explicit exclusion guidance for 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 provide readOnlyHint, idempotentHint, and destructiveHint, which are consistent with the description. The description adds valuable behavioral details such as the structure of returned events (source, citation_uri, raw payload), the effect of mark_read, and that polling works fine. No contradictions found.

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, which is reasonable but could be slightly tighter. The main action is front-loaded with clear verb and noun, and each sentence adds useful information. Minor verbosity in explaining mark_read and the alternative endpoint.

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 sufficiently explains return structure (source, citation_uri, raw payload) and key behaviors. It covers all 5 parameters indirectly through examples and usage notes. Lacks explicit mention of pagination or error handling, but the tool's nature as a read-only fetch is well-covered.

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

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

Schema coverage is 100% with each parameter already described. The description reinforces some parameters (e.g., type example 'sec_8k') but does not add significant new meaning beyond the schema. Baseline 3 is appropriate as the description adds minimal extra value.

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

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

The description clearly states it pulls fired events from the subscription feed, specifying the resource and action. It provides specific fields returned (source, citation_uri, raw payload) and distinguishes from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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

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

The description offers practical usage guidance, including how to filter by type and since timestamp, and how mark_read works to control subsequent calls. It also mentions an alternative HTTP endpoint for scripts. However, it does not explicitly contrast with other retrieval tools like search_within or recall, leaving some ambiguity about when to prefer this tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about the fan-out logic, fallback between GDELT and GNews, and soft-failure for USPTO. 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 relatively long but efficiently packed with information. It fronts example queries and then details behavior. Minor redundancy but overall well-structured.

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

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

No output schema exists, but the description explicitly states the return structure (changes grouped by source, total_changes count, citation URIs). Combined with the detailed parameter guidance, the description is fully 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?

Schema coverage is 100%. The description adds examples and nuances for each parameter (e.g., 'since' format with examples, 'value' accepts ticker or CIK, 'type' only supports company), going beyond the schema descriptions.

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

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

The description clearly states it is a change feed fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling tool 'entity_profile' by specifying when to use that instead.

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 entity_profile instead and gives example queries that show typical usage. Does not compare with all siblings but the main alternative is covered.

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 persistence detail (24 hours for anonymous, persistent for authenticated) and scoping by identifier beyond annotations. 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?

Four concise sentences front-loading purpose, with no redundant or irrelevant information. Every sentence earns its place.

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

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

For a write tool without output schema, the description adequately explains storage behavior and usage context. Could mention overwriting semantics but idempotentHint covers safety.

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% with descriptions; the description adds value by providing example key names (e.g., 'subject_property') and hints at value content, enhancing 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 specifies 'Save data the agent will need to reuse later' with clear verb and resource, and distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and gives concrete examples. Also notes session vs persistent scoping and pairs with recall/forget.

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

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

Beyond the readOnly/idempotent annotations, the description discloses internal cascading lookups, graceful degradation when GLEIF or OpenFIGI is unavailable, and explicit reporting of unresolved identifiers under `unresolved`. This provides valuable behavioral context that annotations alone do not convey.

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?

Although long, the description is front-loaded with user intents and a clear purpose statement. It is organized by supported types, with each sentence adding relevant detail about inputs, outputs, or failure behavior. No filler or redundancy is present.

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 entity types, multiple data sources, fallback logic) and the absence of an output schema, the description covers all essential aspects: expected outputs per type, source attribution, graceful degradation, and how unresolved items are represented. It is self-sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes far beyond by detailing the output identifiers associated with each `type` (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and expanding the accepted values for `value` (ticker, CIK, name, brand/generic). This adds substantial semantic meaning beyond the schema.

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

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

The description explicitly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example intents ('What's the ticker for…') and specifies supported types (company, drug), clearly distinguishing it from siblings like entity_profile or compare_entities.

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

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

The description gives direct usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details the supported types, accepted input formats, and which external sources are queried, making the tool's applicability unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions with annotations.

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

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

The description is three sentences: first states the primary action, second explains the internal process, third provides a use case and return format. No wasted words, front-loaded with the key purpose. Well-structured for quick comprehension.

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

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

Given the tool's complexity (multi-entity comparison, no output schema), the description adequately explains the return format (ranked list with score/confidence/signal density) and the relationship to ai_visibility_check. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds context that the first entity is treated as a 'subject' for narrative, but this is minor. It does not add significant new parameter-level meaning beyond the schema, so a 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 compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. It explicitly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the competitive AI-marketing audit 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?

The description provides a clear use case example ('does Claude know about us as well as our competitors?') and implies usage for competitive audits. It does not explicitly state when not to use it or name alternative tools, but the context from sibling tools and the description itself offers sufficient guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical context: partial failures degrade gracefully, first bundlephobia measurement can take 5-30s, sources_failed list on timeout. 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?

Description is relatively long but each sentence adds value. It's front-loaded with purpose, then usage, ecosystem, and failure behavior. Minor redundancy could be trimmed but overall efficient.

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

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

No output schema, so description must explain return values. It does: summary block fields, per-advisory detail, links, alternative versions. Also covers ecosystem constraints and graceful degradation. Fully complete given tool complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra context beyond schema: scoped packages accepted, version defaults to latest, and composite fan-out behavior.

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 identifies it as a composite check for npm packages, fanning out to deps.dev and bundlephobia. It specifies the purpose ('should I add this npm package to my project') and distinguishes from siblings by being the only tool focusing on dependency scanning.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also notes NPM-only in v1 and directs to deps.dev:version for other ecosystems.

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

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

Annotations already cover safety traits (readOnly, openWorld, idempotent). Description adds specific technical details: BGE-base-en embeddings, 500-char windows, 200K char cap with truncation flag. Does not contradict annotations.

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

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

Description is somewhat long but every sentence adds value, with key information front-loaded. Could be slightly trimmed, but effective.

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

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

Given rich annotations and schema, the description fully covers behavior, limits, and usage context. No output schema needed for this simple search tool.

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

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

Schema has 100% coverage, so baseline 3 is appropriate. Description adds example queries and char limit clarification, but schema already handles parameter documentation adequately.

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

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

The description clearly states it performs semantic search inside a fetched record, with examples like SEC 10-K body. It distinguishes from siblings (e.g., ask_pipeworx_grounded) by explaining its role in the workflow.

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 ('record too big to cram into the prompt') and notes it pairs with ask_pipeworx_grounded. Provides clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., covering safety. The description adds that it is 'Keyless' (no API key required) and details the product links included, providing additional context beyond annotations.

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

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

Two sentences with no wasted words. The purpose is front-loaded with the key verb and resource, followed by specifics and the keyless note.

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 one parameter, full schema coverage, and comprehensive annotations, the description covers all necessary context: what it does, how to specify the storm, what data is returned, and authentication status.

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%. The description adds value by providing explicit examples ('al052026', 'Douglas') inline, clarifying the parameter format beyond the schema's short 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 uses a specific verb ('Full details for one active storm') and clearly identifies the resource (storm by id or name), with examples of id format and name. It distinguishes from sibling 'active_storms' which lists storms.

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

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

The description implies usage when complete details on a specific storm are needed, but does not explicitly state when not to use or mention alternatives beyond the implicit contrast with 'active_storms'. Still clear enough for effective 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?

Adds significant behavioral context: auth requirements, type-specific filters, delivery channels with limitations (e.g., SMS cap, phone verification). However, description implies non-idempotent creation, contradicting idempotentHint=true annotation.

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 comprehensive but slightly verbose. Information is front-loaded with purpose and return value, then details. Could be more structured with bullet points.

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 (3 params, nested objects, no output schema), the description is thorough. It covers return value, auth, limitations, examples, and behavior for each type and delivery channel.

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 substantial meaning: explanations for each subscription type with concrete examples, delivery channel details, and verification steps. This goes well beyond the schema.

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

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

Description clearly states the tool creates a subscription to a live-data event stream and returns a subscription ID. It differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides explicit context on when to use (proactive monitoring), required authentication (Pipeworx OAuth account), and limitations (anonymous/BYO cannot persist). Lacks explicit 'when not to use' or direct comparison to alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it returns category-bucketed example questions with specific tool+argument shapes, and explains that it draws from a live catalog. No contradictions with annotations.

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

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

The description is relatively long but front-loaded with the core purpose ('onboarding entry point'). Every sentence adds value—examples, clarifying contrast with siblings, and parameter guidance. Could be slightly more concise, but no wasted words.

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

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

Given no output schema, the description thoroughly explains what the tool returns (category-bucketed example questions with tool+argument shapes). It covers the tool's use case, parameter usage, and relationship to siblings. With annotations providing safety context, this is fully adequate for an agent to use the tool correctly.

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

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

Schema coverage is 100% for the single 'topic' parameter, with a description in the schema. The description provides examples of valid topic values (e.g., 'finance', 'pharma') and explains the effect of omitting it (full spread), but this is not essential beyond what the schema already conveys. 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 identifies the tool as an onboarding entry point for suggesting questions about Pipeworx, using multiple natural language examples and explaining the output (category-bucketed example questions with tool+argument shapes). It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by being the first step when the agent doesn't know what Pipeworx can do.

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 to 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It provides context on when to call with or without the topic parameter and references alternatives like ask_pipeworx, entity_profile, etc., giving clear guidance on 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 show readOnlyHint=false and destructiveHint=false, but description adds critical info: ownership enforcement, row deactivation (not deletion), and historical data preservation. All neutral 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 sentences totaling ~30 words, front-loaded with action. Every word adds value with no redundancy.

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

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

For single-parameter tool with no output schema, description covers ownership, side effect (deactivation), and historical data retention. Fully adequate for agent selection and invocation.

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

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

Schema covers 100% of parameters with 'id' description. Description adds that the id comes from 'subscribe', providing useful lineage context beyond schema alone.

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

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

Description explicitly states 'Cancel a subscription by id' with clear verb-resource pairing. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by noting ownership enforcement and deactivation behavior.

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?

Indicates when to use (cancel own subscription), ownership prerequisite, and what happens to historical events (available via 'recent_alerts'). Provides clear context with alternative reference.

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

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

Annotations provide readOnly/openWorld/idempotent/non-destructive hints. The description adds critical context beyond these: the meaning of 'could_not_verify' as a failure mode with verification_error, the distinction between 'unsupported' and 'could_not_verify', and the internal routing behavior. 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 lengthy but dense; every sentence serves a purpose—examples, use cases, pipeline explanation, return values, and critical caveats. It front-loads with natural-language triggers and ends with important caller warnings. Slightly verbose but justified for the tool's complexity.

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

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

With no output schema, the description fully covers return values: six verdicts, actual value with pipeworx:// citation, and reasoning. It also explains error semantics (could_not_verify) and unsupported cases. Combined with rich annotations and complete schema coverage, nothing essential is missing.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (claim and tolerance_pct). The tool description does not add new parameter semantics beyond the schema; it only indirectly references the tolerance via 'exact percent-delta math.' 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's function: natural-language claim verification against authoritative sources, with a specific verb ('verify', 'fact check') and resource. It distinguishes itself from siblings by focusing on checking factual claims and describes a structured pipeline for company-financial claims versus a grounded fallback for all others.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains when the structured vs. grounded path applies. It also notes it replaces 4–6 sequential calls, implying an efficiency motive. It does not explicitly name alternatives to avoid, but the guidance is strong.

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