Mediastack

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

Annotations already indicate read-only, idlempotent, and non-destructive nature. The description adds valuable behavioral details: default free model, BYO key for Anthropic with direct billing, and return format. 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, well-structured paragraph that front-loads key information (purpose, default model, optional behavior). Every sentence adds value; 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?

For a tool with 4 parameters, no output schema, and rich annotations, the description fully explains return format (per-model object + combined), use cases, optional parameters, and model costs. No gaps.

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

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

Schema coverage is 100%, but the description adds meaning beyond names/descriptions: default model behavior, API key pass-through, and context disambiguation. This justifies a score above baseline 3.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility. It uses specific verbs like 'probe' and 'score', specifies the default model, and differentiates from siblings like 'scan_competitor_ai_presence'.

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

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

The description provides use cases (AI-marketing audits, brand checks, monitoring) and explains how to use the tool with default or Anthropic models. It lacks explicit when-not-to-use guidance but offers clear context and optional parameters.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the tool routes to one of thousands of source tools, fills in arguments automatically, and returns structured answers with stable citation URIs. These are behavioral details not present in the annotations. No contradiction with the annotations was found.

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

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

The text is long but front-loaded with the most important directive, followed by behavior, usage triggers, examples, and sibling routing. No obvious filler sentences, and the length is justified by the routing complexity; it just stops short of being maximally concise because of the extended category list and examples.

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

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

For a no-output-schema router with many siblings, the description is complete: it names the data domains, gives concrete query examples, describes the output format (structured answer with citations), and routes the main exceptions to specific sibling tools. An agent has enough context to select ask_pipeworx correctly without further documentation.

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

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

Schema coverage is 100%: all six parameters are documented as aliases for the natural-language question. The description reinforces what the question should contain ('current US unemployment rate', 'Apple's latest 10-K') but does not add semantic information about the parameters beyond the schema's own descriptions, so the baseline 3 applies.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and states a specific function: routing a natural-language question to the right one of 5,798 tools across 1,517 verified sources and returning structured answers with pipeworx:// citation URIs. It also differentiates from sibling tools by naming the alternatives (ask_pipeworx_beta, ask_pipeworx_grounded, deep_research) for cases where this tool is not appropriate.

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

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

Gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current', or any factual question about real-world entities...') and says to prefer it over web search even when web search could answer. It lists specific exclusion conditions such as hypothetical questions, grounded/reasoning-heavy queries, and broad multi-part research, naming the correct sibling for each.

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

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

The annotations already mark this read-only/open-world/idempotent, and the description adds valuable behavioral context: live candidate routing improvements, current inactive candidate with a retirement date, exact equivalence to ask_pipeworx today, and a clear statement that it does not fall back to anything yet is a full working router. This goes well beyond the structured hints.

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

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

Four sentences with no wasted phrases; each sentence adds distinct information: identity/differences, current status, usage guidance, and reassurance about fallback behavior. The most decision-relevant information (beta, same interface) is front-loaded.

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

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

For a single-required-parameter router with no output schema, the description is complete: it specifies the input pattern, current behavior, relationship to the stable sibling, response-shape equivalence, and operational caveats. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%: all six properties are described, with q/text/input/query/prompt all documented as aliases for question. The description adds nothing about parameters beyond noting the same arguments as ask_pipeworx, so the schema carries the load and a baseline 3 is appropriate.

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

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

States a specific resource (universal question-answering router), the action (ask), and the beta-vs-stable distinction relative to ask_pipeworx. It names the sibling (ask_pipeworx) and clarifies that this variant is the experimental routing edge, so an agent can distinguish it without opening schemas.

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

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

Explicitly says to use it like ask_pipeworx when the newest routing is desired, and mentions results are compared against the stable router. It gives clear context and names the alternative, though it never spells out an explicit 'do not use when...' exclusion, making it a strong 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond that: it costs an extra LLM call, returns a structured payload with evidence and confidence, and can explicitly refuse with enumerated refusal_reason values. This fully discloses safety-relevant and operational behavior.

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

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

The description is information-dense yet every sentence serves a purpose: defining the behavior, specifying the exact return contract, listing refusal reasons, and providing cost/usage trade-offs. It is front-loaded with the core differentiator ('hallucination-resistant') and structured logically from mechanism to output to usage guidance.

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, yet the description fully specifies the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and all failure refusal reasons. It also covers cost implications, routing behavior, and usage boundaries, making the description complete for an agent to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, and every parameter is documented as an alias for 'question' with a natural-language description. The tool description itself does not add parameter-level detail, but with full schema coverage the baseline of 3 is appropriate; the description's routing and output semantics compensate for any lack of param elaboration.

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

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

