Bandsintown

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Beyond that, the description adds valuable behavioral context: the default model is 'Workers AI Llama-3.3-70b (free)', and using Anthropic requires a BYO key with direct payment to Anthropic. It also outlines the return structure. 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 long, front-loaded with the primary action and output, and every sentence contributes useful information: purpose, default behavior, cost caveat, return format, and use cases. No wasted words.

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

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

Given the tool's moderate complexity, the description covers all essential dimensions: purpose, default model, optional Anthropic integration, cost, return structure, and example use cases. The schema is thorough and annotations cover safety, so the description is fully adequate for an AI agent to select and invoke this 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 the baseline is 3. The description adds meaning beyond the schema by naming the specific default model ('Workers AI Llama-3.3-70b') and explaining the cost flow for `_apiKey` ('you pay Anthropic directly'), which is not fully explicit in the schema's 'Passed straight through to api.anthropic.com.'

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 opens with the specific verb 'Probe' and a clear resource ('one or more LLMs for what they know about a business / brand / product / topic') and an outcome ('score visibility (0-100) per model'). It clearly distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on visibility scoring rather than Q&A or research.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional `_apiKey` to enable Anthropic probes. However, it does not explicitly mention when not to use the tool or directly compare with sibling alternatives like scan_competitor_ai_presence.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: it mentions the tool 'fills arguments', returns 'stable pipeworx:// citation URIs', is 'one fast call', and 'works on every tier'. These details help the agent set expectations without contradicting 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 serves a purpose: usage guidance, alternatives, examples, and output traits. It is front-loaded with 'PREFER OVER WEB SEARCH' and uses structured formatting (plain text, emphasis via capitalization, examples) to maximize scannability without wasting 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 meta-tool with no output schema, the description thoroughly covers what the tool does, when to use it, how it behaves, what output to expect (structured answer with citation URIs), and clear alternatives. It even explains the 'one fast call' nature, fulfilling the need for a complete, self-contained description.

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

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

Schema description coverage is 100% (all 6 parameters are documented, with 'question' described as accepting aliases). The description adds example questions but no additional parameter semantics that aren't already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it routes questions to thousands of tools and returns structured answers with citations. It uses specific verbs ('Routes', 'returns') and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point for factual queries.

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

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

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...'), exclusions, and alternatives ('Step up only when needed: ask_pipeworx_grounded, deep_research'). It even gives concrete examples of suitable queries, making it easy for an agent to decide.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds context about experimental routing improvements, the current inactive candidate state, and the fact that results are compared for merging decisions. This goes beyond annotations by explaining the dynamic nature and current behavior without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence carries meaningful information. It efficiently communicates the beta nature, current equivalence to stable, and usage context without redundancy.

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

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

No output schema exists, but the description states 'same response shape' as ask_pipeworx, providing sufficient context for an agent familiar with that tool. It also explains the current state and that it's a full working router, covering potential concerns about experimental behavior. It could slightly improve by describing the response format explicitly, but it's adequate given the reference to the stable sibling.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question'. The description merely references 'same arguments' without adding new semantics or usage details beyond what the schema already provides. Baseline of 3 is appropriate since the schema handles parameter documentation fully.

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 this is a beta version of ask_pipeworx, a universal router with the same 5,564 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements, making its purpose specific and distinct from siblings.

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

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

It gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison against the stable router and clarifies it's a full working router with no fallback. This tells the agent exactly when to choose this over the stable version.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds critical behavioral context: uses grounding, returns refusal reasons when data doesn't directly answer, and costs an extra LLM call. It doesn't explain how evidence is extracted in detail but goes beyond annotations.

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

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

The description is dense but well-structured: starts with the core purpose, explains behavior, gives usage examples, and ends with a cost-vs-alternative note. It's long but every sentence adds value; could be slightly tighter but not wasteful.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It explains the return format (answer, evidence, confidence, source, etc.), potential refusal reasons, and when to use which mode. This fully compensates for the missing output schema and is sufficient for an agent to decide and invoke correctly.

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

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

Schema covers all parameters (100%), including aliases. The description explains that the question is in natural language and that the schema handles aliases, but it doesn't add anything beyond that. However, with full schema coverage, the baseline is 3, and the description's emphasis on natural language adds slight value, so 4 is justifiable.

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's a 'hallucination-resistant answer mode' for high-stakes reads, differentiating from ask_pipeworx by emphasizing grounded extraction and refusal behavior. It specifies the verb (ask) and resource (pipeworx), and distinguishes from siblings like ask_pipeworx_beta.

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 answer will be quoted, cited, or acted on' with examples) and when not to ('prefer ask_pipeworx for casual lookups'), and mentions the extra cost trade-off. This is exemplary usage guidance.

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

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

