Threatfox

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds return format details and cost implications (free vs paid), but no additional behavioral traits like rate limits or error handling. With annotations covering core safety, a 3 is appropriate.

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

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

The description is concise (3 sentences) and front-loaded with the primary purpose. It efficiently covers key points without redundancy, though could be slightly more structured with bullets.

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

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

Given no output schema, the description adequately explains return format (per-model object + combined view) and covers all parameters. It includes use cases. Missing minor details like error handling, but sufficient for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds context (e.g., default model, API key purpose) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for entity knowledge and outputs a visibility score, with specifics on default model and optional Anthropic. It distinguishes from siblings like 'ask_pipeworx' but does not explicitly differentiate from the similar 'scan_competitor_ai_presence', so not a full 5.

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

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

The description explains when to use (AI-marketing audits) and how to configure models, but does not mention when to avoid it or provide explicit alternatives among sibling tools 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 establish read-only, open-world, idempotent, non-destructive traits. The description adds valuable behavioral context: it routes to an internal tool ecosystem, auto-fills arguments, and returns structured answers with stable citation URIs. This goes beyond 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 longer than average, but the extra length is mostly justified by the tool's broad scope: domain list, routing behavior, trigger phrases, examples, and a default-recommendation note. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and organized logically, though a few phrases are slightly redundant.

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

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

There is no output schema, but the description compensates by specifying that the return value is a structured answer with stable citation URIs. It covers domains, trigger phrases, examples, and default usage. The main completeness gap is the lack of explicit guidance on sibling tool selection, especially ask_pipeworx_grounded and deep_research.

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 documents the single 'question' parameter and its aliases at 100% coverage. The description adds semantic guidance by listing trigger phrases and numerous real-world example questions, which helps the agent formulate appropriate natural-language inputs. It does not repeat schema details but complements them effectively.

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

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

The description clearly states the tool's function: it routes natural language questions to one of 5,798 tools across verified sources and returns structured answers with pipeworx:// citation URIs. It gives concrete examples and distinguishes itself from general web search, but it does not explicitly differentiate itself from closely named siblings like ask_pipeworx_grounded or 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?

The description gives explicit when-to-use guidance: prefer over web search for factual/real-world questions, use for trigger phrases like 'what is', 'look up', 'get the latest', and 'START HERE for most questions'. It also addresses the breaking-news edge case. However, it does not explicitly state when to choose sibling tools such as ask_pipeworx_grounded or deep_research.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it is an experimental edge, candidate improvements are enabled live only when under test, no candidate is currently active, and it is a full working router rather than a fallback stub. This is honest and informative.

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 core identity and beta status, then adds current-state transparency and usage guidance. It is slightly wordy with parenthetical details like '5,798 tools' and the retirement date, but each sentence earns its place and the structure is logical.

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 universal router with no output schema, the description covers the key operational facts: identical to stable, experimental routing, current no-candidate state, live comparison process, and full functionality. It does not explicitly describe the response shape, but 'same response shape' ties it to ask_pipeworx, which is reasonable given the stable sibling exists.

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 every parameter documented as an alias for 'question'. The description adds no parameter-specific meaning beyond saying the arguments match ask_pipeworx, which is acceptable given the schema already fully covers semantics.

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

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

The description clearly states that this is a beta version of ask_pipeworx and an identical universal router over 5,798 tools with the same arguments and response shape. It differentiates itself from the stable ask_pipeworx sibling by its experimental routing status, though it relies somewhat on knowing what ask_pipeworx 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?

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving a clear selection criterion. It does not explicitly say when not to use it or name alternatives like ask_pipeworx_grounded, but the 'when you want the newest routing' instruction provides solid practical guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral disclosure beyond that: it returns a specific success shape with a verbatim evidence quote, and an explicit refusal object with enumerated refusal_reason values. It also discloses the operational cost (one extra LLM call) and the constraint that answers are extracted only from tool results. 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 every sentence earns its place: purpose, routing behavior, exact output/refusal shape, usage guidance, and cost trade-off. The most important qualifier ('hallucination-resistant... high-stakes') is front-loaded. Though long, it is efficiently structured for an AI agent evaluating whether to call this tool.

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 there is no output schema, the description fully compensates by specifying the return object fields and all refusal_reason enum values. It also covers the alternative tool, cost, intended use cases, and behavioral constraints. An agent has everything needed to decide whether to call this tool and what to expect from it.

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

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

