Vizier

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds return structure (per-model {score, confidence, signals, raw_response} + combined), default model details, and cost implication for Anthropic calls. No contradictions.

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

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

Description is 4 sentences, front-loaded with main purpose. Every sentence adds value: what it does, how to use, return structure, use cases. No redundancy.

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

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

Given 4 parameters, 100% schema coverage, no output schema, the description fully explains tool behavior, parameters, return format, and use cases. Nothing critical is missing.

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

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

Schema has 100% description coverage. Description adds value by explaining the default model behavior, the condition for _apiKey, and the purpose of context param. It clarifies usage details beyond schema descriptions.

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

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

Description clearly states the tool probes LLMs for entity knowledge and returns visibility scores (0-100). It specifies the verb 'probe', the resource 'LLMs', and the outcome 'score visibility'. It distinguishes from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing specifically on AI visibility audits.

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

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

Provides explicit guidance on default model (Workers AI free) and how to enable Anthropic with BYO API key. Suggests use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. No explicit when-not to use, but the context of sibling tools 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: it routes to many source tools, fills arguments, returns stable citation URIs, is one fast call, and works on every tier. It does not cover failure modes or rate limits, but that is a minor gap given the annotation coverage.

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

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

The description is longer than typical but front-loads the core directive and organizes content with clear sections: scope, mechanism, triggers, examples, and escalation. Some redundancy exists ('even if web search could also answer it' and repeated START HERE/step-up guidance), but the structure remains scannable and informative.

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

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

For a broad router tool with no output schema, this description covers input expectations, typical use cases, concrete examples, sibling alternatives, and return characteristics (structured answers with citations). Nothing material is missing for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for the same natural-language question. The description reinforces the question domain with examples, but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description states a specific mechanism: routes the question to one of 5,743 tools, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from siblings by declaring itself the default entry point and explicitly contrasting ask_pipeworx_grounded and deep_research.

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

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

It gives explicit when-to-use triggers ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions') and explicit step-up conditions for ask_pipeworx_grounded and deep_research. It also addresses the news edge case directly, leaving little room for misrouting.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds genuinely useful context: candidate routing improvements are enabled live when under test, no candidate is currently active, and it currently matches ask_pipeworx exactly. It also explicitly states the response shape is identical to ask_pipeworx, which compensates for the lack of an output schema.

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

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

The description is longer than a simple one-liner but every sentence earns its place: it defines the variant, explains the current live state, gives usage instruction, and prevents a fallback misinterpretation. There is some minor redundancy between 'currently matches ask_pipeworx exactly' and 'No candidate is active right now,' but the structure is logical and front-loaded with the key identity statement.

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 variant tool whose semantics are identical to ask_pipeworx, the description provides the critical extra context: experimental status, live candidate behavior, current parity with stable, and response-shape equivalence. It relies on the agent knowing ask_pipeworx for underlying details, which is reasonable given the sibling relationship. No output schema exists, but the description explicitly points to the stable tool's response shape.

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

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

The input schema already describes all six parameters with 100% coverage: `question` is the canonical parameter and the other five are documented aliases. The description adds no new parameter-level meaning beyond saying the tool takes the same arguments as ask_pipeworx. Since the schema carries the full burden, the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, specifying it is an identical universal router with the same 5,743 tools, arguments, and response shape. It differentiates it from the stable ask_pipeworx by its experimental, candidate-improvement nature. It could be slightly clearer about what the underlying universal router does, but the name, schema, and sibling context make the purpose reasonably unambiguous.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, directly naming the alternative and the condition for choosing it. It also clarifies that this is not a fallback — it is a full working router — and that results are compared against the stable router, which explains the beta context. This is strong, concrete usage guidance.

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

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

Beyond the readOnly/openWorld/idempotent/non-destructive annotations, the description discloses substantial behavioral detail: the extraction is limited to tool-result content, success includes verbatim evidence and confidence, and refusal reasons are enumerated explicitly. It also reveals the cost trade-off of one extra LLM call versus the sibling.

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

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

The description is dense but every clause earns its place: mode, routing, extraction constraint, return shape, refusal shape, use cases, and cost comparison. It is front-loaded with the most important differentiator and remains readable despite the detail.

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

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

Given there is no output schema, the description compensates by specifying both the success and refusal response shapes, including refusal reason enumerations. It also covers the operational context (cost, routing, when to use), making it self-sufficient for an agent deciding whether and how to invoke the tool.

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

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

Schema description coverage is 100%, so the schema already fully documents the single meaningful parameter (question) and its aliases. The description adds no additional parameter-level semantics, which is acceptable given full coverage; baseline 3 is appropriate.

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

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