The description clearly identifies a specific verb ('EXTRACTS the answer') and resource ('tool result'), explaining that it is a hallucination-resistant grounded answer mode. It distinguishes itself from sibling ask_pipeworx by emphasizing evidence-only extraction and explicit refusals, so an agent can tell them apart without opening schemas.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the condition for preferring it: 'prefer ask_pipeworx for casual lookups.' This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral details: fan-out logic, response shapes, resolver contract, parent event extractor, safety mechanisms, closed market handling, wide spread tradeability, cancellation rule parsing. 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 long but well-structured with sections (fan-out examples, response shapes, resolver contract). Every sentence provides valuable information for a complex tool. Slightly verbose but justified given the tool's scope.

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

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

No output schema, so description fully explains return values (result.market, result.analysis, result.evidence) and edge cases (low-confidence, closed markets, wide spreads, resolution rules). Covers all necessary context for proper use.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds extra meaning: explains market can be slug, URL, or question text; depth enum values are elaborated ('quick = 2-3 sources, thorough = full fan-out'); include_raw effect explained. Adds significant value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). Distinguishes from siblings like polymarket_edges which are narrower.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Provides examples per category. Does not explicitly mention when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 front-loaded with trigger phrases and structured as: trigger list, behavior, data details, and efficiency claim. Every sentence is meaningful, though slightly long. Could be tightened but remains clear and 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 explains return format (paired data, citation URIs) and result ordering. It covers purpose, input examples, data sources, behavioral nuances, and efficiency benefits. Completes all needed context for correct tool invocation.

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

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

Schema coverage is 100%; both parameters are documented in the schema. The description adds meaning beyond the schema: explains what each enum value ('company', 'drug') retrieves, provides example inputs with tickers/CIKs and drug names, and reinforces the 2–5 item constraint. This adds value beyond baseline 3.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs, with highly specific verb phrases ('compare', 'rank', 'head to head') and explicit resource (SEC EDGAR/XBRL financials, FAERS/FDA data). It distinguishes from siblings by noting it replaces 8–15 sequential lookups and should be preferred over single-pack lookups.

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

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

Explicitly provides natural-language triggers (e.g., 'Compare X and Y', 'which is bigger', 'rank these companies') and clear usage preference: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives strong guidance on when to use this tool vs. alternatives.

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

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

The description goes well beyond the annotations by disclosing account requirements, paid tiers, latency expectations, return packet contents, explicit gaps[] arrays, contradiction detection, semantic excerpting, and non-invention of answers. These behaviors are not derivable from readOnlyHint/openWorldHint and are crucial for correct invocation.

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 front-loads critical preconditions and sibling alternation before core mechanics. Nearly every sentence adds useful information, though there is mild redundancy around ask_pipeworx and citation fetchability that prevents a perfect score.

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

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

For a complex tool with no output schema, the description is complete: it explains what results look like, how gaps are handled, how contradictions are surfaced, how long the call takes, what auth is needed, and when to prefer an alternative. An agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline applies: the schema already documents question and depth thoroughly, including the depth enum's meanings and paid status. The description mostly repeats schema content, adding only minor framing such as illustrative research questions and account prerequisites, which are not parameter-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?

The description states a specific function: grounded multi-source research across Pipeworx's 1517 structured data sources in one call, with decomposition and parallel routing across 5,798 tools. It explicitly distinguishes this from open-web search and from ask_pipeworx, which removes ambiguity among siblings.

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

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

Usage guidance is explicit: use for broad/multi-part questions over structured data, avoid for a single lookup, and use ask_pipeworx instead when not signed in. It also names the paid-tier constraint for the thorough depth, giving the agent a clear decision procedure.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable detail about return format (top-N tools with full schemas, ready to call) and no second lookup needed, enhancing behavioral context.

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

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

Front-loaded with purpose, followed by domains, then return format and usage guidance. Slightly verbose but well-structured and each sentence serves a clear role.

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?

High coverage given no output schema: explains what it returns, when to use, and provides example queries. For a discovery tool, this is sufficiently complete.

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

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