Schema description coverage is 100%, so the input schema already fully documents the single actual parameter (question) and its five aliases. The description adds contextual framing about 'fills arguments' and routing, but it does not need to add parameter-level semantics because the schema carries the full burden. This meets the baseline for high schema coverage 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 immediately identifies this as a 'hallucination-resistant answer mode for high-stakes reads,' naming a specific behavior (grounded extraction from tool results) and a concrete resource (Pipeworx). It clearly distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_beta by emphasizing evidence-backed answers and explicit refusals. The purpose is unmistakable even before reading the parameter schema.

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

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

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' naming the alternative and the deciding condition. It also warns about the extra LLM call cost, giving the agent an explicit trade-off for tool selection. This leaves no ambiguity about when to invoke grounded vs. the normal sibling.

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 is exceptionally transparent about behavior: it explains market resolution, classification, fan-out, edge warnings, resolver contract (match confidence alternatives), parent event extractor, news fields with fallback handling, safety short-circuits, spread warnings, and resolution-rule risk. Annotations (readOnlyHint, idempotentHint) are consistent; description adds critical context beyond 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 very long (multiple paragraphs) but well-organized with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). While every sentence adds value, it is not concise; a shorter version could achieve the same clarity. Structure is good but length reduces conciseness.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is extremely complete: it covers input formats, behavior, edge cases, response shapes, warnings, and even resolution rules. No gaps remain for an agent to invoke the tool correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds significant meaning: it explains the 'depth' enum (quick vs thorough), details the 'market' parameter (slug, URL, or question text), and clarifies 'include_raw' (default false for summarized responses). This goes beyond the schema's definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). However, it does not differentiate from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage' even though they appear in the sibling list.

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

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

The description provides explicit use cases ('Use for "should I bet on X"...') but does not exclude alternative tools or state when not to use this tool. It implies usage through examples and blocking conditions (low confidence, closed markets) but lacks direct comparison to siblings.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, etc. The description adds rich behavioral context: explains that company data comes from SEC EDGAR/XBRL with specific financial metrics and handles off-calendar fiscal years; for drugs, pulls FAERS counts, FDA approvals, active trials. Also mentions sorting by primary metric and citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads usage phrases. All sentences are informative with no fluff. Constrained to meet character limits but could benefit from slightly more structure (e.g., bullet points).

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

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

Despite no output schema, the description explains return value: 'paired data + pipeworx:// citation URIs per entity' and clarifies sorting by primary metric. It covers what data is pulled per type, which is complete for a tool with two simple parameters.

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

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

Schema coverage is 100%, and the description adds meaning beyond enum values and array constraints: for company it specifies 'tickers/CIKs' with examples; for drug 'names' with examples. It also explains what data types are retrieved per parameter choice. Minor improvement possible but sufficient.

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 explicit use-case phrases like 'Compare X and Y' and 'head to head', clearly stating it provides side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sequential single-pack lookups, making the purpose specific and 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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also separates company vs drug use cases, detailing what data each type retrieves.

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 readOnly/openWorld/idempotent annotations, the description adds substantial behavioral context: account authentication, paid plan requirement for 'thorough', parallel decomposition across tools, gaps[] for unanswered facets, never-invented evidence, hop/citation fields, semantic excerpting, and expected latency. This is far beyond what annotations alone convey.

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

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

The description is long and dense, but nearly every sentence carries necessary behavioral or routing information. It is front-loaded with the critical account requirement and alternative tool. Minor redundancy around citations and ask_pipeworx prevents a 5.

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

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

Given no output schema, the description fully explains what the agent will receive: a findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and timing expectations. It also covers auth preconditions, depth differences, and tool alternatives, leaving little ambiguity.

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 schema already thoroughly documents both 'question' and 'depth' semantics. The description adds some context around the depth paywall and hop behavior, but it mostly reinforces schema content rather than introducing meaningfully new parameter guidance.

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 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' and contrasts itself with open-web search, making the resource and verb unmistakable. It also distinguishes itself from sibling ask_pipeworx by saying 'Best for broad/multi-part questions' and 'For a single lookup use ask_pipeworx instead.'

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'Best for broad/multi-part questions over structured data', and 'For a single lookup use ask_pipeworx instead.' It clearly names the alternative tool and the conditions that select it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results are 'ready to call directly, no second schema lookup needed,' providing useful context beyond annotations. No contradiction detected.

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 reasonably concise for the information it conveys, front-loading the purpose and key usage. Each sentence adds value, though it could be slightly tighter.

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 6 parameters and no output schema, the description adequately explains the tool's behavior, return value (top-N tools with full schemas), and usage context. No major gaps identified.

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

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