The description identifies a precise, distinctive function: a hallucination-resistant, evidence-grounded answer mode that routes like ask_pipeworx but extracts answers only from the tool result. It clearly differentiates itself from the sibling ask_pipeworx by emphasizing refusal behavior, evidence quotes, and high-stakes suitability.

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

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

The description gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with domains like financial verdicts, legal claims, and medical lookups. It also explicitly states when not to use it by preferring ask_pipeworx for casual lookups due to the extra LLM call.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive behavioral details: resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits for low confidence or closed markets, and resolution-rule risk. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, etc.) and front-loaded with the core purpose. Every sentence provides substantive information. Could be slightly more concise, 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?

Despite no output schema, the description meticulously details the response structure, including result.market, result.analysis, result.evidence, resolver contract, parent event extractor, news fields, safety mechanisms, and cancellation rules. This compensates fully for the lack of output schema and covers all relevant contexts for an agent.

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

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

Schema description coverage is 100%. The description adds significant value beyond the schema: it explains the market parameter can be a slug, URL, or question text; depth options (quick vs thorough) are detailed; include_raw is explained with context on typical response sizes. Examples in input schema further clarify usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains the input flexibility, classifiers, fan-out to data packs, and output contents. This distinguishes it from siblings like polymarket_edges or polymarket_arbitrage, as it's a comprehensive research tool for individual bets.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides guidance on when to use the tool. However, it does not explicitly exclude cases or mention alternatives for when not to use it, so it scores a 4.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds no behavioral context beyond annotations, but does not contradict them.

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

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

Single sentence, front-loaded with key action. No wasted words.

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

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

Adequate for a simple search tool with good annotations and output schema. Could explain what VizieR is or how search works, but minimal is acceptable given tool simplicity.

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

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

Schema description coverage is 100% with clear descriptions for query and max. Description adds no extra meaning, meeting 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?

Description clearly states verb (Search) and resource (VizieR catalogue metadata), making purpose clear. However, it does not differentiate from sibling tools like query_catalog or cone_search, which also search catalogues.

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

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

No guidance on when to use this tool versus alternatives (e.g., cone_search, query_catalog) or what context is appropriate. Lacks any when/why information.

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 data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This goes well beyond the annotations, providing rich behavioral context.

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

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

The description is front-loaded with example queries and every sentence provides value. While slightly verbose, it is efficient and structured well for quick comprehension.

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

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

Given no output schema, the description adequately explains inputs, behavior, and output format (paired data + citation URIs). It covers the essential context needed for correct 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?

The input schema covers 100% of parameters with descriptions. The description adds examples for values (tickers/CIKs vs drug names), explains data pulled per type, and clarifies min/max constraints, adding semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It provides example queries and distinguishes it from sequential lookups, making its purpose unambiguous.

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

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

The description explicitly advises ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities. It gives usage contexts like comparing, ranking, head-to-head. However, it does not explicitly state when not to use it, 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the behavioral profile is clear. The description adds no additional behavioral context, which is acceptable but not enhanced.

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

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

The description is very concise (6 words), but it lacks structure and fails to provide essential details. While concise, it sacrifices clarity for brevity.

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 (5 parameters, domain-specific), the description is insufficient. It does not explain what a cone search entails, the meaning of parameters, or how it relates to sibling 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 description coverage is 40% (only 'ra' and 'dec' have descriptions). The tool description does not add meaning to the undocumented parameters 'catalog', 'max', and 'radius_deg', which are crucial for usage.

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 'Cone search around (RA, Dec)' clearly indicates the tool performs a cone search given coordinates. It is specific and not a tautology, but it lacks differentiation from sibling tools like 'query_catalog'.

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

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

No usage guidelines are provided. The description does not state when to use this tool versus alternatives, nor does it specify any prerequisites or restrictions.

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 it read-only/idempotent, and the description adds substantial behavioral context beyond those hints: parallel facet routing, gaps[] for unanswered facets, contradictions[] scanning on standard/thorough, per-finding citation_uri with a fetchability guarantee, semantic excerpting, and latency bounds. It contradicts no annotation.

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

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

The description is long, but nearly every sentence carries decision-relevant information: auth prerequisite, scope, exclusions, output packet shape, depth semantics, and latency. It is front-loaded with the account warning. It could be lightly restructured with paragraphs, but it contains no real 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?

