Pubchem

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds context about default model, free vs. paid usage, and API key handling. It does not contradict annotations and provides additional behavioral insight.

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

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

The description is three sentences long, front-loads the main purpose, and contains no filler. Every sentence earns its place.

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

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

Despite no output schema, the description fully explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). The four parameters are well-documented in the schema and description, making the tool understandable.

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 default model and that _apiKey is passed to Anthropic, and that context helps disambiguate entities.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the resource (LLMs for business/brand/product/topic). It distinguishes itself from siblings like deep_research and scan_competitor_ai_presence by focusing on AI visibility scoring.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide _apiKey. However, it does not mention when not to use the tool or suggest alternatives 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 indicate idempotent and read-only behavior. The description adds value by mentioning that it routes to one of 5,564 tools across 1,462 sources, fills arguments, and returns structured answers with stable citation URIs. It also notes speed ('one fast call') and coverage. However, it doesn't disclose failure modes or rate limits, but with strong annotations, this is acceptable.

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 key message of preferring this over web search, followed by a list of data types, usage triggers, examples, and escalation guidance. It is long but each sentence serves a purpose, and the structure is logical. Slightly wordy but not wasteful.

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

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

Given the tool's complexity (routing to thousands of sources), the lack of output schema, and the presence of annotations, the description covers what the tool does, when to use it, what it returns, and how it relates to siblings. It is comprehensive and leaves little ambiguity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond what the schema provides (the question parameter and its aliases). The examples in the schema are informative but the description itself does not elaborate on parameter 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: it routes questions to authoritative structured data sources and returns answers with citations. It lists specific data domains (SEC filings, FDA drug data, etc.) and distinguishes itself from siblings like 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?

The description provides explicit guidance on when to use this tool versus alternatives like ask_pipeworx_grounded (for hallucination-resistant answers), deep_research (for broad questions), and web search. It also suggests using it as a default starting point and lists example triggers such as 'what is', 'look up', and 'find'.

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, idempotentHint), the description adds that the tool may have active routing improvements, is currently identical to the stable router, and that results are compared against the stable router to decide merges. This contextualizes the beta state without contradicting annotations.

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

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

Three concise sentences: definition, current state, and usage guidance. Every sentence adds value, and the most critical information (beta nature, routing improvements, current identity) 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?

Given the tool's complexity (universal router) and the absence of an output schema, the description provides sufficient context: identical to stable router, experimental nature, and usage purpose. Minor gap: no explicit warning about potential instability, but 'candidate improvements' implies it.

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

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

Schema coverage is 100% with all aliases documented. The description adds no parameter-specific meaning or usage examples, so the baseline of 3 stands.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router handling 5,564 tools with the same arguments and response shape. It specifically distinguishes from the stable sibling by mentioning candidate routing improvements and its experimental nature.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' The absence of explicit exclusions is mitigated by the presence of ask_pipeworx in sibling tools, allowing the agent to infer stability preference.

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 as true, and destructiveHint as false. The description goes beyond by explaining the extra extraction step, the structured success response fields (answer, evidence, confidence, source, fetched_at, refusal_reason:null), and explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). This provides rich behavioral context beyond what annotations cover, including the cost tradeoff and the guardrails against hallucination.

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 ('Hallucination-resistant answer mode for high-stakes reads'), then provides process details, return structure, use cases, and cost tradeoff—all in a compact, well-organized paragraph. Every sentence adds value 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?

Given the tool's complexity (routing across 5,564 tools, extra LLM call, structured responses with possible refusal reasons) and the lack of an output schema, the description is remarkably complete. It clearly explains what happens on success and failure, when to use it, and the tradeoff with ask_pipeworx. The input schema is simple with a single required param, and the description covers all behavioral aspects an agent needs for reliable 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% with a single required parameter 'question' and multiple aliases. The description does not add parameter-specific details beyond what the schema provides, but it does clarify the purpose of the question parameter in the context of grounded answering. Given the high coverage, this is adequate; the description focuses on the overall tool behavior rather than param syntax, which 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of selecting the right tool, fetching data, and extracting an answer using only the tool result. It distinguishes itself from ask_pipeworx by mentioning the same routing but an extra extraction step, and it differentiates from siblings by specifying use cases (financial verdicts, legal claims, etc.) where fact-invention must be avoided.

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

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

The description explicitly tells when to use this tool vs. alternatives: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also provides a clear tradeoff (costs one extra LLM call) and contrasts with the sibling ask_pipeworx, giving the agent precise decision 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?