Schema coverage is 100% with descriptions for all 6 parameters, but the description adds value by explaining that 'query' is a natural language description, giving examples, and noting limit defaults (20, max 50). This supplements the schema well.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, financials, FDA drugs, etc.), distinguishing its purpose from sibling tools by positioning it as the first call to discover available tools.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and alternatives.

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

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

Beyond the read-only/idempotent annotations, the description discloses fan-out sources, return-field semantics, soft-fail behavior for USPTO, expected-empty sections, the private-company resolved:false path, and GDELT→GNews fallback. This is far more behavioral context than annotations alone 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 definition is front-loaded with examples and the core promise, and every long section adds operational detail. The single dense paragraph and repeated 'type' note make it slightly less scannable than ideal, but it is not padded.

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

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

For a tool with no output schema, the description is remarkably complete: it names each returned section, explains URI formats, sort order, source fallbacks, failure modes, expected empty results, and input disambiguation. An agent has enough context to invoke and interpret results correctly.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds extra value by stating that 'type' values are interchangeable and by enumerating accepted value shapes (ticker/CIK/name) with name-resolution behavior. It does not significantly change semantics but meaningfully reinforces them.

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 user-phrase examples and immediately states 'full cross-source profile of a US public company in ONE parallel call,' naming a specific action and resource. It distinguishes itself from single-source lookups and adjacent siblings by emphasizing the holistic, multi-source fan-out.

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 a strong trigger condition ('when the user asks for a holistic view') and explicitly says to prefer it over chaining single-pack lookups. It does not, however, spell out when to choose sibling tools like compare_entities or resolve_entity over this one.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds useful context about clearing sensitive data and pairing with other tools, enhancing transparency 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?

Extremely concise: three sentences with no waste. Front-loaded with the core action, followed by usage guidance and pairing advice.

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 destructive tool, the description fully covers purpose, usage context, and relationships to other tools. No output schema needed, and the behavior is well explained.

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

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

Schema coverage is 100% with a clear key description and example. The description adds little beyond schema (just 'previously stored'), so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' with a specific verb and resource. It is easily distinguished from siblings (remember, recall) which perform different operations.

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

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

Explicit guidance on when to use (stale context, task done, clear sensitive data) is provided. It also suggests pairing with remember and recall, but does not explicitly state when not to use the tool, which is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: fetches the page, extracts title/description/key links, outputs standard markdown. This goes beyond annotations by describing the processing steps and output format.

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, front-loaded with the core action and purpose, followed by output format and use cases. No 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?

The tool is simple with no output schema. The description explains what the output is (single text blob ready to drop at site-root/llms.txt) and covers all key aspects: input, processing, output, and use cases. It is complete for an agent to understand and invoke.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds that the URL is fetched and extracted, and mentions max_links default (25) and max (50), but these are already in the schema. Baseline 3 is appropriate 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 generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (help AI crawlers index the site). It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. It does not explicitly state when not to use or name alternatives, but the context is clear enough 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by listing the exact return fields: id, type, params, created_at, last_fired_at, fire_count. 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 with no waste: first sentence states purpose and return fields, second sentence gives usage guidance. Front-loaded and efficient.

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

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

With only one optional parameter and no output schema, the description covers the tool's purpose, return format, and usage context adequately. No missing elements.

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

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

Schema coverage is 100%, with one optional parameter (include_inactive) fully described in schema. The description does not add parameter details, meeting the baseline for high coverage.

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

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

The description clearly states it lists the caller's active subscriptions, with specific verb 'list' and resource 'subscriptions'. It distinguishes from siblings by mentioning using it for review before adding or to find an id for cancellation.

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: 'review what you're monitoring before adding more or to find an id to cancel.' While it doesn't mention when not to use, the context is clear and provides practical 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 are all false (readOnly, openWorld, etc.), but the description adds substantial context: filing returns a claim_token, is 'Rate-limited to 5 per identifier per day,' is 'Free; doesn't count against your tool-call quota,' and is read in daily digests. It also warns against pasting user prompts and clarifies scope, going 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?