Annotations only declare readOnlyHint/openWorldHint/idempotentHint. The description goes far beyond, explaining resolver confidence levels (high/medium/low/none), blocking behavior on low-confidence closures, illiquid wide-spread warnings, cancellation-rule risk parsing, and fan-out logic. 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 and dense, but each section (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) earns its place by providing unique, actionable details. Uppercase section headers aid scanning. It is not concise word-for-word but is appropriately structured 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 thoroughly compensates: response shapes (market/analysis/evidence), resolver contract, parent_event extractor for partition bets, news fallback fields, safety overrides (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. This is highly complete for an agent to trust and use.

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

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

Schema covers 100% of parameters, but the description adds context: how the market parameter can be a slug/URL/question text, the meaning of 'quick' vs 'thorough' depth (via fan-out examples), and include_raw's size implications. This enriches the schema without contradicting it.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb+resource+scope that clearly distinguishes it from siblings like 'polymarket_edges' or 'validate_claim'. It also lists concrete use cases ('should I bet on X', 'what does the data say about Y') further cementing its purpose.

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

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

Explicitly states when to use the tool: 'Use for "should I bet on X"...' and provides input format guidance (slug, URL, or question text). It does not name alternative tools to use instead, but the usage context is clear enough. Lacks explicit when-not-to-use guidance, so a 4 rather than 5.

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

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

Beyond the read-only/idempotent annotations, the description discloses exactly what data is pulled for each type (SEC EDGAR/XBRL financials for companies, FAERS/FDA/trial counts for drugs), how off-calendar fiscal years are handled, sorting behavior, and the return format with citation URIs. This goes well 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 front-loaded with common query phrasings, then proceeds to key operational details. Every sentence contributes value—no filler or redundancy—making it dense yet easy to parse.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description fully explains what the agent can expect: sorted results, paired data, and citation URIs. It also covers edge cases like off-calendar fiscal years, making it complete for 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?

While the schema covers 100% of parameters, the description enriches the 'type' parameter by detailing the specific fields and data sources for 'company' vs 'drug'. It also clarifies that 'values' accepts 2–5 entities, reinforcing the schema's min/max constraints with 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?

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like "Compare X and Y" and "X vs Y". It distinguishes itself from sequential single-pack lookups, making its specific purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also implies alternatives by contrasting with single-entity lookups, though it does not name the sibling tool directly.

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

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

Annotations already declare readOnly, idempotent, open-world; the description adds rich behavioral context beyond that: it returns a findings packet with evidence, confidence, gaps[], contradictions[], hop field, citation_uri, and never-invents guarantee. It also discloses timing and semantic excerpting behavior, with no contradiction to 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?

Despite its length, every sentence carries essential information: account requirement, purpose, alternatives, depth behavior, citation guarantees, and performance expectations. It is structured logically and front-loaded with the most decision-relevant constraints.

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 describes the return packet, gaps, contradictions, citation resolvability, and latency. It covers prerequisites, alternatives, and edge cases (current news leading to empty gaps), making it a complete specification for an agent.

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

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

The input schema already covers both parameters at 100%. The description adds practical interpretation: 'Broad/multi-part is fine — decomposition is the point' and explains depth variants' behavioral outcomes (gap recovery, contradictions) that go beyond the enum text, so it earns an above-baseline score.

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 and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call' and explains the decomposition/parallel routing mechanism. It explicitly distinguishes from ask_pipeworx for single lookups, 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?

It provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even gives an account prerequisite and fallback ('If you are not signed in, use ask_pipeworx instead'). Examples of best-fit questions are included.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by explaining the return payload (top-N tools with names, descriptions, full input schemas, and curated examples) and that results are 'ready to call directly, no second schema lookup needed.' This is useful behavioral context beyond the annotations, though it does not cover every edge case.

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

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

The description is front-loaded with the main purpose and then adds domain coverage, return details, and usage guidance. The domain list is a bit long but each item is informative. Overall, every sentence contributes, though the structure could be slightly more compact without losing value.

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

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

Given that this is a discovery tool with no output schema, the description covers all needed aspects: what it does, when to use it, what it returns, and how it fits into workflow ('Call this FIRST'). The lack of output schema is mitigated by describing the return structure (names, descriptions, schemas) and giving examples. This is complete for the tool's complexity.

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

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

The input schema has 100% description coverage, documenting query and its aliases as well as limit. The description does mention 'top-N' which loosely relates to the limit parameter, but it does not add meaning beyond the schema. Baseline of 3 is appropriate because the schema carries the semantic weight.

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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself as a meta-tool for discovering other tools, and the list of domains (SEC filings, financials, FDA drugs, etc.) adds specificity. This contrasts with sibling tools that are domain-specific, so purpose is unambiguous.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies the alternative of using a specific tool directly when you already know what you need.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but description adds substantial behavioral context beyond annotations: parallel fan-out across multiple APIs, specific return structure, patent API soft-fail behavior, and news fallback chain (GDELT→GNews). 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 well-structured and front-loaded with trigger examples. It packs many essential details (return fields, source APIs, limitations) without redundancy. It is slightly verbose but each segment serves a purpose for an agent deciding when to invoke.

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

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

No output schema exists, so the description fully compensates by enumerating all returned data components (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with specifics like filing URIs and sorted fundamentals. It also covers limitations and fallback behavior, making it complete for an agent.

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

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

Schema has 100% coverage, so baseline is 3. Description adds value by giving concrete examples (AAPL, 0000320193), specifying zero-padded CIK, and reiterating that names are not supported. This clarifies the value parameter format beyond the schema's description.

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

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

The description clearly states the tool's purpose: building a full cross-source profile of a US public company in one parallel call. It includes specific resource components (SEC EDGAR, XBRL, USPTO, news, GLEIF) and differentiates from sibling tools by explicitly saying to prefer it over chaining single-pack lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states clear exclusions: names are not supported and instructs to use resolve_entity first, giving a direct alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the rationale (e.g., clearing sensitive data) but does not disclose additional behavioral traits such as irreversibility or error handling. The description is consistent 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 concise sentences: action, usage cases, and related tools. Front-loads the operation and contains 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 the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, and relationships to siblings. Annotations cover safety, making it sufficiently complete for an agent.

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

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

The input schema fully describes the single 'key' parameter with an example and description. The tool description merely repeats 'by key' and adds no new parameter semantics, so the baseline of 3 applies given high schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb (delete) and resource (stored memory). It distinguishes from siblings like remember and recall by specifying the delete action.

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 gives three use cases: stale context, task completion, and clearing sensitive data. It names paired tools (remember and recall) but does not explicitly state when not to use this tool versus alternatives.

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

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

The description explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also describes the output ('single text blob ready to drop at site-root/llms.txt'). The annotations already convey read-only, open-world, and non-destructive behavior, and the description adds process details without contradicting them. It doesn't cover error handling or rate limits, but for this simple tool, the added context is substantial.

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

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

The description is concise and well-structured: it opens with the core action, then provides process details, output format, and example use cases in a list. Every sentence adds value, and there is no redundancy or filler.

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

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

With only 2 parameters, rich annotations (read-only, idempotent), and no output schema, the description covers the essential aspects: what it does, how it works, what it returns, and when to use it. It lacks details on edge cases like invalid URLs or site access issues, but for the tool's simplicity, it is fairly complete.

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

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

The input schema already provides 100% coverage: 'url' and 'max_links' are fully described with types and defaults. The description adds no additional parameter-level semantics beyond what the schema contains, so the baseline of 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?

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It uses a specific verb ('Generate') and resource ('llms.txt file'), and explains the purpose (helping AI crawlers index the site). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on checking presence rather than generating the file.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear contextual guidance on when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful context beyond this by specifying the exact return fields and the default behavior of returning active subscriptions only, with an option to include cancelled ones. No contradictions.

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

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

Two sentences, front-loaded with the core purpose and return fields, followed by practical usage guidance. Every word earns its place with zero 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, one-parameter list tool with read-only annotations, the description covers the purpose, return format, and usage scenarios. It is complete without needing to explain more complex behaviors.

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% since include_inactive has a clear description. The tool description does not add significant detail about parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'List' and resource 'active subscriptions', clearly distinguishing it from the sibling tools subscribe and unsubscribe. It also lists return fields, removing ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool: to review current monitoring before adding more subscriptions and to find an id for cancellation. This gives clear situational guidance and differentiates it from related tools.

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

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

Beyond the annotations (which are all false and unhelpful), the description discloses critical behavioral traits: filing without an account returns a claim_token for later retrieval, rate limiting (5 per identifier per day), free usage not counting against quota, and team digest/roadmap impact. It also warns against pasting end-user prompts, which is a non-obvious behavioral expectation.

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 delivers distinct value: purpose, when-to-use, exclusions, claim_token workflow, rate limits, and free status. It is front-loaded with the core purpose and logically organized. No filler or 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 4-param tool with nested objects and no output schema, the description fully explains the tool's behavior, including the response token flow and limitations. It covers the 'what happens when' aspects that the schema and annotations do not, making it complete for an agent to select and invoke correctly.

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

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

The schema already provides 100% coverage with detailed descriptions for every parameter, so the baseline is 3. The description adds meaningful usage semantics beyond the schema, particularly for claim_token (explaining the flow of passing it back later) and context (emphasizing to describe in terms of Pipeworx tools/packs). No param info is missing, so a 4 is warranted.

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 ('Tell') and clearly states the resource (Pipeworx team) and the categories of feedback (broken, missing, needs to exist). It distinguishes itself from sibling research/visibility tools by focusing on feedback about Pipeworx tools specifically.

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

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

The description provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' It also gives a how-to-determine guidances (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 mark readOnly/openWorld/idempotent/non-destructive, and the description adds valuable context: the data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5min-1h. This goes beyond the structured fields by informing freshness and privacy behavior.

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

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

The description is efficient and well-structured: one topic sentence, a concise returns list, a bulleted 'Useful for' list, and a brief data/caching note. Every sentence earns its place and no filler 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?

For a simple read-only tool with one optional parameter and no output schema, the description is highly complete. It covers purpose, use cases, data composition, privacy, and caching, which is sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% for the single optional window parameter, including an enum and descriptive text about short vs long windows. The description repeats the window values but adds no new semantic meaning beyond the schema, so the 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?

The description uses a specific verb 'Returns' and names the resource (Pipeworx trending), specifying that it returns top tools, top packs, and call volume over a window. It clearly distinguishes this aggregation-oriented tool from sibling discovery/search tools by emphasizing what other agents are calling. Purpose is immediately 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 'Useful for' bullets give three explicit contexts: discovering hot data sources, confirming canonical tool choice, and aligning use cases. However, it does not mention when not to use it or name an alternative tool, so it misses the highest bar for explicit exclusions/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?

Even with annotations already declaring readOnly, idempotent, non-destructive, the description adds substantial behavioral detail: the partition filter (drops placeholder slugs, null arb if >20%), semantic anchor (Jaccard similarity threshold), fill check (theoretical vs realizable edge, thin legs, warning not to trade if realizable edge <= 0), and response structure. This goes far 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 dense but well-structured. Key concepts are highlighted in caps (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for easy scanning. Every sentence contributes operational detail; no filler. The length is justified by 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 takes on the full burden of explaining return values, which it does thoroughly: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check fields. It also covers edge cases (placeholder filtering, thin legs, low similarity) and gives clear conditions under which not to trade. The description is highly complete for a complex, multi-mode 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: examples of event slugs and topic seed questions, explanation of what each mode does step-by-step, and guidance on which mode to prefer. It enriches the semantic understanding of both parameters significantly.

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

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

The description starts with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by describing its unique methodology and modes.

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

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

Explicit usage guidance is provided for each invocation pattern: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is exactly the level of when-to-use vs. alternatives guidance desired.

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

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

The description extensively discloses behaviors beyond annotations: it details three model families with specific parameters, response segments, diagnostics funnel counters, 24h-move warnings, caching keyed on knobs, and the Fed bets exclusion. This goes far beyond the readOnlyHint and idempotentHint annotations, providing agents with deep insight into internal workings and edge cases.

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

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

The description is extremely long and dense, packing many model-specific details into a single wall of text. While it uses capital-letter labels to separate sections, the sheer volume of jargon (e.g., 'per-sport α', 'GDELT 7d/21d', 'placeholder-slug filter') makes it difficult to parse quickly. A more concise summary would be more effective for agent decision-making.

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 (9 parameters, no output schema, multiple models), the description is remarkably complete. It explains the top-level response structure (by_segment, fed_candidates, _diagnostics), the knobs' effects, and the internal logic, leaving little ambiguity about what results to expect and why certain segments might be empty.

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

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

Schema coverage is 100% and each parameter already has a rich description (e.g., min_kelly explains the concept and default). The description adds a high-level 'TRADEABLE-EDGE KNOBS' section but does not provide more per-parameter detail than the schema, so it meets the baseline 3 without exceeding it.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's function and differentiates it from sibling tools like polymarket_arbitrage or polymarket_kalshi_spread by focusing on opportunity discovery from Pipeworx data, not just scanning or tracking.

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

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

The description gives clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also describes tradeable-edge knobs and diagnostics, but does not explicitly name alternative tools or when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: history limited by 60-day TTL, snapshot gaps due to cache-miss behavior, decay computed from daily closes (not intraday), and the meaning of expired entries. 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 long but well-structured with clear labels (Args, RESPONSE, LIMITS). Every sentence contributes necessary detail for a telemetry tool with no output schema. Slightly dense but appropriately sized for the complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), field semantics (trend values, decay_pp_per_day), and limitations (TTL, gap interpretation). It leaves no major ambiguity for an agent invoking this tool.

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

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

Schema coverage is 100% and describes both parameters (days, window) with defaults and clamps. The description repeats these defaults and adds the 'snapshot family' framing, but does not materially extend the schema's meaning. 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 states a specific verb ('answers') and resource ('edge persistence and decay telemetry from daily polymarket_edges snapshots'). It clearly differentiates from sibling polymarket_edges by focusing on temporal behavior ('how long has this edge existed and is it shrinking?'), which is a distinct analytical purpose.

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

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

The description gives clear context for when to use the tool — when edge age/decay matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implicitly separates from sibling tools by addressing historical persistence rather than current edges, but does not explicitly name alternatives or exclusions.

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

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

Despite strong annotations (readOnlyHint=true, idempotentHint=true), the description adds substantial behavioral detail: walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp), explains verdicts, and warns about forced directional risk from partial basket fills. 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 tightly packed; every sentence adds value. It uses bold headers (SINGLE-MARKET, BASKET) to structure complex dual-mode behavior and front-loads the core purpose. Appropriate length for the tool's complexity.

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

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

Given the tool's complexity and absence of an output schema, the description fully documents return values for both modes (top_of_book, vwap_fill_price, shares_filled, verdict; basket-specific capture_ratio, thin_legs[], max_clean_notional_usd). It also explains risk context and limitations, making it operationally complete.

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

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

Even though schema coverage is 100%, the description enriches parameter meaning: distinguishes single-market vs basket interpretation of size_usd (max spend vs target proceeds vs settlement notional), explains default side selection in basket mode, and clarifies that market/event accept slugs or URLs. This goes well beyond the schema descriptions.

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

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

The description leads with a specific verb+resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to position its scope.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create directional risk), giving clear exclusions 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 indicate a safe read-only, idempotent operation, but the description goes far beyond by detailing exact conditions for compatibility_warning, temporal_alignment semantics, and skipped_cross_type/subtype counters. It openly admits when spreads may be mathematically meaningless, adding substantial behavioral context that the annotations lack.

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 excellently structured: a single-sentence definition, then labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries meaningful information, and the front-loading ensures the core purpose is immediately clear. It is appropriately detailed 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 compensates by explaining the response shape (leg-by-leg prices, top_spreads_pp), safety fields, and edge cases. It covers potential failure modes (compatibility_warning conditions) and temporal misalignment, making the tool self-sufficient 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?