The description extensively covers behavioral traits beyond annotations: low-confidence resolution short-circuit with status, closed/dead market handling, illiquid wide spread note, resolution-rule risk explanation, and safety warnings. Annotations already indicate read-only, open-world, idempotent, non-destructive, and the description adds rich context 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 long but well-structured with section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with core purpose. It could be more concise, but the organization aids readability.

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

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

Given the tool's complexity (multiple classifiers, fan-out examples, response shapes, safety conditions), the description is thorough and covers edge cases. With no output schema, it explains return values adequately.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds substantial meaning: explains depth enum values, include_raw use cases, and market parameter formats. This goes well beyond schema documentation.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from sibling tools like ask_pipeworx and polymarket_arbitrage.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly state when not to use it or compare to alternatives, but the purpose 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is moderately long but front-loaded with trigger phrases and usage instruction. Every section adds value: trigger examples, preference guidance, type-specific details, sorting, and result format. Could be slightly more concise but is well-organized and earns its length.

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

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

Given the complexity of supporting two entity types with distinct data sources, sorting, and citation URIs, and no output schema, the description is comprehensive. It explains behavior for both types, handling of off-calendar fiscal years, and result ordering. Minor omission: no error handling or rate limits, but these are system-level concerns.

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. The description adds meaning beyond the schema by explaining what each type enum value does ('company' pulls latest 10-K data, 'drug' pulls FAERS counts) and the array values (tickers/CIKs for companies, names for drugs). Also clarifies sorting and result structure.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single call, with specific verb 'compare' and resources 'companies' or 'drugs'. It distinguishes from siblings like entity_profile by emphasizing parallel vs sequential lookups and explicitly replacing 8-15 sequential calls.

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 trigger phrases ('compare X and Y', 'X vs Y', 'rank these', 'head to head') and instructs to ALWAYS PREFER over sequential single-pack lookups. It does not explicitly list when not to use, but the context makes it clear this tool is for multi-entity comparisons, distinguishing it from single-entity 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 mark readOnlyHint and openWorldHint, but the description adds rich behavioral details: returns verbatim evidence with confidence, source, fetched_at, and citation_uri; includes gaps[] and contradictions[] for certain depths; performs parallel decomposition across thousands of tools; uses semantic excerpting; and specifies time expectations. No contradictions with annotations.

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

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

The description is relatively long (~300 words) but well-structured: account requirement first, then core behavior, then usage guidance, then detailed behavioral features. Every sentence adds value, though some specifics (exact counts of sources/tools) could be omitted for brevity without losing clarity. Still, it remains front-loaded and scannable.

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

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

With no output schema, the description fully covers return values: findings packet with evidence, confidence, source, citation_uri, gaps, contradictions, hop field. It also explains time expectations, semantic excerpting, and iteration behavior. For a complex research tool, this provides complete context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: explains that question is natural language and welcomes complexity, clarifies the depth enum fully (quick/standard/thorough with hop counts and feature differences), and states that standard is the default. This saves the agent from guessing parameter semantics.

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

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

The description clearly states the verb 'research' and the resource 'Pipeworx's 1462 structured data sources', explicitly distinguishing it from open-web search. It differentiates from siblings like ask_pipeworx by emphasizing multi-source parallel decomposition vs. single-lookup. The purpose is specific and unambiguous.

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

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

The description provides explicit guidance: requires a free account (paid for 'thorough'), recommends ask_pipeworx if not signed in, singles out its best use (broad/multi-part structured data questions) and when to use alternatives (single lookups, breaking news). It also notes that 'thorough' requires a paid plan, 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 and idempotentHint. Description adds valuable behavioral context: returns top-N tools with schemas and curated examples, no second lookup needed. 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 concise, front-loaded with purpose, includes examples and return value details. Every sentence adds value, though slightly longer than minimal.

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?

Although no output schema, the description adequately explains return format (names, descriptions, schemas with examples) and that results are callable directly. All parameters are covered by schema. Complete for a discovery 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 detailed parameter descriptions including aliases. The description does not add significant parameter-specific info beyond what schema provides; 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' and lists many example use cases (SEC filings, financials, drugs, etc.). It distinguishes from sibling tools by positioning itself as the first call to discover the option set.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral context: parallel fan-out across multiple sources, specific fields returned, soft-fail for patents, fallback logic for news, and sorting of fundamentals. 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 well-structured with examples first, then purpose, preference, and details. It's somewhat long but every sentence adds value; only minor redundancy with schema descriptions could be trimmed.

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

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