Although lengthy, the description front-loads the purpose in the first sentence and every subsequent sentence serves a distinct function: scope, usage, token flow, rate limit, and cost. There is no redundancy or filler; each detail earns its place.

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

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

With no output schema, the description fills the gap by explaining that filing returns a claim_token and how to use it to read status and resolution. It covers scope, exclusions, rate limits, roadmap impact, and follow-up behavior, making it complete for a high-complexity feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema, such as advising to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and reinforcing that claim_token should be passed 'with no other arguments.' This adds value, though the schema already documents parameters well.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb and resource. It then enumerates concrete use cases (bug, feature/data_gap, praise) and clearly distinguishes this feedback tool from sibling tools like ask_pipeworx or discover_tools.

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

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

The description explicitly states when to use it ('Use when a tool returns wrong/stale data...') and provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' with instructions to file elsewhere for other servers. It also explains how to follow up using a claim_token, making the usage guidance actionable.

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?

Describes data source (CF analytics-engine), no PII, and caching behavior (5min-1h) beyond annotations. Adds actionable context without contradicting annotations.

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

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

Concise paragraph with front-loaded purpose, then returns, use cases, and data lineage. Every sentence adds value; no redundancy.

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

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

Given low complexity (1 optional param, no output schema), description covers what is returned, usage scenarios, data source, caching, and privacy. No gaps for an agent to use effectively.

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

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

Schema already describes window parameter fully, but description adds explanatory nuance (shorter vs longer windows) that enhances understanding of the enum values.

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

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

Description clearly states it returns trending tools/packs and call volume over a window. Use cases differentiate from siblings like ask_pipeworx or discover_tools, establishing a unique 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?

Lists three explicit use cases for when to use the tool (discovering hot data sources, confirming canonical tools, aligning use case). Does not explicitly state when not to use or name alternative tools, but context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds critical context: semantic anchor (≥0.30 Jaccard similarity), partition filter (>20% placeholder fraction returns null), fill check (realizable_edge_pp ≤0 means do not trade). It explains the response structure and edge cases, going 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 dense but well-organized with clear sections for modes, semantic anchor, partition filter, and fill check. It is front-loaded with the core purpose. While a bit lengthy, every sentence adds value, making it more comprehensive than 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?

Despite no output schema, the description thoroughly explains the response structure (opportunities array, partition_check fields) and covers edge cases (low similarity, placeholder filter, fill check). It references sibling tools for further actions, making it complete for an AI 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?

Schema coverage is 100%, so baseline is 3. However, the description adds rich detail: event mode walks child markets and performs partition checks; topic mode searches related events and flattens markets. It provides examples and explains the behavior, significantly enhancing understanding beyond the minimal schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies three modes (no args, event, topic) and distinguishes them from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: no args for trending scan of top ~200 markets, event for a specific market slug, topic for cross-event scanning. It explains why cross-event mode catches patterns single-event misses and mentions using polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes far beyond with details: caching at KV level for 1h, response structure with diagnostics, model family internals, and per-leg Kelly behavior. No contradictions.

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

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

The description is lengthy and dense with technical details, including run-on sentences. While informative, it could be more structured and concise for efficient agent parsing. Front-loads purpose but loses conciseness with deep internals.

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, 3 segments, no output schema), the description is remarkably complete. It covers response structure, knobs, caching, diagnostics, and even Fed note, leaving no major gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description adds operational context beyond schema, such as when to bump slippage and the effect of min_partition_leg_kelly on partition arbs, providing value.

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes from siblings by focusing on edge detection without paging hundreds of markets.

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 primary use case and explains tradeable-edge knobs (min_liquidity, max_spread_pp) for when to filter. It lacks explicit 'when not to use' or direct sibling alternatives, but the diagnostics section helps callers understand empty results.

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 details output structure (tracked, expired, snapshot_dates), limitations (60-day TTL, snapshot gaps), and data computation (decay from daily closes, not intraday). Annotations are consistent, and the description adds significant behavioral context beyond the annotations.

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

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

The description is front-loaded with the purpose and structured clearly (args, response, limitations). It is somewhat verbose but each section serves a purpose. Minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully covers return values, edge cases (gaps, expiration), and limitations. It provides sufficient context for an agent to use the tool correctly without ambiguity.

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 clear parameter descriptions. The tool description reiterates the defaults and max but does not add new information beyond the schema, resulting in a baseline score of 3.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates from siblings by focusing on telemetry over time, distinct from raw `polymarket_edges` or arbitrage tools.

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

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