The schema already provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds value by explaining the override behavior ('Overrides the topic-mapped Kalshi side') and the concept of 'pre-mapped' shortcuts, which enriches understanding beyond the schema.

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

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

The description opens with a specific, unambiguous definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from siblings by focusing on cross-venue spread and explaining the two operating modes (topic shortcuts vs. explicit tickers), making its 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 guidance by explaining the two modes and warning that 'pre-mapped ≠ tradeable' and that 'most pre-mapped topics return compatibility_warning today.' It also explains when spreads are meaningful versus meaningless, but it does not explicitly name alternative sibling tools or state 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 readOnly, idempotent, non-destructive behavior. The description adds meaningful context beyond that, including scoping by identifier ('Scoped to your identifier...') and the list-all-keys behavior when key is omitted, which is not fully captured by the schema or 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?

Every sentence earns its place: the first states the core function, the second gives usage context, the third explains scoping, and the fourth relates it to siblings. There is no redundancy or filler.

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

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

For a simple 1-parameter read tool with no output schema, the description fully covers both invocation modes, data isolation, and the tool's place in the workflow. Combined with strong annotations, it is complete enough to guide correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the 'key' parameter with concrete examples ('user's target ticker, an address, prior research notes') and reiterates the omission rule, adding conceptual meaning beyond the schema's terse description.

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

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