Despite having no output schema, the description comprehensively covers all return components (cik, filings, fundamentals, patents, news, LEI), limitations (patent sunset, name unsupported), and internal fallback/ordering behavior. This fully equips the agent to understand what the tool provides.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description repeats the same constraints (ticker/CIK, no names) and adds 'zero-padded CIK' example, but adds minimal new meaning beyond what the schema already 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 clearly states the tool provides a 'full cross-source profile of a US public company' and lists concrete example queries. It explicitly distinguishes from chaining individual lookups and references sibling tools like resolve_entity for name resolution.

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

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

The description explicitly states when to prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'), when not to use it ('names not supported'), and provides an alternative ('use resolve_entity first').

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 and pairing, but doesn't introduce new behavioral traits beyond confirming deletion.

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 unnecessary words. The description is front-loaded with the core action and efficiently includes usage guidance.

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

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

For a simple tool with one parameter, no output schema, and informative annotations, the description covers the operation, use cases, and relationship to sibling tools. Nothing essential is missing.

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

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

The input schema already describes the 'key' parameter as 'Memory key to delete' (100% coverage). The description adds no additional semantic details beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the action (delete) and resource (memory by key). It distinguishes from siblings 'remember' and 'recall' by implying storage and retrieval operations.

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

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

Provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember' and 'recall', but does not explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown, providing full 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 the key action and follows with details and use cases. It is concise but includes necessary elaboration, making it slightly longer than minimal.

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

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

For a simple tool with 2 parameters, no output schema, and comprehensive annotations, the description covers purpose, inputs, output format, and use cases. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema descriptions for url and max_links, but it reinforces their roles.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the output format and its use for AI crawlers. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on generation rather than analysis.

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

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

The description lists specific use cases (getting a client's site indexed, drafting for own project, auditing a competitor) but does not explicitly mention when to avoid using this tool or suggest alternative tools like scan_competitor_ai_presence for auditing.

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 false, covering safety and idempotency. The description adds that it returns a tree and tags, but does not elaborate on response structure or limits. Given annotations, the description adds marginal value.

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

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

Two sentences, no filler. The first sentence defines the tool precisely, the second gives a use case. Ideal length for quick comprehension.

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

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

Given the simple input, strong annotations, and existence of an output schema, the description is sufficiently complete for an agent to understand purpose and safe usage. It could hint at the hierarchical nature, but not necessary.

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

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

Schema coverage is 100% with a single parameter 'cid' described as 'PubChem Compound ID'. The description reinforces that the input is a CID but adds no additional meaning beyond the schema. Baseline score applies.

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

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

The description clearly states it returns a pharmacological classification tree including drug class, mechanism of action, and biological role tags for a PubChem Compound ID (CID). It is explicitly distinguished from sibling tools like get_compound or search_by_name by focusing on 'what kind of drug' questions.

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 directly says 'Useful for...' which implies the appropriate context for use. It does not explicitly list when not to use or alternatives, but the specialization is clear enough given the sibling tool names. A minor gap remains.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety info. The description adds value by listing the specific properties returned (molecular formula, weight, etc.), which helps the agent understand what to expect 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 a single, well-structured sentence that efficiently enumerates the provided properties without any fluff. Every word contributes to understanding the tool's output.

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

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

For a simple retrieval tool with one parameter and an output schema, the description is complete. The annotations cover safety and semantics, and the description lists all returned fields. There is no missing information that would impede correct usage.

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

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

Schema coverage is 100% for the single parameter 'cid', with clear description 'PubChem Compound ID'. The tool description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves standard properties for a PubChem CID, listing many specific properties. The verb 'get' and resource 'compound' are precise. Among sibling tools, none directly overlap, making it uniquely identifiable.

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 implicitly indicates when to use: when you need standard properties of a compound given a CID. However, it does not explicitly state when not to use or provide alternatives. The context is clear enough, but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the types of names returned, which is useful. However, it says 'List all names' while the schema includes a max_results parameter with a default cap, which is misleading and not clarified in the description. This creates a minor transparency gap.

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 clear sentence that front-loads the core action and resource. It is efficient, though it omits mention of the max_results cap, which would have improved completeness without adding much length.

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 an output schema exists, the description does not need to detail return values. However, it fails to explain the max_results cap and its impact on the 'list all' claim. For a simple tool, the description is nearly complete but has a notable omission.

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 adds no additional information about the parameters, so it does not add value beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'names (synonyms) for a CID', and provides specific examples like common names, IUPAC, trade names, CAS numbers. This clearly distinguishes it from sibling tools such as search_by_name or resolve_entity.

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

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

The description implies usage when needing synonyms for a given CID, but it does not explicitly mention when not to use it or suggest alternative tools. Sibling tools like search_by_name exist, but no guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds context by specifying the return fields and that it lists active subscriptions by default, which aligns with and enriches the annotations.

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

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

The description is two sentences, front-loaded with the main action, then return fields, then usage. Every sentence adds value with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers what the tool does, what it returns, and when to use it. No gaps are evident.

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 provides a complete description for 'include_inactive'. The tool description does not add further meaning to this parameter, so it meets the baseline for 100% schema coverage.

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

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

The description clearly states 'List the caller's active subscriptions' and lists the return fields. This specific verb+resource differentiates it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly advises when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear, actionable 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?

The description richly discloses behaviors beyond the annotations: 'Rate-limited to 5 per identifier per day', 'Free; doesn't count against your tool-call quota', 'Filing without an account returns a claim_token', and the daily digesting of feedback. This fully informs the agent about side effects, limits, and follow-up semantics.

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 the two-sentence ideal, but every clause carries necessary context: scope, exclusions, token workflow, rate limit, and quota. It is front-loaded with purpose and organized logically from 'what' to 'when' to 'how' to 'limits'.

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 covers all critical aspects: what it does, when to use versus alternatives, the token-based follow-up mechanism, rate limiting, and quota effect. An agent selecting this tool would know exactly what to expect and how 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 description coverage is 100%, so the structured fields already explain type, context, message, and claim_token. The description repeats the claim_token usage with an example but does not add meaning beyond what the schema provides. For a tool with complete schema coverage, a 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 opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly defines the tool as a feedback channel and distinguishes it from sibling research tools by scoping it to Pipeworx tools only.

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

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

The description provides explicit when-to-use scenarios: 'bug', 'feature/data_gap', and 'praise'. It also gives a clear exclusion rule: 'if the tool came from a different MCP server... file it with that server instead,' plus guidance to describe issues in terms of Pipeworx tools rather than pasting user prompts.

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 valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h depending on window), and self-aggregating nature. This goes well beyond the annotations.

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

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