The description implies usage when deciding whether an edge is fresh or aged, but does not explicitly compare to sibling tools or state when not to use it. It provides a query-like phrase but lacks direct guidance on alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds specifics: walks the ladder, returns fills, slippage, verdict, per-leg details, thin_legs, directional risk. No contradiction with annotations.

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

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

Description is detailed and informative but somewhat verbose with technical details in a single block. While structure is logical, it could be more concise (e.g., bullet points for modes). Still front-loaded with purpose.

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

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

No output schema, so description covers return fields thoroughly (top_of_book, vwap_fill_price, slippage, verdict, etc.) and handles edge cases (thin_legs, forced_directional_risk). Complete for a tool with 4 parameters and complex behavior.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining size_usd interpretation for single-market vs basket, side auto-default for basket, and mode implications. Exceeds baseline by clarifying parameter behavior beyond schema annotations.

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

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

Description clearly defines tool as a realizable-vs-theoretical edge check against live order-book depth, with explicit single-market and basket modes. Distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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: before acting on polymarket_arbitrage signals or trades above ~$500. Explains risks of partial basket fills and thin books, giving clear guidelines on when the tool is critical.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: matching is by keyword/word overlap, not shared resolution source; spreads are gross and ignore Kalshi fees; compatibility codes can be non-empty even when pairs are returned; unknown legs are never paired; and temporal_alignment null does not mean aligned. This is unusually transparent about limitations.

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 the tool is complex and has no output schema to carry return-value documentation. It is front-loaded with the core purpose, then modes, response fields, and caveats. The capitalization-heavy style and dense safety-fields section make it harder to skim, but every sentence contributes needed operational detail.

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: spread.top_spreads_pp, compatibility_warning/codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. It also covers failure/caveat cases such as event_subject_mismatch and temporal_alignment_unknown. Nothing essential for invoking and interpreting the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, clarifies that both modes run the identical matcher, and lists the exact topic shortcut values. This goes beyond repeating 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 states a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from same-venue or other Polymarket tools by emphasizing the Kalshi–Polymarket pairing and the 'same outcome on both sides' matching logic.

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 clear, actionable invocation guidance for both modes: pre-mapped topic shortcuts versus explicit event ticker/slug overrides, and explains which fields override which side. It warns that most pre-mapped topics currently return compatibility warnings, but it does not explicitly name alternative sibling tools or state when to choose polymarket_arbitrage or polymarket_edges instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: scoping to an identifier (anonymous IP, key hash, or account ID) and the pairing with remember/forget. 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?

Three sentences, all essential: primary action, usage guidance, and scope/pairing. No unnecessary words. Front-loaded with the core function.

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 tool with one optional parameter and no output schema, the description covers scope, usage, and pairing. It lacks error handling or return format details, but those are minor given the tool's simplicity.

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

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

Schema coverage is 100% and the description reinforces that omitting key lists all keys, which the schema already states. No additional semantic depth beyond schema examples is provided, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It distinguishes from siblings (remember, forget) and provides concrete examples like 'user's target ticker', making the purpose specific and 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 gives clear context for when to use (look up stored context without re-derivation) and mentions pairing with remember/forget. However, it does not explicitly state when not to use or compare with alternative retrieval tools like search, which slightly reduces clarity.

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

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

Description describes mark_read:true as flagging events as read (a mutation), but annotation declares readOnlyHint=true. This is a clear contradiction, undermining trust in behavioral disclosure.

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

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

Four well-structured sentences, front-loaded with purpose, no unnecessary words. Efficient and clear.

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

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

While description covers purpose, parameters, and alternative access, the contradiction with annotations reduces reliability. Missing details like error handling or limit behavior, but otherwise fairly complete for a read-only list tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context for mark_read (explains effect) and mentions filtering by type/since, but doesn't significantly augment what's already in the schema.

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

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

Description clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields. While it doesn't explicitly differentiate from sibling tools, the purpose is specific enough.

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?

Mentions filtering options (type, since) and suggests polling works fine. Also points to an alternative HTTP endpoint for scripts/dashboards, giving context on when to use the tool vs other access methods.

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

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

Annotations are all safe (readOnly, idempotent, not destructive). The description adds behavioral context: fans out to multiple APIs in one parallel call, has explicit fallback logic (GDELT→GNews), soft-fails for USPTO due to API sunset, and explains the return structure (changes[] grouped by source). No contradiction.

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

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