The description clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes from sibling tools by explicitly contrasting with 'remember' and 'forget' in the final sentence, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the alternatives (remember, forget) and explains how they pair, giving clear context and exclusions.

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

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

The description discloses a side effect with mark_read:true that flags events as read and affects subsequent calls, which contradicts the annotation readOnlyHint=true. This is a clear inconsistency between the declared read-only nature and the described state mutation, so the description's transparency is undermined by the annotation mismatch.

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 long, front-loaded with the core action, and every sentence adds value: purpose, return payload, filtering options, side effect, and external alternative. There is no filler or redundancy.

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

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

Despite lacking an output schema, the description explains what each returned alert carries (source, citation_uri, raw payload) and covers filtering and read-state behavior. It does not clarify interactions between mark_read and unread_only, but given the tool's moderate complexity and rich annotations (aside from the contradiction), the description is sufficiently complete.

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

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

The input schema already documents all five parameters with 100% coverage, and the description adds meaningful context beyond those descriptions, such as explaining the effect of mark_read, the format for since (ISO timestamp), and an example type (sec_8k). It enriches the parameter semantics without duplicating schema text.

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: 'Pull fired events from your subscription feed.' It identifies the resource (subscription feed) and the specific action (retrieving alerts), and differentiates from sibling tools like list_subscriptions or recent_changes by focusing on alert event payloads and read-state semantics.

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 practical usage context: polling is acceptable, and an alternative external endpoint is given for scripts/dashboards. It implies this tool is intended for agent-driven retrieval, but it does not explicitly contrast with sibling tools or specify when not to use it, which keeps it a notch below a perfect score.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial contextual behavior: the fan-out to SEC/GDELT/GNews/USPTO, the fallback logic, the PatentsView sunset soft-fail, and the return format with citation URIs. This goes far beyond annotation safety flags.

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

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