The description is approximately 100 words, front-loaded with the main output, followed by use cases, then technical details. Every sentence adds value, and there is no redundancy or filler.

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

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

For a tool with a single optional parameter, no output schema, and complete annotation coverage, the description fully explains the return values (top tools, top packs, call volume), caching, and data sources. It is complete enough for an agent to use correctly.

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

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

The only parameter (window) has 100% schema coverage with clear enum. The description explains the semantic difference: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds significant 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 it 'returns the top tools, top packs, and total call volume' with specific verbs and resources. It distinguishes itself from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on aggregate trending data.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, seeing alignment). While it does not list when not to use it, the use cases are concrete and helpful. No direct alternative tool is mentioned, but the purpose is unique 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 indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral context: monotonicity checks, partition checks, semantic anchor, partition filter, fill check behavior, and response structure. No contradictions.

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

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

Description is long but well-structured with clear sections for each mode and additional checks. Every sentence adds value, though some details (e.g., fill check explanation) could be slightly more concise without losing clarity.

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

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

Despite no output schema, description fully explains return fields (opportunities[], gap_pp, suggested_trade, reasoning, etc.) and covers all modes and edge cases (low similarity, placeholder filters, fill check). No obvious gaps for a tool of this 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 has 100% coverage with descriptions for both parameters. Description adds significant value: explains event slugs and topic queries with examples, clarifies mode-dependent behavior, and adds context beyond the schema.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It 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 a specific market (recommended), topic for cross-event scanning. Provides examples and notes on when not to trade (fill check). However, does not explicitly contrast with sibling tools or mention when to use alternatives.

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

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

The annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds significant behavioral context: caching (1h at KV level), response structure with diagnostics, tradeable-edge filters, per-leg behavior, and Fed bets exclusion. No contradictions.

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

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

The description is lengthy but well-structured with bullet-like lists and clear sections. It is dense with useful information, but could be more concise without losing key details. Every sentence provides value.

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

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