Given the tool's complexity and the absence of an output schema, the description is highly complete: it covers prerequisites, when-not-to-use, output structure, citation semantics, depth behavior, and expected latency. An agent has enough to invoke it correctly and anticipate its return shape.

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 does add a small amount of extra parameter context (e.g., thorough requires a paid plan, and the practical effect of each depth level), but it mostly restates or lightly expands what the schema already documents for depth and question.

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 names a specific verb ('research') and a specific resource ('Pipeworx's 1500 STRUCTURED data sources'), and explicitly contrasts itself with open-web search. It also distinguishes itself from ask_pipeworx by positioning deep_research as the multi-facet, parallel-decomposition 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?

It states exactly when to use it ('Best for broad/multi-part questions over structured data') and gives explicit alternatives: single lookups and breaking/current-news topics should go to ask_pipeworx. It even handles the not-signed-in case by routing to ask_pipeworx. Little is left to inference.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true; the description adds that it returns top-N tools with full schemas and curated examples ready to call, which is valuable behavioral context beyond annotations.

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

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

The description is front-loaded with the core purpose and includes a detailed list of domains, which is informative but slightly verbose; however, 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 lacking an output schema, the description fully explains what is returned (top-N tools with schemas and examples) and how to use it, making it complete for a discovery tool with 6 parameters and no nested objects.

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

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

Schema coverage is 100% with detailed descriptions for all 6 parameters; the description restates alias behavior but doesn't add significant new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task', provides specific domains (SEC filings, FDA drugs, etc.), and distinguishes this discovery tool from sibling tools that focus on specific tasks like deep_research or entity_profile.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set', giving clear when-to-use guidance and implied before other tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, lowering the bar. The description goes well beyond that by disclosing soft-failure of the USPTO PatentsView sunset, that an empty fda_products section is expected for small-molecule-only companies, that a private company returns resolved:false with a notes field, and that sources_used/sources_failed distinguish real no-data from bugs.

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 very dense single paragraph, but it is front-loaded with trigger phrases and the ALWAYS PREFER directive. Every sentence adds real information about sources, return fields, or edge cases, so there is no waste; however, a bulleted structure 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, the description carries the full burden of explaining return values, and it does so thoroughly: cik, company_name, resolved fields, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/failed. It also covers input edge cases and failure semantics, leaving nothing an agent needs 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%, but the description adds meaningful examples (AAPL, 0000320193, Moderna), explains that type's two values are interchangeable, and details that company names resolve via SEC EDGAR's company-name match. It also clarifies resolved_from/resolved_to behavior for name inputs, far exceeding what the schema alone provides.

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

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

The description opens with concrete trigger phrases and immediately states 'full cross-source profile of a US public company in ONE parallel call,' giving a specific verb, resource, and scope. It also contrasts itself with chaining single-pack SEC/XBRL/news lookups, so an agent can clearly tell it apart from alternative approaches.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides numerous example phrasings that should trigger this tool. It does not explicitly name sibling tools like resolve_entity or compare_entities as alternatives in specific conditions, leaving some inference to the agent.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not elaborate on idempotency behavior (e.g., what happens if key doesn't exist). No contradiction with annotations.

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

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

Two concise sentences: first states action, second provides usage context and sibling pairing. No wasted words, front-loaded with purpose.

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

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

For a simple one-parameter tool with annotations covering destructiveness and idempotency, the description covers purpose, usage, and pairing. Slight gap: does not explain idempotency implications (safe to delete missing key). Overall sufficient.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete.' The description adds no additional meaning beyond the schema. 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 specifies 'Delete a previously stored memory by key,' with a specific verb and resource. It distinguishes itself from sibling tools by mentioning 'Pair with remember and recall,' indicating its role in the memory lifecycle.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with related tools. Lacks explicit when-not-to-use guidance, but positive scenarios are clear.

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

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

Annotations already indicate the tool is read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: fetches the page, extracts title/description/key links, emits standard markdown format. This goes beyond annotations without contradiction.

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

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

Two sentences provide all necessary information: first sentence defines purpose and output, second sentence lists use cases. No redundancy or 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 (2 parameters, no output schema, comprehensive annotations), the description covers input, process, output format, and use cases completely. No gaps remain.

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

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

Schema coverage is 100% with both parameters described. The description does not add much semantic detail beyond the schema; it explains that the URL is fetched and max_links controls link entries, but the schema already provides descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generate a production-ready llms.txt file for any URL. It specifies the verb (generate), the resource (llms.txt file), and the target audience (AI crawlers). This is distinct from any sibling tool, which focuses on other tasks.

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: getting a client's site indexed, drafting for own project, auditing competitor AI crawler view. This provides clear context for when to use the tool, though it does not explicitly mention when not to use or alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by clarifying that it returns specific fields (id, type, etc.) and defaults to active subscriptions, and that it is scoped to the caller. 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?

Two concise sentences: first states purpose and return fields, second gives usage context. No wasted words; information 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 simple read tool with one optional parameter, full annotations, and no output schema, the description is complete: it explains what it does, what it returns, and when to use it. An agent can correctly invoke it without ambiguity.

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

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

Schema coverage is 100% with one parameter described. The description adds meaning beyond the schema by listing the return fields, which helps an agent understand what data to expect, even though it doesn't restate parameter details.

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 'List the caller's active subscriptions', specifying the verb (list) and resource (subscriptions) and adding scope (caller's active). It distinguishes from siblings like subscribe and unsubscribe by focusing on reading.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use it, but doesn't explicitly state when not to use or name alternatives, though siblings imply them.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that resolution is via SIMBAD/NED, which is useful context but does not disclose further behavioral traits.

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

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

The description is a single concise sentence, front-loaded with the key purpose. No wasted words, though it could benefit from a bit more detail.

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

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

Given the simple 2-parameter tool and presence of an output schema, the description is minimally adequate but omits details like pagination or behavior on no results.

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 little meaning beyond the schema: it mentions 'object name' but does not explain input formats or valid catalog IDs. With 50% schema coverage, the description should compensate but fails to do so.

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

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

The description clearly states the verb 'Query' and resource 'object name', and mentions the resolution via SIMBAD/NED. However, it does not differentiate from sibling tools like 'resolve_entity' or 'catalogs'.

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions.

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

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

Discloses significant behavioral details beyond the all-false annotations: the claim_token mechanism for later status retrieval, rate-limiting to 5 per identifier per day, absence of tool-call quota impact, and daily team review. 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?

Although the description is long, every sentence delivers actionable information—purpose, scope, feedback categories, boundary conditions, token mechanics, rate limits, and pricing. It is front-loaded with the core action and contains no redundant or filler text.

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

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

Despite lacking an output schema, the description explains the return value (claim_token) and how to use it later, along with submission guidelines, rate limits, and scope checks. This makes the tool operationally complete for an AI agent to invoke correctly.

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

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

While the schema already covers all four parameters with descriptions, the tool description adds meaningful usage constraints: instructing users not to paste end-user prompts, to describe issues in terms of Pipeworx tools/packs, and how to use claim_token to read prior feedback replies. This goes beyond the schema 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?

Clearly states the tool's core function: sending feedback to the Pipeworx team about broken, missing, or surprisingly good functionality. It distinguishes itself from sibling ask_pipeworx tools by focusing on feedback submission rather than information retrieval.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and when-not-to-use (tools from other MCP servers), with a concrete alternative (file with that server). Also clarifies how to identify Pipeworx tools, giving agents clear decision criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that data is derived from CF analytics-engine, no PII, and cached 5min-1h, which are valuable behavioral details 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?

Description is concise with no wasted words, front-loaded with the key output, and uses bullet points for use cases. Each sentence earns its place.

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

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

Given low complexity (1 param, no output schema), the description adequately covers what the tool returns and how to use it. It could hint at the return format, but overall it is complete.

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

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

Only one parameter (window) with schema coverage 100%. Description adds semantic value by explaining the effect of different windows: shorter for hot right now, longer for steady-state demand.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, with three specific use cases. It distinguishes itself from siblings by focusing on trending activity rather than discovery or querying.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment). It does not explicitly state when not to use, but the use cases are clear enough for an agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: monotonicity checks, partition_sum validation, Jaccard similarity threshold, placeholder filtering, and live CLOB depth fill check. 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?