Schema coverage is 100% with examples, so the description adds minimal parameter-specific value beyond listing aliases and example queries already present in the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific use cases and domains (SEC filings, financials, etc.), distinguishing it from sibling tools as a discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear guidance on when to use it for exploration rather than direct answers.

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 openWorldHint. The description goes beyond these by explaining behavior details: it fans out across multiple sources, reports sources_used/sources_failed so an empty section is known as 'no data' rather than a bug, and returns resolved:false with a notes line for private companies. These are meaningful behavioral disclosures not present in the annotations.

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

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

The description is dense and front-loaded with purpose, but it is a long, unbroken paragraph heavily packed with parentheticals and semicolons. There is a garbled/incomplete phrase ('Cash, sorted ...') that hurts readability, and the trigger examples take space that could be condensed. It is not poorly written, but it lacks clear structural organization for easy scanning.

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

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

With no output schema, the description must explain the return value, and it largely does: it lists cik, company_name, resolved_from/resolved_to, recent_filings with URI format, fundamentals fields, and sources_used/sources_failed. It also covers input resolution and failure cases. However, it does not detail the exact shape of every source section (patents, contracts, biologics, etc.) or mention pagination/data freshness, leaving some gaps for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by providing concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying that names resolve via SEC EDGAR, and noting that type accepts 'company' or 'ticker' interchangeably with identical value shapes. This enriches the parameter semantics without being exhaustive.

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

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

The description clearly states the tool's purpose: a 'full cross-source profile of a US public company in ONE parallel call', backed by trigger examples like 'brief me on Tesla'. It differentiates from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', making its scope and resource unambiguous.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER ... when the user asks for a holistic view', which separates it from narrower single-source lookups. It also clarifies acceptable input forms (ticker, CIK, name) and the private-company edge case, but does not name specific sibling tools (e.g., search_news, compare_entities) for direct exclusion.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not elaborate on permanence or side effects. It adequately complements annotations without contradiction.

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

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

Two sentences, front-loaded with the core action. No unnecessary detail. Every sentence adds value: first states purpose, second gives usage guidance and links to siblings.

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

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

Given the tool's simplicity (one param, no output schema) and annotations, the description covers purpose, usage, and relationship to siblings. Missing details like error behavior (e.g., key not found) are minor for this context.

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

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

Schema coverage is 100% with a clear description and example for the 'key' parameter. The description only mentions 'by key' without adding new semantics, so it meets 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 the action: 'Delete a previously stored memory by key.' It identifies the resource (memory) and the specific operation (delete). Mentioning 'Pair with remember and recall' helps distinguish from related tools, though not exhaustively.

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 lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It does not provide explicit when-not-to-use or alternatives, but the guidance is clear and 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds the process details: fetches page, extracts title/description/key links, emits standard llms.txt format, and output is a text blob ready to drop at site-root. 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 three sentences with no filler. Information is front-loaded: first sentence states purpose, second explains process, third lists use cases. Every sentence adds value.

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

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

For a simple tool with 2 parameters, no output schema, and comprehensive annotations, the description provides sufficient context: purpose, process, output format, and use cases. No gaps remain.

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

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

Schema coverage is 100% and description does not add meaning beyond what schema already provides for both 'url' and 'max_links'. The baseline of 3 is correct given high coverage.

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

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

Description uses specific verb 'generate' and resource 'llms.txt file', clearly indicating the tool's output. It distinguishes from all 38 sibling tools by describing a unique function (generating an AI crawling index file). No sibling tool appears to do this.

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

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

Explicitly lists three concrete use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not state when not to use or provide alternatives, but the provided context strongly implies appropriate usage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about return format (titles, descriptions, sources, URLs), which is sufficient beyond annotations.

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

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

Two tightly written sentences with zero redundancy. The primary action is front-loaded, and every word 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?

The description provides basic usage and output but lacks explicit differentiation from similar tools (e.g., 'search_news') and has parameter inaccuracies, leaving gaps for an agent to decide when to use this tool.

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

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

Despite 100% schema coverage, the description introduces a non-existent parameter 'language' and uses singular forms ('category', 'country') that do not match the schema's actual parameters ('categories', 'countries'), potentially misleading an agent.

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 the latest news headlines and mentions optional filters. It distinguishes from sibling 'search_news' by implying focus on current headlines, but does not explicitly differentiate.

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 advises optional filtering by category, country, or language, but does not specify when to avoid this tool or suggest alternatives like 'search_news' for keyword-based searches.

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, destructiveHint, and idempotentHint. The description adds value by specifying returned fields and the concept of 'active' subscriptions, but does not introduce new behavioral traits beyond these.

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

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