Given the tool's complexity (9 parameters, 3 model families, detailed output), the description is exceptionally thorough. It explains the response structure (by_segment, diagnostics), caching, tradeable-edge knobs, and even special cases like Fed bets. Without an output schema, this description fully compensates.

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 parameter descriptions. However, the description adds meaning beyond the schema by explaining the overall context, tradeable-edge knobs, and the specific role of min_partition_leg_kelly. It enriches understanding but the schema already does a good job.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and explicitly states it's built for 'what should I bet on today'. It distinguishes itself from siblings like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by focusing on multiple model families and providing a comprehensive edge discovery tool.

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

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

The description provides clear context for usage: agents can discover opportunities without paging hundreds of markets. It explains when to use each segment (model_driven, structural_arbitrage, concentrated_longshot) and the tradeable-edge knobs. However, it does not explicitly exclude sibling tools or state when not to use this tool instead of 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?

The description adds significant behavioral context beyond annotations: it details the response structure (tracked, expired, snapshot_dates), explains how decay is computed (from daily closes, not intraday), and notes limitations (snapshot TTL, enabled date). Annotations already indicate read-only and idempotent, and the description aligns with these.

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

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

The description is lengthy and dense, but all sentences add value. It front-loads the core purpose, then details response fields, and ends with limitations. However, the structure could be better organized; the response field listing with semicolons is somewhat dense.

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

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

With no output schema, the description thoroughly covers the return value structure (tracked, expired, snapshot_dates) and explains each field. It also addresses limitations. This provides full context for the 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?

Though schema coverage is 100%, the description adds meaning by specifying defaults (days=14, window='1wk'), clamping range (days: 2-30), and providing context for the window parameter. This goes beyond the schema's basic 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like polymarket_edges which likely provides raw edge data.

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

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

The description gives useful context on when to use this tool (e.g., comparing fresh vs. old wide edges) but does not explicitly state when not to use it or mention alternatives among sibling tools. The context is clear but lacks 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description confirms read-only behavior, detailing what it returns (top_of_book, vwap_fill_price, slippage, etc.) and warns about forced_directional_risk. No contradiction, and adds substantial 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?

Description is well-structured with clear sections (SINGLE-MARKET, BASKET) and front-loaded purpose. However, it is somewhat verbose; could be slightly more concise while retaining all critical info. Still every sentence earns its place.

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

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

Given no output schema, description thoroughly lists all return fields (top_of_book, vwap_fill_price, shares_filled, etc.) and covers edge cases (thin_legs, forced_directional_risk). For a complex tool, it provides complete contextual information for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, but description adds meaning: explains default side in basket mode (auto from partition sum), interprets size_usd differently for buys vs sells, and clarifies parameters in context. Provides value beyond schema alone.

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

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

Description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket/partition modes and specifies usage before execute arb signals or edges trades above $500, differentiating it from sibling tools like polymarket_arbitrage and polymarket_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?

Provides explicit usage context: '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 create directional risk), effectively guiding when to use and when not.

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

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

Annotations only indicate readOnly, openWorld, and idempotent; the description provides rich behavioral details: compatibility_warning triggers for mismatched bet shapes or unrelated events, temporal_alignment indicates whether spreads are meaningful, and skipped counters explain dropped comparisons. 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 detailed and structured into sections (overview, modes, response, safety fields). It is front-loaded with the main purpose. While it is longer than average, every sentence adds necessary information for correct use. Could be slightly more concise but still effective.

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

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

Without an output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and skipped counters. It covers all critical aspects for agent decision-making. Minor omission: does not explicitly state the output format (JSON), but the detail is 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% so parameters are already documented. The description adds value by listing the 10 topic shortcuts, explaining that explicit parameters override topic-mapped ones, and providing examples. This goes beyond the schema alone.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes and distinguishes itself from sibling tools like polymarket_arbitrage which operate within a single venue.

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

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

Explicitly describes when to use each mode (topic shortcuts vs explicit tickers), warns that most pre-mapped topics currently return compatibility warnings, and explains the conditions under which spreads are valid. This helps an agent decide when this tool is appropriate and what to expect.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe and idempotent. The description adds the important behavioral detail that data is scoped to the user's identifier (IP, key hash, or account ID), which is 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 only four sentences, each serving a distinct purpose: function, use case, scoping, and pairing. It is front-loaded with the core functionality and wastes no words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers retrieval, listing keys, use case, scoping, and sibling relationships. It does not explicitly describe the return format, but this is inferable from the function. Overall, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter. The description adds examples of what keys might be (ticker, address, notes), which provides additional context beyond the schema's definition, but the schema alone is sufficient for parameter understanding.

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

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