Long but well-structured with clear sections. Every sentence adds value, though the density of technical details could be slightly streamlined.

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

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

No output schema, but description thoroughly explains output fields (opportunities[], partition_check, fill check results) and refers to polymarket_fill_risk for additional needs. Complete for a complex arbitrage 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% with descriptions for both parameters. Description further clarifies event slug format, topic as seed question, and provides usage recommendations 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?

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly describes when to use each mode: no args for trending scan, event for specific event (recommended), topic for cross-event scanning. Also advises against trading when fill check shows no realizable edge and directs to polymarket_fill_risk for custom sizing.

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

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

Description discloses extensive behavioral details including model calculations, edge derivation (edge_pp_net, kelly_fraction), filtering logic, Fed bets handling, caching behavior, and diagnostics. Annotations indicate read-only, open-world, and idempotent traits, which are consistent and well-supported.

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

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

Although lengthy, the description is well-organized into segments and uses clear structure. Every sentence adds value given the tool's complexity, but slightly verbose overall.

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

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

Provides complete context for a complex tool with 9 parameters and no output schema. Covers output structure (three segments, diagnostics), caching, edge cases (Fed bets exclusion), and practical usage guidance. No gaps identified.

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

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

All 9 parameters have rich descriptions in the input schema (100% coverage). The description adds further context beyond schema, such as explaining slippage assumptions, why min_kelly doesn't affect partition arbs, and practical guidance for each knob.

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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, explicitly designed for 'what should I bet on today'. It distinguishes from general market scanning by detailing three specific model families.

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

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