The description is dense but every sentence earns its place: usage examples, operational details, fallback behavior, parameter guidance, and a sibling differentiation. It is structured logically from examples to mechanics to alternative, without redundancy.

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

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

With no output schema, the description explicitly covers return values ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also addresses external dependencies and failure modes for each data source, making it complete for selecting and invoking 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. The description adds meaningful guidance beyond the schema: it explains `since` formats with examples, recommends '30d' or '1m' for typical monitoring, and clarifies that `value` can be a ticker or CIK. This elevates the score to 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 clearly states it provides a 'change feed for a company in the last N days/weeks/months' and lists concrete example queries. It also differentiates from the sibling tool entity_profile by contrasting dynamic changes vs static profile.

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

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

Provides explicit when-to-use examples ('What's new with X', 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' Also describes fallback behavior (GDELT → GNews) and soft-fail conditions.

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

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

Beyond annotations (idempotentHint, readOnlyHint, destructiveHint), the description discloses key behavioral details: data is stored as a key-value pair scoped by the agent's identifier, persists across sessions for authenticated users, and expires after 24 hours for anonymous sessions. This adds meaningful context without contradicting any annotations.

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

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

Five sentences, each with a distinct purpose: function, trigger, mechanism, persistence, and companion tools. No fluff or repeated information. The description is front-loaded with the core action and stays tightly 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?

For a simple write-only tool, the description is complete: it explains what to store, when to use it, how the storage works, retention rules, and how it relates to sibling tools. No output schema is needed, and the description covers all necessary operational aspects.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces semantics by explaining the key-value relationship ('Stored as a key-value pair scoped by your identifier') and providing real-world examples of values to store. It does not add new syntax or format details, but complements the schema enough to earn 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 clearly states a specific verb and resource: 'Save data the agent will need to reuse later.' It immediately distinguishes the tool from siblings by naming 'recall' and 'forget' as complementary operations, and describes a key-value memory store scoped by identifier.

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

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

Explicit 'Use when' conditions are given with concrete examples (resolved ticker, target address, user preference, research subject). It also states when not to use it implicitly by pointing to recall (retrieve) and forget (delete) for other stages. Persistence differences between authenticated and anonymous sessions provide additional decision 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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds meaningful behavioral context: 'LEI/FIGI enrichment degrades gracefully', 'Each call cascades through several lookup endpoints internally', and 'unresolved identifiers are stated explicitly rather than omitted'. This goes beyond the annotations without contradicting them, earning a 4.

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

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

The description is front-loaded with user-facing query examples, which quickly orients the agent. While it is relatively long (multiple paragraphs), each sentence adds value—covering supported types, input formats, graceful degradation, and internal cascading. It earns a 4 for being informative without redundancy, though it could be slightly more concise.

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

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

For a complex tool with no output schema but 100% param coverage and comprehensive annotations, the description is remarkably complete. It explains the resolution process, supported identifiers per type, fallback behavior, and even notes that unresolved items are listed explicitly. This fully equips an agent to use the tool appropriately without needing external documentation.

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

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

Schema description coverage is 100% (both parameters have descriptions). The description adds significant value beyond the schema: it explains what each 'type' resolves (company: CIK, ticker, LEI, FIGI; drug: RxCUI) and provides explicit input examples for 'value' (e.g., 'AAPL', '0000320193', 'ozempic'). This compensates for the lack of an output schema and clarifies the resolution 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?

The description defines the tool's purpose with specific verbs and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input'. It provides concrete examples ('What's the ticker for…') and enumerates supported entity types ('company', 'drug') with clear resolution scopes. This makes it highly distinguishable from sibling tools like 'compare_entities' or 'entity_profile', even without explicit differentiation.

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

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

The description explicitly states when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. However, it lacks explicit when-not-to-use guidance or direct comparisons to siblings (e.g., 'use entity_profile after resolving an ID'). The clear context of being a first-step resolution tool still earns a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds value by disclosing the process (probes each entity with ai_visibility_check, ranks by score) and the return format (ranked list with score, confidence, signal density). This goes beyond annotations without contradicting them.

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: the first states the core function, the second gives a use case and the output. No filler, front-loaded with the primary action. Extremely 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?

With no output schema, the description explicitly states what is returned: 'ranked list with score, confidence, signal density per entity.' It covers the competitive comparison context and references the underlying probe tool. For a moderate-complexity tool with good parameter schema and annotations, this is fully complete.

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

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

Schema coverage is 100% with all four parameters described, including entities' first-entry-as-subject nuance. The description does not add meaning beyond the schema—it echoes 'your brand + N competitors' but the schema already covers that. With full schema coverage, 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 opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from sibling tool ai_visibility_check (single entity probe) by focusing on side-by-side comparison and ranking, and from compare_entities by explicitly tying to AI visibility and using ai_visibility_check as the probe.

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

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

The description gives a concrete use case: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use this tool instead of ai_visibility_check (for comparisons), but does not explicitly state when not to use it or name alternatives as exclusions. The context is clear, though alternatives are not spelled out.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds valuable behavioral context: partial-failure degradation, potential 5-30s latency for bundlephobia's first measurement, and the sources_failed field. No contradiction with annotations.

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

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

The description is dense but well-organized: purpose, trigger usage, return fields, ecosystem limitation, and failure behavior each get a distinct sentence. There is no fluff, and the length is justified by the tool's composite nature.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It lists the exact summary fields returned, explains edge cases like timing out, and states ecosystem boundaries clearly.

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

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

Schema coverage is 100% for the two parameters, so the description doesn't need to restate them. It adds high-level context by tying parameters to the composite check, but it does not introduce new parameter-level semantics beyond what the schema already documents.

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 opens with a clear composite-purpose statement and enumerates exact data sources (deps.dev + bundlephobia). It distinguishes itself from sibling tools by framing the tool as a one-call npm-package evaluation for safety, popularity, and size.

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 trigger phrases are given: 'Use whenever an agent asks...' with concrete examples like 'is X safe / popular / small'. It also clarifies when NOT to use it (non-NPM ecosystems) and points to an alternative, deps.dev:version.

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, non-destructive, idempotent behavior. The description adds substantial behavioral context: returns character offsets and similarity scores, uses BGE-base-en embeddings over 500-char overlapping windows, and enforces a 200K char cap with truncation flagging. 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 somewhat dense but well-structured, with each sentence contributing: purpose, use case, companion tool, and technical details. It earns a 4 rather than 5 because the sentence about embeddings and windowing could be seen as more than necessary for tool selection, though it is useful transparency.

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 must explain return values, and it does: 'top-N passages with character offsets and similarity scores.' It also covers input limits and truncation behavior. For a 3-parameter tool with full schema coverage and explicit annotations, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context—'text you already pulled,' 'natural-language query,' 'top-N passages'—but these mostly rephrase the schema descriptions. It does not materially deepen parameter meaning beyond what the schema already communicates.

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

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

Clear verb+resource: 'Semantic search INSIDE a fetched record.' Explicitly distinguishes from siblings by emphasizing it operates on already-fetched text, and it names ask_pipeworx_grounded as a companion tool. The examples (SEC 10-K, article, long tool result) reinforce the intended resource.

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?

Gives explicit when-to-use: 'Use when the record is too big to cram into the prompt.' Also provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This directly addresses tool selection versus siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds valuable behavioral context: OAuth requirement, phone verification, SMS daily cap, and the fact that the feed is always on. These details go beyond the structured annotations and help set expectations for side effects and constraints.

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 well-structured, starting with purpose, then what it returns, then prerequisites, supported types, and delivery options. Every sentence adds necessary context for a complex subscription tool, though a slight tightening could improve scannability.

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, the description covers return value, authentication requirements, event types, delivery channels, and how to consume the feed. It also references alternative usage (pulling via recent_alerts) and the schema provides full parameter details, making the description comprehensive enough for a 3-parameter tool.

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

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

Schema description coverage is 100%, and the description largely mirrors the schema's explanations (e.g., supported types and delivery examples). It adds a few clarifications like the meaning of item codes and the 10/day SMS cap, but overall it does not significantly enrich beyond the schema, so a 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on the act of subscribing and returning the new subscription id.

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

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

Provides explicit when-to-use guidance by contrasting proactive subscriptions with the always-on feed that can be pulled via recent_alerts or the registry URL. It also states prerequisites (OAuth account, phone verification) and lists supported event types with concrete examples, giving agents clear context for selection.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable behavioral context beyond that: it explains the output is category-bucketed example questions derived from a live catalog, and that calling with no arguments returns the full spread while passing topic focuses results. This richer behavioral disclosure complements the annotations without contradicting them.

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 substantial paragraph, but it is well-structured: it opens with natural-language examples, then explains the return format, the optional parameter, and the recommended usage. Every sentence earns its place, though it is verbose compared to simpler tools. The front-loading of example queries aids 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?

With no output schema, the description fully compensates by explaining the return shape (category-bucketed example questions with tool+argument shapes) and the source (live catalog). It covers the parameter behavior, the categories, and the usage scenario. The description is complete for an onboarding/discovery tool with simple optional parameters and rich intent.

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 describes the topic parameter with valid examples (finance, pharma, etc.), giving 100% coverage. The description adds meaning by explaining the parameter's purpose: 'pass topic (e.g. "finance", "pharma", "betting") to focus.' It also clarifies the default behavior when omitted, which the schema implies but doesn't state. This goes beyond the schema's basic type/description.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with the exact tool and argument shape for each. It distinguishes itself from siblings like ask_pipeworx by positioning itself as 'the onboarding entry point' for discovering what to ask. Specific verbs like 'returns' and 'use FIRST' make the function unambiguous.

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

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

The description explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter for focusing the results. While it doesn't explicitly state when not to use it, the 'FIRST' directive gives clear contextual guidance relative to sibling tools.

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

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

Beyond annotations, it discloses ownership enforcement and the exact semantics of deactivation (row deactivated, not deleted) and its impact on recent_alerts. This adds significant behavioral context that annotations alone do not 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-load the action and immediately cover key constraints. No filler or redundant information.

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

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

For a single-parameter, non-destructive mutation with annotations present, the description fully covers the action, ownership rule, deactivation behavior, and effect on historical data. It is appropriately complete for 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?

The schema already fully describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe' (100% coverage). The description's 'by id' adds no new meaning, so the 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 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by adding ownership and deactivation details.

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 clarifies that ownership is enforced and that deactivation (not deletion) preserves historical events, which implicitly indicates when to use this tool and what side effects to expect. However, it does not explicitly name alternative tools like list_subscriptions for finding subscription IDs.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: it explains the two execution paths, the exact verdict list, and critically distinguishes 'could_not_verify' (process failure, not evidence) from 'unsupported' (no source coverage). This error-handling nuance is essential for correct caller behavior and goes well 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 long but every sentence is purposeful. It front-loads natural-language triggers to help an agent recognize when to invoke the tool, then proceeds logically through purpose, pipeline routing, output details, critical caveats, and efficiency note. The structure is well-organized with no filler or repetition.

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

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

There is no output schema, so the description carries the burden of explaining return values. It enumerates the verdicts, mentions the actual value with citation, and describes reasoning. It also covers edge cases like 'could_not_verify' and 'unsupported', which are crucial for correct handling. Given the tool's complexity, the description is comprehensive and self-sufficient.

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

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

Schema description coverage is 100% with detailed descriptions for both 'claim' and 'tolerance_pct' (including valid range and default). The tool description adds context about 'exact percent-delta math' and tolerance implied by wording, but these are also reflected in the schema's parameter descriptions. Therefore the description does not significantly enhance parameter understanding beyond the schema, fitting the baseline of 3.

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

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

The description clearly and specifically defines the tool as natural-language claim verification against authoritative sources, with examples of user phrasings like "fact check" and "verify the claim that…". It distinguishes itself from sibling tools by describing a composite operation that replaces multiple sequential steps and by detailing the two distinct verification pipelines (SEC EDGAR for company-financial claims, grounded pipeline for everything else).

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

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

It provides an explicit when-to-use statement: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the decision path between structured financial verification and the fallback grounded pipeline. However, it does not explicitly state when not to use the tool or name alternatives (e.g., deep_research for open-ended research), so it falls short of the 'when-not/alternatives' bar.

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