The description clearly states the tool retrieves a saved value or lists all keys. It distinguishes itself from siblings 'remember' and 'forget' by explicitly naming them as pairs. The examples of stored data (ticker, address, notes) add specificity.

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 this tool to look up stored context, avoiding re-derivation. It mentions alternatives 'remember' and 'forget' for save and delete operations, giving clear guidance on when to use this tool vs its direct counterparts.

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, and non-destructive. The description adds behavioral details: returned fields, mark_read effect on next call, and polling suitability. This adds value beyond annotations but could mention pagination or rate limits.

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

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

The description is concise with multiple sentences, each adding necessary information. No redundant or vague text; front-loaded with the core 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?

Given no output schema, the description explains return fields and behavior for all parameters. It also mentions polling and an alternative API endpoint. This suffices for a read-only tool with strong annotations.

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, but the description enriches semantics by explaining mark_read's effect ('flag returned events read so the next call only shows newer ones') and providing an example filter type ('sec_8k'). This adds 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 begins with a clear action verb and resource: 'Pull fired events from your subscription feed.' It specifies the return content and filters, distinguishing it from siblings like list_subscriptions.

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

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

The description provides context on when to poll and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly state when not to use this tool versus other related tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO (with PatentsView sunset note). This goes beyond annotations to explain how the tool operates.

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

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

The description is concise and front-loaded with example queries, making the purpose immediately clear. Every sentence contributes valuable information. It is not overly verbose, though it could be slightly more structured with bullet points or explicit sections.

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

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

Given the tool's moderate complexity (multiple sources, fallback, no output schema), the description covers input format, source behavior, and return structure (changes array with URIs). It also references the alternative tool 'entity_profile'. However, it lacks details on error handling or rate limits.

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

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

All three parameters are fully described in the schema (100% coverage). The description enhances this by providing format examples for 'since' (ISO dates and relative shorthand), explaining that 'value' accepts ticker or CIK, and noting that 'type' is limited to 'company'.

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

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

The description clearly defines the tool as a change feed for a company over a time window, using concrete example queries like 'What's new with X' and 'latest on Y'. It distinguishes itself from the sibling tool 'entity_profile' by explicitly stating when to use the alternative for static profiles.

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

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

The description provides explicit guidance: use for recent changes within a window, and use 'entity_profile' for static profiles. It details fallback logic across multiple sources and gives typical usage for the 'since' parameter (e.g., '30d' or '1m'), making it easy for the agent to decide when and how to invoke.

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 idempotentHint=true, destructiveHint=false. Description adds that it stores key-value pairs scoped by identifier and memory duration (24hr for anonymous). No contradictions.

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

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

Description is front-loaded with purpose, then usage guidelines, then technical details. Each sentence is necessary and well-organized, 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?

Tool is simple key-value store; description covers persistence, scope, and pairing with siblings. No output schema needed; return value implied by recall. Complete for intended use.

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

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

Schema has 100% coverage with descriptions. The description adds naming conventions (e.g., 'subject_property') and value content (findings, addresses), providing 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 saves data for reuse across conversations, with specific examples (ticker, address, preference). It distinguishes from siblings by mentioning pairings with recall and forget.

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

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

The description explicitly advises when to use (discover something worth carrying forward) and mentions alternatives (recall to retrieve, forget to delete). It also clarifies persistence based on authentication.

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 (readOnlyHint, idempotentHint) already signal safety and idempotency. The description goes far beyond by disclosing graceful degradation ('LEI/FIGI enrichment degrades gracefully'), cascading internal lookups ('each call cascades through several lookup endpoints'), and the handling of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'). No contradictions.

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

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

The description is verbose (~150 words) but well-structured: it opens with example queries, then cascades into supported types and behavioral notes. Every sentence adds value, covering purpose, guidelines, and edge cases. While not maximally concise, it earns its length with substance and front-loading.

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 absence of an output schema, the description compensates by detailing what identifiers are returned (CIK, ticker, LEI, FIGI for company; RxCUI for drug) and how errors are handled (graceful degradation, unresolved list). It covers parameter semantics, use cases, and internal complexity—leaving little ambiguity for an AI agent to misinterpret.

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 substantial meaning beyond the schema: for 'type' it explains what each enum value entails (e.g., company returns 'cross-source identity spine' with CIK, LEI, FIGI); for 'value' it provides concrete examples (ticker, CIK, name; brand/generic name). This enrichment lifts the score to 4.

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

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