Provides clear context that the tool is for discovering trading opportunities without paging, and includes specific parameter guidance (e.g., slippage_pp advice, min_kelly filters). However, it does not explicitly contrast with sibling tools 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 richly explains behavioral traits beyond annotations: data comes from daily snapshots with a 60-day TTL, gaps mean no cache-miss, decay computed from daily closes net of default slippage. This aligns with and complements the annotations (readOnlyHint, idempotentHint, etc.) without contradiction.

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

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

The description is well-structured: a clear purpose sentence, followed by a detailed breakdown of the response fields and limits. Every sentence is informative, and the key information 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?

Despite having no output schema, the description thoroughly covers the return values (tracked[], expired[], snapshot_dates[]) with field explanations and limits. This makes the tool fully understandable without additional 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?

The description adds default values and constraints for both parameters (days default 14 max 30, window default '1wk') and explains their purpose. Since the input schema already provides full descriptions (100% coverage), the description adds moderate value by restating defaults and clarifying the 'window' as a snapshot family.

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

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

The description clearly states it provides edge persistence and decay telemetry, answering a specific analytical question about edge longevity. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical snapshots rather than current edges.

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 the tool: to assess how long an edge has existed and whether it is shrinking. It provides context that a fresh wide edge differs from an old wide edge, implying the tool's value. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description aligns by detailing read-only checks. It adds behavioral context: returns verdict, slippage, shares_filled, and warns about forced directional risk from partial basket fills. 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 long but well-structured with key phrases in caps (REQUIRES, SINGLE-MARKET, BASKET). It front-loads the core purpose. Every sentence adds value, though slight trimming could improve conciseness without losing 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?

No output schema, so the description fully documents return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also explains forced_directional_risk. For 4 parameters, this is complete.

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

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

Schema description coverage is 100%, but the description adds significant meaning: clarifies side defaults (auto for basket), size_usd interpretation (max spend vs target proceeds), and market/event as slug or URL. This enriches understanding beyond the schema.

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

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

The description states the tool is for 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly separates single-market and basket modes, providing a specific verb-resource combination. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills cause directional risk) and names 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?

With readOnlyHint and idempotent annotations already covering the safety profile, the description adds substantial extra behavior: keyword-based matching, compatibility_codes, the gross-not-net fee caveat, skipped_unclassified handling, and the exact meaning of null temporal_alignment. It also discloses that returned pairs may still carry warnings, which is essential honest behavior. No contradiction with annotations.

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

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

The description is long, but it is well-structured with mode, response, safety, and fee sections, and nearly every sentence carries necessary operational detail. It is heavier than a truly concise definition, but the complexity of the tool and the absence of an output schema justify the density.

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

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

Despite having no output schema, the description documents the key response fields, spread semantics, safety codes, skipped counters, alignment meaning, and fee limitations. An agent has enough context to decide when to call the tool and how to interpret returned warnings in either mode.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by explaining that both modes run the identical token-overlap matcher and that explicit ticker/slug parameters override topic-mapped sides. It reinforces how the optional parameters interact without merely restating 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 that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, naming the specific resource and outcome. It is unambiguous but does not explicitly contrast itself with sibling tools like polymarket_arbitrage, so it stops short of full sibling differentiation.

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

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

The description explains TWO MODES — topic shortcuts versus explicit kalshi_event_ticker plus polymarket_event_slug — and includes practical caveats like 'pre-mapped ≠ tradeable' and 'most pre-mapped topics return compatibility_warning today.' It gives clear operational context but never names an alternative tool for when this comparison is not what the agent needs.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the row limit (up to 50000 rows), constrains to a single catalog, and describes the input as a 'numeric constraint expression'. It also clarifies that it returns data rows, not metadata or summaries. 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 two sentences, front-loaded with the action and service, then adds limit and purpose. Every sentence contributes value without redundancy or fluff.

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

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