Two concise sentences that front-load the purpose and follow with usage guidance. 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 one optional parameter and no output schema; the description lists all return fields. Combined with rich annotations, the definition is fully 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% with a well-described boolean parameter (include_inactive). The description does not elaborate on parameter usage, but the schema already provides adequate meaning, so baseline 3 applies.

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

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

The description explicitly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.), clearly distinguishing it from sibling tools like subscribe or 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 provides concrete use cases: 'review what you're monitoring before adding more' and 'find an id to cancel', offering clear guidance on when to invoke this tool versus alternatives.

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

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

The description discloses multiple behavioral traits beyond the annotations: rate-limit ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), side effects ('The team reads digests daily and signal directly affects roadmap'), and the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later...'). These details are not in the annotations, fully carrying the transparency burden. There is no contradiction with 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 moderately long but every sentence earns its place: it covers purpose, usage, scope, formatting, token workflow, team process, rate limit, and cost. The first two sentences front-load the core purpose and triggers. Slight redundancy (e.g., the first sentence already says 'broke, missing, or needs to exist' and the usage list repeats similar categories) prevents a perfect score, but the structure is logical and scannable.

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 (4 parameters, nested object, no output schema), the description is exceptionally complete: it explains the entire feedback loop (file via arguments, receive claim_token, later check status), clarifies what qualifies as valid feedback, distinguishes from other MCP servers, and notes operational constraints (rate limit, quota impact). The absence of an output schema is mitigated by explicitly stating the return token and its meaning.

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

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

While the schema already covers 100% of parameters with descriptions, the description enriches understanding, especially for claim_token and context: it explains the token's round-trip workflow and provides an example call. It also instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which adds crucial semantics to the message and context fields that the schema alone 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 opens with 'Tell the Pipeworx team something is broke, missing, or needs to exist,' explicitly naming the action (feedback) and the specific resource (Pipeworx team). It distinguishes itself from sibling tools by focusing exclusively on user feedback for the current Pipeworx connection, not on research or entity operations. The scope limitation ('ONLY for tools served by this Pipeworx connection') further clarifies its unique niche.

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

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

The description provides explicit usage triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions, directing users to file with another server if the tool isn't Pipeworx-specific, and offers a fallback test ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, etc.), the description adds valuable behavioral details: data source (CF analytics-engine), no PII, cached 5min-1h, and self-aggregating signal. No contradiction with annotations.

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

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

The description is concise (5 sentences) and well-structured, starting with core functionality, then bullet-point use cases, and ending with technical details. No unnecessary words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description covers purpose, use cases, data provenance, caching, and parameter semantics. It is fully adequate for the agent to understand and invoke the tool correctly.

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

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

The description adds meaning to the single parameter 'window' beyond the schema's enum options, explaining that shorter windows show current trends and longer windows show steady-state demand. Schema coverage is 100%, so baseline is 3, but the extra context earns a 4.

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

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

The description clearly states what the tool does: returns top tools, packs, and call volume on Pipeworx over a recent window. It uses a specific verb ('Returns') and distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on trending usage data.

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

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

The description explicitly lists three use cases (discovering hot data, confirming canonical tools, checking alignment) and explains window choices. It does not mention when not to use or compare directly with siblings, but the context is sufficient for selection.

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

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

Annotations are readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: semantic anchor, partition filter, fill check against CLOB depth, and realizable edge calculation. 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 dense and well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While lengthy, every part earns its place. Minor redundancy (e.g., mention of fill check twice).

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 provided, but the description thoroughly explains response fields (opportunities[], partition_check, suggested_trade, fill_check details). Covers 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 coverage is 100% with descriptions for both event and topic. The description adds value by explaining the modes, providing example inputs, and detailing behavior (e.g., cross-event scanning dependencies).

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 via monotonicity violations and partition-sum checks, with explicit modes (no args, event, topic) and examples. It is specific and distinguishes from sibling tools.

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

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

Provides detailed guidance on when to use each mode (event recommended for specific markets, topic for cross-event scanning), explains fill check, and mentions custom sizing via polymarket_fill_risk. Lacks explicit 'when not to use' or direct comparison with other sibling tools like polymarket_edges.

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

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