The description starts with vivid example queries then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly lists supported types ('company', 'drug') and details what identifiers are retrieved for each, making the tool's function unmistakable and well-differentiated from siblings.

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

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

The description provides an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This gives clear usage context. It does not explicitly contrast with siblings like 'search_by_name', but the 'Use FIRST' phrasing strongly indicates priority, earning a 4.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and surfaces the most/least recognized. It also mentions returning ranked lists with score, confidence, and signal density. There is 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 long with a parenthetical example. It is front-loaded with the core purpose, and every sentence provides unique value. 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?

Given no output schema, the description adequately covers the return format (ranked list with score, confidence, signal density). It explains the workflow (probes with ai_visibility_check). However, it does not mention potential errors, rate limits, or the need for an API key when using the 'anthropic' model, though that is in the parameter schema. Overall sufficient for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds meaning beyond the schema: it notes that the first entity in 'entities' is treated as the 'subject' for narrative, and that 'context' is shared across probes to disambiguate common names. This helps the agent understand parameter relationships.

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 identifies most/least recognized. This distinguishes it from sibling ai_visibility_check (single entity) and compare_entities (general comparison). The verb 'compare' and resource 'AI presence' are specific.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' with an example question. It implies the tool is for multi-entity comparison, differentiating from the single-entity sibling. However, it does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single probes.

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 true. The description adds valuable behavioral details: it fans out to multiple external services, returns a structured summary block with specific fields, lists per-advisory detail, links, and alternative versions. It transparently warns about bundlephobia's first measurement taking 5-30s and that sources_failed will list timeouts. No contradictions with annotations.

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

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

The description is relatively long but well-structured: a clear purpose statement upfront, followed by usage context, return detail, ecosystem scope, and edge-case behavior. Every sentence adds value, though a minor trim could tighten it slightly 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?