The description covers the essential aspects: catalog ID, row limit, column selection, constraint, and the nature of the data. With an output schema present and strong annotations, it does not need to explain return format or safety. Minor gaps like how constraints are parsed are covered by schema examples. Overall, sufficient for a read-only query 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 description adds meaning to parameters beyond the schema. It explains the catalog parameter as a VizieR ID with an example, describes columns as 'column selection', and defines constraint as a 'numeric constraint expression' and 'cut'—more informative than the schema's 'Solr-style constraints'. The schema covers most parameters, but the description compensates for the undocumented 'catalog' field.

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: 'return data rows from one published catalogue' via the VizieR service. It specifies the resource (VizieR astronomical catalogue service at CDS Strasbourg) and the action (query by catalog ID), distinguishing it from sibling tools like cone_search or catalogs by focusing on row extraction from a known catalog.

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

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

The description provides clear context on when to use the tool: when you have a VizieR catalog ID and want rows of objects meeting a constraint. It also mentions the optional column selection and constraint expression, implying use cases like filtering by numeric parameters. It does not explicitly exclude alternatives or mention sibling tools, but the guidance is sufficient for typical 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping detail ('Scoped to your identifier...') which is useful behavioral context beyond 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 sentences, front-loaded with the core purpose. Every sentence adds unique value: retrieval/listing, usage examples, scoping, and pairing with siblings. No wasted words.

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

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

Given one optional parameter, no output schema, and rich annotations, the description fully covers what the tool does, how to use it (including missing key behavior), scoping, and inter-tool relationships. Complete for a simple retrieval tool.

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

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

Schema coverage is 100% for the single parameter, which already describes 'omit to list all keys'. The description reinforces this usage but adds no new semantic detail beyond the schema.

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

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

The description specifies a clear verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes from sibling tools like remember and forget by explicitly naming them.

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

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

Explicitly states when to use: 'look up context the agent stored earlier' with concrete examples (ticker, address, notes). Advises pairing with remember (save) and forget (delete), providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context such as mark_read side effect, polling suitability, and the returned fields (source, citation_uri, payload), going beyond what annotations provide.

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

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

The description is two sentences plus a short note, all front-loaded with the core purpose and essential details. No filler or repetition.

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

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

Despite lacking an output schema, the description explicitly states what returned data includes (source, citation_uri, payload) and covers key behaviors (filtering, mark_read, polling). It is fully sufficient for an agent to understand and 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?

Schema coverage is 100% with clear parameter descriptions. The description adds example usage for 'type' and 'since', and explains 'mark_read', but does not deeply elaborate on 'limit' or 'unread_only' beyond what's in the schema. This meets the baseline for high-coverage schemas.

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

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

The description starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It distinctly separates from sibling tools like ask_pipeworx or list_subscriptions by focusing on alerts from a subscription feed.

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

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

The description gives clear context for when to use this tool (retrieving recent alerts, polling, using filters) and mentions an alternative endpoint for scripts/dashboards, but does not explicitly contrast with specific siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it fans out to multiple sources in parallel, uses a fallback order, and soft-fails for USPTO. It also explains the return structure (changes[] grouped by source, total_changes count, citation URIs), which is not covered by 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 appropriately sized, front-loaded with the tool's purpose and typical queries, then progressively detailing sources, parameters, and fallbacks. Every sentence adds necessary information without redundancy.

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

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

Despite lacking an output schema, the description explains the return structure (changes grouped by source, total_changes count, citation URIs). It covers the multi-source nature, fallback behavior, and soft-fail conditions. For a complex aggregation tool, this is complete and well-contextualized.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'since' parameter format (ISO date or relative shorthand with examples like '7d', '30d', '3m', '1y'), the 'value' parameter accepting ticker or CIK, and the 'type' enum limitation to 'company'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool answers queries like 'What's new with X' and 'latest on Y', specifying it returns a change feed for a company from multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes from the sibling tool entity_profile by contrasting dynamic changes vs static profile.

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

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

The description explicitly provides when-to-use guidance: 'Use entity_profile instead when you want the static profile regardless of window.' It also explains the fallback mechanism (GDELT→GNews) and the soft-fail for patents, giving clear context on when results may be incomplete.

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 idempotent and non-destructive. Description adds valuable context: persistent vs. 24-hour retention, scoping by identifier. No contradictions.

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

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

Three sentences, front-loaded with purpose, each 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?

Covers use cases, retention policy, scoping, and pairing with other tools. No output schema needed; description is complete for this simple tool.

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

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