Annotations declare readOnlyHint, idempotentHint, etc., and the description adds rich behavioral context: caching (1h at KV level), segment logic, diagnostics for empty results, and trade details. No contradictions with annotations.

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

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

Front-loaded with core purpose but overall very long with extensive details on segments and formulas. Could be more concise by moving some details to external references.

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 thoroughly documents response structure (by_segment, fed_candidates, diagnostics) and caching behavior. All 9 parameters are explained with usage context. Complete for a complex tool.

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

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

Baseline 3 due to 100% schema coverage; description adds value by explaining real-world context (e.g., slippage_pp mentions Polymarket fees, min_liquidity gives example, min_partition_leg_kelly explains interaction with min_kelly). Exceeds baseline.

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

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

Description clearly states the verb 'scan' and 'return', resource 'Polymarket markets', and the specific outcome 'opportunities where Pipeworx data disagrees with market price'. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 built for 'what should I bet on today' and describes how agents discover opportunities without paging. However, it lacks explicit when-not-to-use or comparisons to siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description adds significant behavioral context beyond annotations: snapshot TTL (60 days), decay computation from daily closes (not intraday), response structure with detailed field meanings (trend values, decay_pp_per_day), and handling of gaps. Annotations already declare read-only, idempotent, and non-destructive, and the description fully aligns.

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 question and then breaks down the response into tracked, expired, and snapshot_dates. Although it is verbose, every sentence adds value, and the structure is logical. Minor reduction for length but not excessive.

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 lack of output schema, the description fully explains the return structure, including all fields and their interpretations (trend values, decay_pp_per_day, lifespan_days, snapshot_dates). It also covers limitations (TTL, snapshot start, decay from closes). No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the default values and clamp of 'days' and mentions 'snapshot family' for 'window', but does not add new semantic meaning beyond what the schema already provides. No extra nuance or usage hints are given.

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

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

The description clearly states the tool's purpose: it provides edge persistence and decay telemetry. The verb 'track' is implicit in the title and description, and it explicitly answers a specific question about edge longevity. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical persistence and trend analysis.

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 when to use the tool ('Answers how long has this edge existed and is it shrinking?') but does not explicitly state when not to use it or compare it to alternatives. The context is clear enough for an agent to infer usage, but lack of explicit exclusions prevents a perfect score.

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

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

Despite annotations already providing readOnlyHint, idempotentHint, and non-destructive flags, the description adds extensive behavioral context: it walks the order book ladder, returns top-of-book and VWAP fills, slippage, and warns about forced directional risk. Since no output schema exists, the description fully compensates.

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

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

The description is well-structured with bold headers for modes, but it is verbose with repeated warnings about partial fills and directional risk. It could be slightly more concise without losing clarity, but the length is justified by the tool's complexity.

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

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

Given no output schema, the description thoroughly documents all return fields for both modes, covers edge cases (thin legs, clamping), and explains the dominant loss mode (unhedged directional position). It is fully complete for evaluating tool suitability.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the dual meaning of 'side' (single-market vs basket auto-detection), the different interpretation of 'size_usd' between modes, and the requirement for exactly one of 'market' or 'event'.

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 verb (fill risk check) and resource (live CLOB order-book depth), distinguishing between single-market and basket modes. It is specific and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by focusing on capturability rather than signal generation.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risk of partial fills converting arb to directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes far beyond that by disclosing matching limitations, compatibility codes and their meanings, fee treatment, skipped-leg counters, unknown-leg exclusion, and the precise semantics of temporal_alignment null values. This is unusually candid behavioral documentation.

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 almost every sentence carries distinct operational information: modes, response shape, safety fields, fee caveats, skipped counters, and mismatch semantics. It is front-loaded with the core purpose and uses clear section markers like TWO MODES, RESPONSE, and SAFETY FIELDS. It earns its length, though a slightly tighter organization would improve scannability.

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

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

With no output schema present, the description carries the full burden of explaining return values, units, flags, warnings, and limitations. It covers spread direction, raw probabilities, compatibility_codes, fees, skipped comparisons, and the meaning of null temporal alignment. An agent has enough information to call the tool, interpret the response, and avoid over-trusting the spread signal.

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

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

Schema coverage is 100%, so the schema already documents all three parameters well. The description adds value by explaining that both modes run the identical token-overlap matcher, that explicit ticker/slug parameters are for custom pairings, and that the same disclosures and warnings apply regardless of mode. This is meaningful context beyond the schema entries.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes itself from single-venue tools like polymarket_edges and polymarket_arbitrage by making the cross-venue comparison the core subject, and then clarifies the two modes of invocation.

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

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