With no output schema, the description bears full responsibility for explaining returns. It does so thoroughly: a summary block with specific fields (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers partial failures and timing. For a tool of moderate complexity (composite call, multiple sources), this is complete and sufficient.

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

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

Schema description coverage is 100% with both package and version documented. The description does not add new parameter-level information beyond what the schema provides (e.g., 'Scoped packages accepted', 'defaults to latest'). Since the schema already covers parameter meanings, the description adds no incremental semantic value for parameters, resulting in a baseline score of 3.

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

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

The description opens with a clear and specific verb-resource: 'Composite should I add this npm package to my project check in ONE call'. It explicitly states the tool fans out across deps.dev and bundlephobia for npm packages, distinguishing it from sibling tools that are either for other ecosystems or different queries.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also notes limitations—'NPM ecosystem only in v1'—and mentions fallback via deps.dev directly for other ecosystems, plus handling of partial failures.

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 minimal behavioral context beyond the annotations. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description only reiterates that it returns CIDs, which is obvious. No additional traits like authentication or rate limits are mentioned.

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

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

The description is concise and well-structured: three sentences covering purpose, usage example, and next step. No unnecessary words 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?

For a simple lookup tool with annotations and an output schema, the description is complete. It explains the core function and how to use the result. However, it could briefly mention that results are case-insensitive or that max_results applies, but the schema covers these.

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 provides example values ('ibuprofen', 'caffeine') but does not add significant semantic detail beyond what the schema already provides for name and max_results.

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: 'Resolve a common chemical or drug name to PubChem CIDs.' This is a specific verb-resource pairing and distinguishes it from siblings like get_compound, which retrieves properties from a CID. The description also provides concrete examples like 'what's the CID of ibuprofen?'.

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 guides when to use the tool: 'Use for...to disambiguate.' It also suggests the next step: 'Then use get_compound with the CID for properties.' While it does not list when not to use, the context is clear and sufficient for decision-making.

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 safety/idempotent hints. Description adds technical details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation+flagging, and offset for verification. 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?

Description is concise (4 sentences) with front-loaded key purpose. Each sentence adds meaningful value: use case, behavior, technical details, and example.

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 aspects: purpose, usage, technical details, output format (passages with offsets and scores), constraints, and pairing with other tools. No gaps given no output schema.

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. Description adds context: examples for query, notes on truncation for text, and default for limit. Provides extra clarity 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?

Title and description clearly state semantic search inside a fetched record. Explicitly distinguishes from siblings by specifying when to use (too big for prompt) and pairing with ask_pipeworx_grounded.

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

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

Explicitly states use case: when record is too large for prompt. Gives alternative: 'Pairs with ask_pipeworx_grounded'. Clear when-to-use and when-not.

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 states 'Create' and 'Returns the new subscription id', implying non-idempotent behavior, contradicting 'idempotentHint': true annotation. This is a clear contradiction, warranting a score of 1.

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 dense but well-structured: purpose, requirements, supported types with examples, then delivery channels. Each sentence adds value. Slightly lengthy but efficient given 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?

Covers prerequisites, type enumeration, delivery details, rate limits, and return value (subscription id). No output schema, but return description is sufficient. Could mention error cases but not necessary.

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 description adds significant value by detailing type-specific params, delivery options with examples and constraints (e.g., phone verification, 10/day cap). This goes beyond the schema description.

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

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

Description starts with 'Create a proactive monitoring subscription', which clearly states the action and resource. It distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Description provides context on prerequisites (OAuth account) and supported types with examples. It implicitly guides when to use, but lacks explicit when-not-to-use mentions or direct references to alternative 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 indicate read-only, open-world, idempotent, non-destructive. The description adds that results are drawn from a live catalog, explains what the output contains (example questions with tool+argument shapes), and clarifies argument behavior. No contradictions.

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

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

The description is well-structured with alternative phrasings, core purpose, output details, and usage notes. It is slightly verbose but every sentence adds value; no significant waste.

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

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

Despite no output schema, the description fully explains the output format (category-bucketed example questions with tool+argument shapes) and covers the single parameter. Usage guidance is complete for the tool's purpose.

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

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

Schema coverage is 100% for the single parameter 'topic'. The description adds value by listing specific example values (finance, pharma, etc.) and stating that omitting the parameter gives a cross-category spread, which goes beyond the schema's brief description.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, and explicitly positions it as the onboarding entry point. It distinguishes itself from siblings like ask_pipeworx by focusing on suggestions for what to ask.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to focus with a topic. It implies when to use but doesn't explicitly mention when not to use or compare to all siblings, though it references learning how to call meta-tools.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts,' which discloses the non-destructive behavior and links to a sibling tool, providing valuable context beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose and ownership constraint, then immediately addressing behavioral side effects. Every sentence adds value with no redundancy.

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

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

Given the tool's low complexity (one required parameter, no output schema), the description covers purpose, ownership enforcement, and the deactivation effect completely. No gaps are present for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, with the 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description adds 'by id' but does not significantly enhance understanding beyond the schema. Per guidelines, 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 starts with 'Cancel a subscription by id,' which is a specific verb+resource combination. It clearly distinguishes from sibling tools like 'subscribe', 'list_subscriptions', and 'recent_alerts' by describing the cancel action and unique ownership enforcement.

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

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

The description states 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context on when to use this tool (for your own subscriptions) and an implicit exclusion (cannot cancel others'). However, it does not explicitly mention alternatives or when not to use, but the guidance is sufficient.

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

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

The description adds significant behavioral context beyond the annotations: it warns that 'could_not_verify' means the check did not happen and must not be treated as evidence, distinguishes it from 'unsupported', and discloses the two routing paths (SEC EDGAR/XBRL vs. grounded pipeline). It also mentions the return object (verdict, value, citation, reasoning) and error details.

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 dense with unique, necessary information. It is front-loaded with the purpose and example queries, and every sentence adds value—especially the 'IMPORTANT for callers' caveat and the note about replacing sequential calls. There is no redundancy or filler.

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

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

For a tool with no output schema, the description fully covers return values (verdict types, actual value, citation, reasoning), error semantics (could_not_verify vs. unsupported), routing behavior, and usage context. It leaves no ambiguity about what the agent will receive or how to interpret edge cases.

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

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

Schema coverage is 100%, and the schema already thoroughly describes both parameters, including tolerance_pct's range, default, and intent. The description adds little beyond what the schema provides, except contextualizing the 'exact percent-delta math' for financial claims. Therefore, a baseline of 3 is appropriate.

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

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

The description clearly states this tool performs natural-language claim verification, with explicit verbs like 'verify', 'fact check', and 'confirm or refute'. It distinguishes itself by focusing on true/false claims and even differentiates between company-financial claims (SEC EDGAR fast path) and all other factual claims (grounded pipeline), making its purpose unmistakable.

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

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

It provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains that it replaces 4–6 sequential calls, implying efficiency. However, it does not explicitly contrast with sibling tools like ask_pipeworx_grounded or deep_research, so the exclusion of alternatives is implicit rather than explicit.

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