Schema coverage is 100%, so description adds marginal value. Provides example key naming conventions, but doesn't significantly expand beyond schema meaning.

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

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

The description clearly states the tool saves data for reuse across sessions, with specific verb 'save' and resource 'key-value pair'. It distinguishes from sibling tools recall and forget by naming them explicitly.

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 tells when to use: 'Use when you discover something worth carrying forward' and provides examples. Also mentions pairing with recall and forget, offering clear 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 mark this as read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral detail beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit listing of unresolved identifiers, returning figi_candidates on ambiguity, labeling identifier sources, and cascading through multiple lookup endpoints. No contradiction with annotations.

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

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

The description is long and dense, but the tool is genuinely complex with two entity types and several edge cases. It is front-loaded with purpose and usage, then structured around SUPPORTED TYPES. Some parenthetical asides could be trimmed, but most sentences carry disambiguation value; the final 'replaces 2-3 manual lookups' is the only clearly non-essential sentence.

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

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

For a tool with no output schema, the description explains key return behavior: unresolved identifiers are listed under unresolved, ambiguous FIGI matches yield figi_candidates, drug results include RxCUI/ingredient/brand and a citation, and enrichment failures degrade to EDGAR results. Combined with exhaustive parameter semantics and type coverage, an agent has enough to call and interpret this tool correctly.

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

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

Schema coverage is 100% and both parameters have descriptions, but the tool description adds critical guidance: for company, value accepts ticker, CIK, ISIN, or name; for drugs it accepts brand or generic; and for bonds it instructs passing the issuer exactly as printed without trailing security-class words. This goes well beyond the schema and materially reduces invocation errors.

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

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

The description states a specific verb and resource: resolve user-spoken names to canonical/official identifiers consumed by other tools. It includes concrete input examples, supported entity types, and clarifies that it handles non-equity instruments and ISIN-to-entity resolution, making it easy to distinguish from sibling tools like compare_entities or entity_profile.

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

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

The description gives an explicit directive: 'Use FIRST whenever you have a name but need an ID,' and provides numerous query patterns. It does not explicitly name alternative tools or state when not to use it, but the 'first step' framing and the ID-oriented purpose effectively communicate placement among siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it internally calls ai_visibility_check and returns a ranked list with score, confidence, and signal density per entity, providing behavioral context beyond the annotations.

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

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

The description is four sentences, front-loaded with the purpose, and every sentence adds value—no fluff or repetition.

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

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

The tool has 4 parameters, no nested objects, and no output schema. The description specifies the return format (ranked list with score, confidence, signal density), which is sufficient for an agent to understand the output. Annotations cover safety and idempotency. Complete for the tool's complexity.

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

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

Schema coverage is 100% (all 4 parameters described in schema). The description adds meaning by explaining that the first entity is treated as the 'subject', models default to workers-ai, _apiKey is needed for anthropic, and context disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (more generic).

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 it is useful for competitive AI-marketing audits and gives an example query. It implies use when comparing multiple entities, but does not explicitly mention when not to use or list alternatives like calling ai_visibility_check multiple times.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true), the description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, sources_failed lists timeouts.

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, well-structured sentence front-loads purpose, then enumerates output, ecosystem scope, and fallback behavior. No redundancy, every clause earns its place.

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

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

For a 2-parameter, no-output-schema tool, the description fully explains output fields, behavior on partial failures, ecosystem limitations, and typical use cases. Complete and actionable.

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

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

Schema coverage is 100% with good descriptions. The description adds extra context: scoped packages accepted and default to latest version when omitted. Adds value beyond schema.

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

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

The description clearly states the composite check for adding an npm package, with specific verb 'scan' and resource 'dependency'. It distinguishes from siblings by being a one-call composite across deps.dev and bundlephobia.

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

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

Explicit guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' Also notes NPM-only in v1 and points to deps.dev:version for other ecosystems.

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

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

The description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, etc.) by disclosing the embedding model (BGE-base-en), windowing (overlapping 500-char windows), character cap (200K chars with truncation flagging), and return format (offsets, similarity scores). 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 two substantive sentences plus a concise technical note. Every sentence is essential, front-loaded with the core action, and there is no redundant or filler content.

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

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

For a tool with no output schema, the description adequately explains input details, behavior (embeddings, windowing, truncation), and return fields (passages with offsets and scores). It does not detail the exact JSON response structure, but the context is sufficient for selection and invocation.

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

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