The description clearly explains when to use the `topic` mode versus explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, and warns that pre-mapped shortcuts are not guaranteed to be tradeable. It does not explicitly name sibling alternatives or say 'use X instead of this tool,' but the mode guidance and caution about compatibility warnings provide solid context for choosing and trusting the tool.

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

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

Annotations already declare read-only and idempotent behavior. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) which is not in annotations. No contradictions.

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

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

Three concise sentences that front-load the main purpose, with no wasted words. Every sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers usage, scoping, and relationships with siblings. No gaps.

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

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

Schema has 100% coverage with a clear description for the 'key' parameter. The description reinforces that omitting the key lists all keys, but adds little 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 verb (retrieve/list) and resource (saved memories). It distinguishes from siblings like 'remember' and 'forget' by explicitly mentioning them and contrasting the action.

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

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

Describes when to use (looking up previously stored context) and provides context about scoping to an identifier. Does not explicitly state when not to use, but the pairing with 'remember' and 'forget' implies alternatives.

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

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

Adds context beyond annotations: describes returned fields, mark_read side effect, and mentions the same feed available via REST. No contradiction with annotations.

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

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

Concise and front-loaded: first sentence captures purpose, no fluff, every sentence adds value.

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

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

Covers purpose, parameters, return fields, behavior, and alternative access, all without an output schema. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description elaborates on type, since, and mark_read, but omits limit and unread_only, adding partial value.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts, distinguishing it from sibling tools like list_subscriptions.

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

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

Provides guidance on filtering by type and since, setting mark_read, and notes polling works fine, with an alternative REST endpoint. Lacks explicit when-not-to-use but is informative.

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

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

Annotations already indicate read-only/idempotent, but the description adds detailed behavioral context: fans out to multiple APIs, fallback logic, USPTO soft-fail, and return structure.

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 informative but slightly long. Starts with example queries which is helpful, but some repetition could be trimmed.

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 structure comprehensively. Handles edge cases like fallback and soft-fail.

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

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

All three parameters are fully described in the schema, and the description adds extra context: 'since' format with examples, 'value' as ticker or CIK, and 'type' as only 'company'.

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

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

Clearly states the tool returns recent changes for a company from multiple sources (SEC filings, news, patents) and distinguishes from sibling tool 'entity_profile'. Examples of queries help clarify use cases.

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

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

Provides explicit when-to-use examples and recommends 'entity_profile' for static profiles. Also explains fallback behavior for news sources under rate limiting.

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 mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds key behavioral details: key-value pair scoped by identifier, persistence differences between authenticated and anonymous sessions (24h), and pairing with recall/forget. No contradiction with annotations.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage context, durability behavior, and pairing instructions.

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 required params, no output schema), the description covers all essential aspects: storage mechanism, scope, persistence duration, and relationship with sibling tools. It is fully sufficient for an agent to use correctly.

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

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

Schema description coverage is 100% (both key and value have descriptions). The description reinforces the schema by providing example keys and values, but adds limited new semantic meaning beyond the schema's own 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 'Save data the agent will need to reuse later' with concrete examples (resolved ticker, target address, user preference). It distinguishes itself from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete.'

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 advises use when 'you discover something worth carrying forward' and contrasts with recall/forget. It provides clear context but does not explicitly state when not to use the tool.

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

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

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: ambiguous matches return `figi_candidates` rather than asserting a result, unresolved identifiers are stated under `unresolved` instead of omitted, identifiers are source-labelled, and LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable. It also reveals the tool internally cascades through several lookup endpoints, which is behavior an agent needs to know.

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 highly detailed and well-structured, front-loading purpose and usage before diving into specifics. The long series of query paraphrases at the start is somewhat redundant, and the company explanation is dense with nested parentheticals. Still, nearly every clause adds unique information, so the length is largely justified.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: it describes `figi_candidates` for ambiguity, `unresolved` for failures, source labels, graceful degradation, and the exact output for drug lookups. Input variants, edge cases, and failure modes are all covered, making the tool fully usable without further 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?