The description is a single paragraph but well-structured: it front-loads with example queries to quickly convey purpose, then explains data aggregation, parameter details, and sibling comparison. Every sentence adds useful information. No fluff.

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

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

Despite no output schema, the description explicitly states the return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers error/fallback behavior and provides a clear alternative tool. With high parameter coverage and annotations, nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds significant value: it explains the `since` parameter syntax in detail (ISO date or relative shorthand like '7d', '30d', '3m', '1y'), recommends typical usage ('30d'), and clarifies that `type` only supports 'company' currently. It also explains `value` accepts ticker or CIK. This goes beyond the schema definitions.

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

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

The description starts with clear example queries ('What's new with X', 'latest on Y') and explicitly states it returns a change feed for a company in a time window. It lists multiple data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling entity_profile, which provides static profiles. The verb 'returns' and resource 'change feed' are specific.

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 examples of when to use the tool ('What's new with X', 'updates on Acme') and when to use the alternative: 'Use entity_profile instead when you want the static profile.' It also explains fallback behavior (GDELT→GNews) and suggests a default `since` value ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, covering safety and idempotency. The description adds the source (ThreatFox) and the lookback window but does not detail behavior like pagination or ordering. It is consistent with annotations and adds some context.

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

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

The description is two sentences, immediately front-loading the core action and resource. Every word is necessary; no repetition of schema information or superfluous details.

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

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

Given the low complexity (single optional parameter, output schema present), the description adequately covers the source, time range, and intended use case. It enables an agent to understand when and how to use the tool without missing critical information.

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

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

Schema description coverage is 100%, with the 'days' parameter already described. The tool description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool returns IOCs added to ThreatFox in a configurable number of days. It specifies the resource (IOCs), source (ThreatFox), and temporal scope (last N days). This distinguishes it from sibling tools like search_ioc or recent_alerts.

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

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

Description explicitly says 'Useful for daily threat-intel ingestion,' providing a clear use case. However, it does not specify when not to use or mention alternatives, though the context from sibling names suggests search_ioc might be for specific lookups.

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

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

Beyond annotations (idempotentHint=true, readOnlyHint=false), the description adds behavioral details: key-value pair storage, scoping by identifier, persistence differences for authenticated vs. anonymous users (24 hours). No contradictions.

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

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

The description is four sentences, efficiently front-loaded with the main purpose, and every sentence adds value. No redundancy or fluff.

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

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

Given the simplicity of the tool (2 parameters, no output schema) and the annotations covering idempotency and non-destructiveness, the description thoroughly covers use cases, scoping, and persistence. It is complete for an agent to use effectively.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor context (e.g., key naming examples) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb (save) and resource (data), and is easily distinguished from siblings like recall and forget.

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

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

The description provides explicit guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions when to pair with recall and forget, indicating alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral detail: internal cascading across multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting instead of silent omission, and `figi_candidates` when a name is ambiguous. These traits go far beyond the structured annotations.

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

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

The description is front-loaded with purpose and the 'Use FIRST' directive, which is ideal. It is dense and somewhat wall-of-text, with many details packed into a long paragraph, but nearly every detail is load-bearing for correct invocation of a complex multi-source resolver.

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 compensates thoroughly: it enumerates returned artifacts (`figi_candidates`, `unresolved`, source labels, RxNorm citation), describes coverage limits (non-US issuers, non-equity instruments), and clarifies fallback behavior. An agent has enough context to decide when to call this tool and what to expect back.

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%, yet the description adds essential semantics: accepted input forms for company and drug, exact examples, and the critical 'ENTITY NAME ONLY' constraint with the bond-issuer nuance. It explains ISIN-to-LEI mapping behavior and the distinction between ticker-implied and name-search resolution, which the bare schema does not convey.

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 and object: resolve a user-spoken NAME to canonical/official identifiers, with concrete examples ('ticker for...', 'CIK for...', 'LEI for...'). It clearly distinguishes this from siblings by positioning it as the ID-lookup entry point that other tools require.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also defines supported entity types and input forms. It does not explicitly name alternatives like entity_profile or compare_entities, but the primary use case is unambiguous and exclusion cues are present implicitly through the supported-type and ID-focused framing.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., so the description adds value by detailing the process ('probes each entity with ai_visibility_check, ranks by score') and output structure ('ranked list with score, confidence, signal density per entity'), which are 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 two sentences: first states the main action, second provides usage context and return details. Every word adds value, no redundancy, and it is well-organized.

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

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

Given no output schema, the description adequately covers return values (ranked list with score, confidence, signal density per entity) and explains the probing process. The tool's complexity is moderate and the description is sufficient for an agent to understand behavior.

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

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

Schema coverage is 100% with clear descriptions for all 4 parameters. The description adds minimal extra semantic value beyond the schema, such as implying the first entity is the subject, which is already in the 'entities' parameter 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 action ('Compare AI visibility across multiple entities side-by-side'), the resource ('AI visibility of entities'), and distinguishes from siblings (e.g., ai_visibility_check for single entity, compare_entities) by specifying it probes each with ai_visibility_check and ranks them.

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

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

The description provides a clear usage context ('competitive AI-marketing audits') and an example question, implicitly guiding when to use this tool over alternatives. However, it does not explicitly state when not to use it or name direct 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?

Disclosed partial failure and latency: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out'. Annotations already show readOnly, openWorld, idempotent hints, no contradiction.

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

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

Single dense paragraph that front-loads purpose and includes all necessary details without redundancy. Every sentence is informative.

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

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

Despite no output schema, description details return structure (summary block, per-advisory detail, links, alternatives) and error handling. Complete for a composite tool with two external APIs.

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

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

Schema coverage is 100%. Description adds that scoped packages are accepted for 'package' and defaults to latest version for 'version'. Adds value beyond schema descriptions.

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

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

Description clearly states it's a composite check for npm packages, fans out across deps.dev and bundlephobia, and answers questions about safety, popularity, and size. Distinguishes from sibling tools like search_hash, search_malware, etc.

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

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

Explicit usage instruction: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes ecosystem limitation to npm in v1 and directs to deps.dev for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, so behavioral safety is well-covered. The description adds no extra behavioral context beyond purpose, which is acceptable but not additive.

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

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

Single sentence, no redundancy, immediate comprehension. Every word is necessary.

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

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

For a simple one-parameter tool with output schema, the description is adequate. It could add scope notes (e.g., 'public IOCs only') but is otherwise complete enough to guide 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% and the hash parameter is described as 'md5 / sha1 / sha256'. The description adds context that the result will contain 'IOCs', which meaningfully extends understanding of the parameter's purpose beyond the schema.

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

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

Description clearly states the tool returns 'IOCs associated with a file hash (md5 / sha1 / sha256)'. This is a specific verb+resource combination, and it distinguishes the tool from sibling tools like 'search_ioc' or 'search_malware' which target other entity types.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or restrictions. Siblings exist but are not referenced.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying return fields (malware family, confidence, threat-type, etc.), which provides behavioral context beyond annotations.

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

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

The description is two sentences, front-loaded with purpose, and contains no unnecessary words. It efficiently conveys the tool's function and output.

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 presence of an output schema and 100% parameter schema coverage, the description provides adequate completeness. It explains what the tool returns, and no additional details are needed for this straightforward lookup tool.

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

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

Schema coverage is 100%, and the schema descriptions for both parameters are sufficient. The description marginally adds context for the 'indicator' parameter by listing example types (IP, domain, URL, hash) but does not provide additional meaning beyond the schema.

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

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

The description uses specific verb 'look up' and identifies the resource as 'indicator of compromise (IP, domain, URL, hash, etc.)'. It clearly distinguishes from sibling tools like search_hash and search_malware by focusing on generic IOC lookup.

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

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

The description states to use it for looking up a specific IOC, providing clear context. However, it does not explicitly mention when not to use it or suggest alternatives like search_hash or search_malware for hash or malware-specific queries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral context beyond the annotations, so it meets the baseline but provides no extra value.

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

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

A single, front-loaded sentence that immediately conveys the core function. No wasted words.

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

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

The description is sufficient for a simple tool with two parameters and an output schema. It states the result type (IOCs) and example values. Could be more complete by mentioning when to use this over search_ioc.

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%: both parameters are described. The description includes examples but doesn't add deeper meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves IOCs tagged to a specific malware family, with concrete examples. It distinguishes from sibling tools like search_ioc by focusing on malware families.

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

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

No explicit guidance on when to use this vs alternatives (e.g., search_ioc). Usage is implied from the description but lacks direct comparison or exclusion criteria.

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

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

Adds rich behavioral details beyond annotations: mentions embedding model, window size, character offset, truncation cap (200K chars). 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?

Somewhat long but well-structured: purpose first, then usage guidance, then technical details. No wasted sentences.

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

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

Fully covers tool behavior despite no output schema. Explains input, behavior, limitations, and integration with other tools.

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

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

Schema has 100% coverage but description adds meaning: explains text as 'already pulled', query as natural-language with examples. Adds significant usage-level semantics.

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

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

Clearly states semantic search inside a fetched record, uses specific verb 'search' and resource 'text inside a record'. Distinguishes from siblings like ask_pipeworx_grounded.

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

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

Provides explicit context for when to use (record too large for prompt) and pairs with ask_pipeworx_grounded. Could be improved by explicitly stating when not to use.

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

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

Beyond annotations, the description reveals critical behaviors: the need for OAuth, the one-time webhook secret, auto-disable after 10 webhook failures, and the 10 SMS/day cap. 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 front-loaded with the main action and return value, followed by well-organized details. While a single paragraph, it uses examples and lists effectively. A slight improvement could be breaking into sections, but it's already 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?

Given the tool's complexity (multiple subscription types, delivery channels, constraints) and the absence of an output schema, the description covers the essential information: return value, type-specific params, delivery options, and critical notes. It is complete for effective 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?

With 100% schema coverage, the description adds significant value: it provides concrete examples for each type, explains the webhook signing process, and clarifies constraints like phone verification and webhook auto-disable.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', and identifies the return value (subscription id). This differentiates it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies when to use: it requires a Pipeworx OAuth account, lists supported types and delivery channels, and includes constraints like SMS daily cap. It does not explicitly mention when not to use, but provides sufficient context for appropriate 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 provide readOnlyHint, openWorldHint, etc. Description adds context about returning example questions with exact tool and argument shapes from a live catalog, and that it's the onboarding entry point. No contradictions.

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

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

Description is fairly long but each sentence adds value. Front-loaded with example queries. Minor room for tightening, but still efficient given the richness.

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

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

Given no output schema, description adequately explains return type (category-bucketed questions with tool+argument shapes). Covers purpose, usage, parameters, and when to use. Fully complete for a simple 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 already describes 'topic' with 100% coverage. Description adds concrete example values (finance, pharma, etc.) and clarifies that omitting gives a cross-category spread, adding meaning beyond schema.

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

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

Description clearly states the tool returns category-bucketed example questions about what Pipeworx can do, with specific verbs and examples. It distinguishes itself as the onboarding entry point from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to use the optional topic parameter. Provides clear context for when to use vs alternative meta-tools.

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

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

Adds important details beyond annotations: the row is deactivated (not deleted), historical events remain available via recent_alerts. This complements the idempotentHint: true annotation without contradiction.

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

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

Three concise sentences, front-loaded with the action. No unnecessary words, each sentence adds value.

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

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

Given the simple tool with one parameter and no output schema, the description covers the behavioral outcome (deactivation, ownership, historical accessibility) completely.

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

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

Schema coverage is 100% and parameter description is sufficient. The description adds minimal value by referencing 'returned by subscribe,' but 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 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from sibling tools like subscribe (creates) and list_subscriptions (lists).

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

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

It explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. It does not explicitly mention alternatives but context implies when not to use.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses critical semantics: the distinct meanings of 'could_not_verify' vs 'unsupported', that 'could_not_verify' is not evidence, and the internal routing logic. This adds significant context for correct interpretation of results.

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 each sentence contributes value: examples, usage, routing, return values, and error semantics. It is front-loaded with trigger phrases, though it could be more concise with bullet points or shorter sentences. Minor redundancy exists (e.g., 'grounded' mentioned multiple times).

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

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

Despite no output schema, the description thoroughly covers return values (enumerated verdicts), citation, reasoning, error handling, and the two processing paths. For a tool with 2 parameters, this is highly complete and leaves little ambiguity 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 description coverage is 100%, so the baseline is 3. The description adds minimal additional meaning beyond the schema; it mentions tolerance override but the schema already explains it. No further parameter context is provided.

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 specifies the tool's purpose: natural-language claim verification against authoritative sources, with example trigger phrases. It also distinguishes itself from other tools by noting it replaces multi-step sequential calls, eliminating ambiguity.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for company-financial vs. other claims. However, it does not explicitly state when not to use it or name alternative sibling tools, though this is implied.

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