Schema coverage is 100%, and the description adds value by specifying the limit's range (1-20) and default (5), and by providing natural-language query examples. The schema already describes each parameter well, but the description enhances clarity.

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 'semantic search inside a fetched record' and provides concrete examples (SEC 10-K, article, tool result). It contrasts with siblings by mentioning it pairs with ask_pipeworx_grounded, distinguishing its purpose effectively.

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

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

Explicitly advises when to use this tool: 'Use when the record is too big to cram into the prompt' and explains how it saves context and returns relevant passages. It also suggests pairing with ask_pipeworx_grounded, providing clear guidance on alternatives.

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

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

Annotations indicate idempotent, not read-only, not destructive. Description adds rich behavioral context: return value, delivery channel mechanics, SMS verification and cap, webhook auto-disable. 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?

Dense and well-structured, starting with purpose then requirements, examples, and delivery options. Every sentence adds value, though slightly lengthy; could be streamlined with bullet points but remains clear.

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

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

Covers all key aspects: types, params, delivery, limitations, return value. No output schema, but description states returns subscription id, which is sufficient. Minor gap: no explicit response structure beyond id.

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

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

Schema has 100% coverage, but description provides extensive additional meaning: type-specific examples, delivery channel formats, constraints, and requirements (e.g., verified phone). 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation and providing specific resource details.

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

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

Explicitly notes OAuth requirement, delivery channels, and rate limits. Implies when to use (for live event monitoring) but lacks explicit comparison to alternatives. Nonetheless, context is clear enough.

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

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

Annotations already indicate read-only and non-destructive. Description adds that it returns category-bucketed examples with tool+argument shapes, drawn from a live catalog. 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?

Well-structured with front-loaded examples and clear sections, but somewhat verbose with many example queries. Could be more concise.

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

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

For a simple 1-param tool with no output schema, the description fully explains purpose, usage, and return type. No missing critical info.

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 parameter well (100% coverage). Description reinforces that omitting topic gives full spread and lists possible values, adding context 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's purpose: to suggest example questions for Pipeworx, especially for onboarding. It lists categories and distinguishes from sibling tools like ask_pipeworx.

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' and explains when to pass a topic vs. omit. Provides clear guidance on alternatives.

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

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

Adds significant behavioral context beyond annotations: ownership enforcement (only own subscriptions), soft deactivation (row not deleted), and linkage to recent_alerts for historical events. Annotations already indicate idempotent and non-destructive; description complements 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, no redundant words. Action is first word. Every sentence adds value: effect, ownership, and impact on historical data.

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 mutation with one required parameter and no output schema, description covers action, constraints, and side effects. No missing information needed for agent to invoke correctly.

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

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

Parameter 'id' has clear schema description (uuid from subscribe). Schema coverage is 100%. Description does not add additional semantics beyond referencing 'id', so baseline 3 is appropriate.

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

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

Clear verb 'cancel' with specific resource 'subscription by id'. Distinguishes from 'subscribe' (create) and 'list_subscriptions' (list). Ownership enforcement and deactivation-not-deletion are stated, making purpose unambiguous.

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

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

Implied usage: cancel your own subscriptions. Ownership enforcement is explicitly stated. Does not explicitly list alternatives or when-not-to-use, but context from sibling tools and description of historical events via recent_alerts provides 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?

Even with annotations declaring read-only/idempotent behavior, the description adds substantial context: the dual fast-path/grounded pipeline, the precise list of verdicts, the meaning of verification_error, and the crucial warning that could_not_verify must not be treated as evidence. This goes far beyond what annotations convey.

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

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

The description is long but every sentence earns its place: trigger phrases, usage, processing paths, return values, caller warning, and efficiency benefit. It is well-structured, front-loaded with the most important info, and avoids redundancy with structured fields.

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

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

With no output schema, the description takes on the burden of explaining return values. It does so comprehensively, listing all verdicts, mentioning citations and reasoning, and distinguishing error states. It also covers the full scope of claims (company-financial and other), making it 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?

The input schema fully describes both parameters with examples and tolerance details (100% coverage), so the description does not need to repeat them. While the claim parameter is contextually illustrated in the description (e.g., company financial examples), no additional parameter-level semantics are provided beyond the schema, matching the baseline.

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

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

The description explicitly defines the tool as 'natural-language claim verification against authoritative sources' and provides trigger phrases like 'fact check' and 'verify the claim that…'. This clearly distinguishes it from sibling tools such as deep_research or ask_pipeworx by focusing on confirming/refuting specific factual claims.

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

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

It states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It also breaks down the two major claim types (company-financial vs. other) and how each is handled, but does not explicitly name alternative tools or state when NOT to use it, so it falls short of a 5.

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