Although the schema already documents both parameters, the description significantly enriches parameter meaning: it explains that company `value` can be a ticker, CIK, ISIN, or name (ISIN accepted via GLEIF mapping is not in the schema), defines drug inputs as brand or generic, and provides explicit anti-guidance about passing entity names only. This goes well beyond the schema's base 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 opens with concrete user query patterns ('What's the ticker for…', 'find the CIK for…') and states the core function: resolving user-spoken names to canonical identifiers. It distinguishes itself with 'Use FIRST whenever you have a name but need an ID' and names the supported entity types (company, drug) with specific identifier sets (CIK, LEI, FIGI, RxCUI).

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 agents when to use this tool ('Use FIRST whenever you have a name but need an ID') and gives type-specific guidance for both 'company' and 'drug'. It also warns against passing full noun phrases for bonds. However, it doesn't explicitly name sibling tools as alternatives or state when NOT to use it, so the exclusion guidance is implicit rather than fully explicit.

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 readOnlyHint, openWorldHint, idempotentHint, non-destructive. The description adds that it calls ai_visibility_check per entity, returns a ranked list with score, confidence, and signal density, and treats the first entity as subject. No contradictions. Description adds meaningful 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 three concise sentences. First sentence states purpose, second explains mechanics, third gives example. No superfluous words, well front-loaded.

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

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

Though there is no output schema, the description clearly states the return format: 'ranked list with score, confidence, signal density per entity.' It also explains the tool probes each entity with ai_visibility_check, providing enough context for an agent to understand expected 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 description coverage is 100%, so baseline is 3. The description adds extra semantics: 'First entry treated as the 'subject' for narrative; rest are competitors.' This clarifies usage beyond the schema's generic 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. It distinguishes itself from siblings like ai_visibility_check (single probe) and compare_entities (which may have different focus) by specifying its competitive audit purpose.

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

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

The description gives a concrete use case: 'competitive AI-marketing audits' and an example question. It implicitly differentiates from single-entity probes by noting side-by-side comparison. However, it doesn't explicitly list when not to use or mention alternatives beyond the context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral context: fans out to two services, returns specific fields (summary block, per-advisory detail, links, alternative versions), mentions timing (bundlephobia first measurement takes 5-30s), and explains graceful degradation (sources_failed will list timeout, rest still returns). No contradictions with annotations.

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

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

The description is a single paragraph that packs a lot of information. It is front-loaded with the core purpose. While dense, every sentence serves a purpose (use case, return structure, ecosystem scope, timing caveat). Slightly long but justified by the tool's complexity; could be shorter but acceptable.

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 (composite check, two services, multiple return types, partial failures, ecosystem limitation) and absence of an output schema, the description covers all necessary aspects: what is returned (fields, advisories, links, alternatives), timing, graceful degradation, and ecosystem scope. It is fully complete for an agent to use correctly.

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

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

Schema covers package and version with 100% description. The description adds value by noting that scoped packages (e.g., @types/node) are accepted for the 'package' parameter, which is not explicit in the schema. It also reinforces version defaults. Overall, it clarifies acceptable inputs beyond schema.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia, with a specific verb ('scan') and resource ('dependency'). It distinguishes from sibling tools by specifying the npm ecosystem and the exact use case ('should I add this npm package?'). The function is unique among siblings, which include generic research 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: 'whenever an agent asks is X safe / popular / small' and gives a concrete example ('what does adding lodash cost me'). Also tells when not to use: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. Provides guidance on partial failures and timing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds return value composition (headlines, descriptions, sources, dates) beyond annotations, providing useful behavioral context.

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

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

Two sentences, front-loaded with the primary action, no extraneous words. Every sentence adds value.

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

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

For a search tool with output schema, the description covers key inputs and outputs. Lacks mention of pagination or sorting, but overall adequate given schema richness.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates filter options and categories but adds minimal new meaning beyond what the schema's parameter descriptions already provide.

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 searches news articles by keywords, with a specific verb and resource. It distinguishes from sibling 'latest_news' by emphasizing keyword-based search and optional filters.

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 (search with keywords and optional filters) but does not explicitly contrast with alternative tools like 'latest_news' or provide when-not-to-use guidance.

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

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

Adds details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, character offset guarantees. Annotations already state safe and idempotent, but description enriches with technical specifics.

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

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

Single paragraph under 100 words, efficiently packing purpose, usage, and technical details. No filler.

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

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

Covers all essential aspects: purpose, usage, technical constraints, output format (offsets, scores). No output schema but description sufficiently explains returns.

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 repeats schema details (char limit, limit range) but adds query examples, which provides moderate added 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?

Clearly states it performs semantic search inside a fetched record, with specific output (passages, offsets, scores). Distinguishes from siblings like search_news and 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?

Explicitly says to use when the record is too large for prompt, and pairs with ask_pipeworx_grounded. Provides clear when-to-use guidance.

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

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

Annotations indicate non-read-only, open-world, idempotent, non-destructive. The description adds context: returns subscription id, webhook secret returned once, auto-disabled after 10 consecutive failures. No contradictions; adds value beyond annotations.

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

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

The description is comprehensive but not overly verbose. It is front-loaded with the core purpose, then breaks down types and delivery in an organized manner. Minor redundancy could be trimmed, but overall efficient.

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

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

Given no output schema, the description explains the return value (subscription id) and covers all aspects: authentication, type-specific parameters, delivery options with constraints, and failure behavior. Very complete for a creation 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?

With 100% schema coverage, the description still adds meaning: textual examples for each type's params, delivery channel details (email pattern, SMS verification, webhook signing). This goes beyond the schema's bare 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 'Create a proactive monitoring subscription to a live-data event stream' and directs the agent to its purpose. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. Specific verb and resource are present.

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 context: requires a Pipeworx OAuth account (anonymous/BYO cannot persist subscriptions), details supported types and parameters, and notes delivery channel constraints (phone verification, SMS cap). It does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds context about returning category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog, 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?

Description is front-loaded with the core purpose and includes example trigger questions but is slightly lengthy. Still, every sentence adds value.

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

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

Despite no output schema, description fully explains return format (category-bucketed example questions with tool+argument shapes) and usage context (onboarding). No gaps.

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

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

Schema covers the single optional parameter topic with 100% coverage, but description enriches by listing example focus areas and explaining the effect of omitting vs. providing the parameter.

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

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

Description clearly states the tool is an onboarding entry point for discovering what Pipeworx can do, returning categorized example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it provides ideas and examples.

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 provides guidance on calling with no arguments or with a topic. Lacks explicit when-not statements but gives clear context for 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?

The description adds value beyond annotations by disclosing ownership enforcement, deactivation vs. deletion, and retention of historical events. It does not contradict annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) and provides behavioral context that annotations alone do not cover.

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: the first states the purpose, the second adds constraints and side effects. Every sentence contributes necessary context, with no redundant or extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, ownership rule, deactivation behavior, and linkage to 'recent_alerts.' It is fully sufficient for an AI agent to understand and correctly invoke the tool.

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

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

The schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description merely says 'Cancel a subscription by id,' which adds no new semantic meaning beyond the schema. With 100% schema coverage, baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' using a specific verb (cancel) and resource (subscription). It adds context about ownership enforcement and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by clarifying the action and constraints.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use and implies when not to. It also mentions that the row is deactivated, not deleted, linking to 'recent_alerts' for history, but lacks explicit exclusions or alternatives for other scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by explaining the two routing paths, the exact verdict set, the meaning of 'could_not_verify' (with verification_error structure) versus 'unsupported', the percent-delta math, and the inclusion of verbatim evidence and citations. This rich behavioral context is not available in annotations.

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

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

The description is dense but well-structured: trigger phrases first, then usage, then internal routing, then output semantics, then crucial caller warnings. Every sentence adds operational value; the warning about 'could_not_verify' is especially important. It is appropriately sized for the tool's complexity and fronts the purpose immediately.

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

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

Despite having no output schema, the description fully explains the return payload (verdict, actual value with citation, reasoning) and the error cases. It also covers the two routing paths and how they differ. For a tool with this complexity, the description leaves no significant gaps for an agent to invoke and interpret the result 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 both parameters are documented in the schema. The description adds meaningful context by explaining how tolerance_pct overrides the claim's implied tolerance, the accepted range (0.5–50), and its use in hallucination detection. It also ties the parameter to the percent-delta grading logic, which enhances understanding beyond the raw schema.

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

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

The description clearly defines the tool as natural-language claim verification with specific trigger phrases like 'fact check' and 'verify the claim that…'. It states the resource (claims) and the action (validate against authoritative sources), and distinguishes it from siblings by framing it as a single-call replacement for a multi-step verification pipeline.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear usage directive. It also gives internal routing guidance (SEC EDGAR fast path vs. grounded pipeline) and when to set tolerance_pct for hallucination detection. However, it does not explicitly name when-not-to-use alternatives like ask_pipeworx_grounded, so it stops short of full exclusion guidance.

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