Mesh

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

Beyond the annotations (readOnly, idempotent, not destructive), the description adds that it returns per-model results (score, confidence, signals, raw_response) and a combined view, and notes that Workers AI is free while Anthropic requires a BYO key. 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 extremely concise: two sentences covering functionality and conditions, plus a single sentence on use cases. No fluff, and the key purpose is front-loaded.

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

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

Despite lacking an output schema, the description explains the return structure (per-model fields + combined view). It covers common use cases and model selection. Minor omissions like error handling or rate limits do not detract significantly given the annotations and simplicity.

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

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

With 100% schema description coverage, the description adds value by providing concrete examples for 'entity' (e.g., 'Pipeworx') and explaining the default behavior for 'model' and the role of '_apiKey'. This goes beyond the schema's 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 action (probe LLMs) and the resource (knowledge about a business/product/topic), with a specific metric (visibility score 0-100). It distinguishes this from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing on AI visibility assessment.

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 for when to use the tool (AI-marketing audits, pre-launch checks, competitive monitoring) and explains the default model vs. the need for an API key. However, it does not explicitly state when not to use it or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by disclosing routing across 3,725 tools and returning structured answers with citation URIs, giving richer behavioral context.

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

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

Front-loaded with key instruction 'PREFER OVER WEB SEARCH', uses bold for emphasis. Single well-organized paragraph with examples. Every sentence adds value.

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

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

No output schema, but description explains the tool returns 'structured answer with stable pipeworx:// citation URIs', sufficient for an agent. Covers domain, mechanism, and examples, making it complete for a query tool.

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

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

Schema descriptions already cover the single parameter question and its aliases. Description repeats the alias information and mentions 'fills arguments' but adds no new semantic detail 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 answers factual questions from authoritative sources, with verb 'ask' and resource 'Pipeworx'. It distinguishes from web search but does not explicitly differentiate from siblings like 'ask_pipeworx_grounded' or 'deep_research', so slightly below 5.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and lists a comprehensive set of query types (e.g., 'what is', 'look up', 'current') with concrete examples. Provides clear when-to-use guidance.

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

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

Adds substantial behavioral context beyond annotations: describes the routing process, extraction method using only tool results, return format with refusal reasons, and mentions extra cost. 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 somewhat lengthy but every sentence adds value. It front-loads the key differentiator and contains no filler. Could be slightly more concise.

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

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

Given no output schema, the description fully covers the return format, refusal reasons, use cases, and cost trade-off. Completeness is high for a tool with 6 parameters and complex behavior.

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

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

Schema description coverage is 100% with all 6 parameters described, so the description adds no new parameter information beyond accepting natural language. 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 identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads,' specifies the verb 'ask' and resource 'Pipeworx,' and distinguishes it from the sibling 'ask_pipeworx' by emphasizing grounded answers and refusal behavior.

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 to 'use whenever an answer will be quoted, cited, or acted on' and to 'prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to-use guidance with alternatives.

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

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

The description provides extensive behavioral details beyond annotations: fan-out logic, classifiers, response shapes, resolver contract, parent event extraction, safety mechanisms (low-confidence resolution, closed markets, wide spreads), resolution-rule risk, and fallback fields. Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which are consistent.

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: purpose first, then classifiers, fan-out examples, response shapes, resolver contract, etc. Every sentence adds necessary detail given the tool complexity. Could be slightly shorter, but the structure is logical and 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 complexity (multiple classifiers, fan-out, safety checks) and lack of output schema, the description covers all crucial aspects: market analysis, evidence sources, resolver confidence, parent events, news fallbacks, and security considerations. It leaves no obvious gaps for agent 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% with all three parameters described. The description adds meaning: explains 'market' input types, 'depth' vs 'thorough', and 'include_raw' impact (summary vs full payload). This enhances understanding 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 identifies the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb 'Research', the resource 'Polymarket bet', and the action of pulling data. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on specific analyses.

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 also explains input types (slug, URL, question text) and the depth parameter. However, it lacks explicit when-not-to-use guidance or direct comparison to siblings, which is partially covered by context.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context: it pulls from SEC EDGAR/XBRL for companies with specific financial metrics, handles off-calendar fiscal years, and for drugs pulls FAERS data. It also notes sorted results and citation URIs, providing comprehensive transparency 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 relatively lengthy but each sentence adds important information, including examples, data sources, and behavioral details. It is well-structured, starting with example queries, then instructions, then entity-specific details. Could be slightly more concise, but 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 complexity (comparison across two entity types with different data sources), the description covers all essential aspects: data sources, fiscal year handling, sorting, output format (paired data + citation URIs), and the efficiency gain over sequential lookups. No output schema is provided, but the description adequately describes return expectations.

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

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

Schema coverage is 100%, so the schema already documents parameters. However, the description adds meaningful enrichment: for 'type', it explains what data each enum value retrieves; for 'values', it clarifies the format (tickers/CIKs vs drug names) and constraints (2-5 items). This adds value beyond the schema descriptions, justifying a score above the baseline 3.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, using specific user query examples. It distinguishes between 'company' and 'drug' entity types and explains the data sources for each, making the purpose very specific and differentiating it from sibling tools like 'entity_profile' which likely handles single entities.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a strong when-to-use directive. However, it does not explicitly state when to avoid this tool (e.g., for a single entity) or name specific alternative tools, though the context implies these from the sibling list.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. Description adds crucial details: 'never invented', returns verbatim evidence with 'gaps[]' for unknowns, and cites sources. Complements annotations without contradiction.

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

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

Description is packed with information and front-loaded with core functionality. However, it is slightly lengthy; could be trimmed without losing essence. 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 complexity (multi-source, parallel, structured output) and absence of output schema, the description covers purpose, process, output format (findings packet with evidence, citations), prerequisites, and behavioral guarantees. Fully 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%, but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and clarifies that question can be broad/multi-part, which is not obvious from 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 states a specific verb and resource: 'Grounded multi-source research in ONE call' with details on decomposition and parallel execution. It distinguishes from sibling tools like ask_pipeworx by noting the multi-facet approach.

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 when-to-use: 'Use for broad or multi-part questions' and when-not-to-use: 'use ask_pipeworx for single lookups'. Also provides prerequisite: 'Requires a Pipeworx account' and depth restrictions.

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

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

Annotations already declare readOnly and idempotent. Description adds value by explaining output format (top-N tools with schemas, no second lookup) without contradicting annotations.

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

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

Description is front-loaded with purpose and provides comprehensive information, though slightly verbose. 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?

No output schema, but description compensates by detailing return payload (names, descriptions, schemas, examples) and that results are call-ready.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific details beyond what 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?

Description clearly states the tool finds tools by describing data/task, lists specific domains, and differentiates from siblings by positioning it as a first-step discovery tool.

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

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

Explicitly states when to use (browse/search/discover) and gives direct guidance to call it first when many tools are available.

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 details: fans out across multiple sources, returns specific fields, and soft-fails for patents. 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?

Dense and informative, front-loaded with examples and preference statement. Slightly verbose but every sentence adds value. Could be slightly more concise but excellent overall.

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

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

No output schema, but description lists all return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (only companies, USPTO sunset). Complete for a holistic profile 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%, but description adds meaning: explains 'type' only supports 'company', and 'value' must be ticker or CIK, not names. Also describes return fields, adding value beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with examples like 'tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings by stating to prefer over chaining individual lookups.

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

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

Explicitly says to use 'when the user asks for a holistic view' and advises to 'use resolve_entity first if you only have a name'. Lists input requirements (ticker or zero-padded CIK) and notes the USPTO sunset.

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 readOnlyHint=false, confirming deletion. The description adds context about clearing sensitive data but does not elaborate on side effects or authorization needs. No contradiction with annotations (idempotentHint is consistent with a delete operation that may target a non-existent key).

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, each carrying essential information: purpose, usage guidelines, and pairing with siblings. It is front-loaded with the action and resource, with no unnecessary words.

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

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

For a simple tool with one required parameter and comprehensive annotations (destructive/idempotent flags), the description covers what the tool does, when to use it, and how it relates to other tools. No output schema is needed.

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

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

The input schema covers 100% of parameters with a description for 'key'. The description does not add any new meaning beyond the schema's 'Memory key to delete', so baseline score of 3 applies.

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

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

The description states 'Delete a previously stored memory by key', which is a specific verb ('Delete') and resource ('memory by key'). It clearly distinguishes this tool from siblings like 'remember' and 'recall'.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall' for a workflow. However, it does not explicitly state when not to use the tool.

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

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

Consistent with annotations (read-only, idempotent, non-destructive) and adds context about fetching and extracting. No contradictions; the description aligns perfectly with the safe, read-only nature.

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

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

Concise, front-loaded with purpose, and each sentence adds value. No wasted words, structured clearly with bullet-like use cases.

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 effectively explains the output format. Annotations cover safety. All necessary context for an agent to use the tool correctly is present.

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?

Both parameters are described in schema (100% coverage). The description adds default and max for max_links, enhancing understanding. Fine, though slightly more detail on output trimming could be included.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific actions (fetch, extract, emit) and output format. It distinguishes from siblings by focusing on creating the standard file for AI indexation.

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

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

Describes use cases (client site indexing, own project drafting, competitor auditing) but does not explicitly state when not to use or mention alternatives, though sibling list provides implicit differentiation.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by detailing the exact fields returned (labels, qualifiers, see-also headings) and stating 'Keyless', which implies no auth needed. No contradictions with annotations.

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

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

The description is a single, informative sentence that front-loads the purpose and enumerates returned fields. It is concise but could be slightly restructured for readability; currently very 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?

Given one parameter with full schema coverage, sufficient annotations, and no output schema, the description adequately explains what the tool returns. Missing typical edge cases (e.g., invalid ID), but overall complete for its simplicity.

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

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

Schema coverage is 100%, so the schema already describes the parameter. The description adds useful examples (e.g., D003920 for Diabetes Mellitus) and explains the ID format, enhancing 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 explicitly states the tool retrieves full details for a MeSH descriptor by ID, listing specific data returned (preferred label, entry terms, allowable qualifiers, see-also headings). This clearly distinguishes it from sibling tools like search_descriptors which focus on searching.

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 the primary use case (getting details by ID) but lacks guidance on when to use this vs alternatives or what prerequisites exist. The mention of 'Keyless' hints at no authentication, but no explicit when-to-use or when-not-to-use advice is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return fields and 'active' default, but does not introduce new behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with action and resource, no waste. Efficient and to the point.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context completely.

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

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

Only one optional boolean parameter with schema description. Description does not add extra meaning beyond the schema; baseline 3 due to 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?

Description uses specific verb 'List' and resource 'subscriptions', specifies 'caller's active subscriptions', and distinguishes from siblings 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?

Explicitly states use cases: review before adding more subscriptions or find an id to cancel. Provides clear context for when to use this tool.

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

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

Annotations have all false values, so the description carries full burden. It discloses rate limit (5 per identifier per day), free usage, daily team review, and roadmap impact. This is excellent transparency 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 well-structured: purpose first, then usage scenarios, formatting instructions, and finally consumption details. No wasted words, front-loaded with essential information.

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

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

For a simple feedback tool, the description covers purpose, usage scenarios, formatting, rate limits, and team impact. No output schema exists, but the description sufficiently explains what the tool does and its effects.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor extra guidance (max length 2000 chars, typical 1-2 sentences) for 'message' and repeats enum meanings for 'type', but does not significantly deepen understanding beyond the schema.

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

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

The description clearly states the tool sends feedback to the Pipeworx team about bugs, features, data gaps, or praise. The verb 'tell' and resource 'Pipeworx team' are specific, and no sibling tool serves this purpose.

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

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

The description explicitly lists scenarios for use (bug, feature, data_gap, praise) and provides a negative instruction (don't paste end-user prompt). It mentions rate limits and quota. However, it could more explicitly contrast with asking questions via ask_pipeworx.

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 and idempotentHint, but description adds valuable details: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating signal. 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 a single paragraph but well-structured: first sentence states output, then use cases. Information is front-loaded. Could be slightly more concise, but no wasted sentences.

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

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

For a simple read-only tool with strong annotations, the description covers purpose, use cases, behavioral traits, and caching. Even without output schema, the return values (top tools, top packs, total call volume) are clearly described. 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?

Only one parameter 'window' with enum in schema. Description adds context: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.' This clarifies the meaning beyond the enum values.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a recent window. The verb 'calling' and resource 'Pipeworx' are specific. It distinguishes from siblings like ask_pipeworx which is for answering questions, not for trends.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and aligning use case. Also explains when to use shorter vs longer windows. Lacks explicit 'when not to use', but given its read-only aggregated nature, the use cases are 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?

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: monotonicity checks, partition-sum deviations, Jaccard similarity filtering, placeholder filtering, fill check comparing theoretical vs realizable edge. No contradiction with annotations.

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

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

The description is long but well-structured with bold headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the critical requirement. Some redundancy exists (e.g., repeating 'recommended' for event mode twice), but overall organized for complex tool.

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

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

Given no output schema, the description thoroughly covers input, processing, output fields (opportunities array with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, etc.; fill check details). Also explains error/edge cases (null signal, placeholders filtered). Integrates with sibling tool polymarket_fill_risk.

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

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

Schema description coverage is 100%, but description adds significant value with examples, usage scenarios, internal processing details (e.g., slug acceptance, URL handling, seed question examples), and outcome interpretations. Far exceeds minimal schema info.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific guidance, 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?

The description explicitly requires one of event or topic, warns that calling with no args fails, recommends event for specific markets and topic for cross-event scanning, and advises when not to trade based on fill check results.

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

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

The description extensively adds behavioral context beyond annotations: caching behavior (1h at KV level), response structure with diagnostics, model details (e.g., partition_overround with per-sport alpha), and edge calculations. It aligns with annotations (readOnlyHint, idempotentHint) and discloses all relevant behaviors.

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

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

The description is extremely verbose and unstructured, combining purpose, model details, parameter explanations, and diagnostics into a single dense paragraph. While content-rich, it lacks conciseness and scannability; bullet points or sections would improve it.

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, multiple model families, segments, and diagnostics), the description covers all aspects: what the tool does, how results are grouped, what each segment contains, tradeable-edge knobs, and diagnostics for empty segments. Without an output schema, it thoroughly explains the response format.

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

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

Schema coverage is 100%, and the description adds significant value by explaining how each parameter affects the tradeable-edge filters (e.g., min_liquidity, max_spread_pp), the purpose of min_partition_leg_kelly, and the role of category_filter in restricting output segments. This goes well beyond the schema descriptions.

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

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

The description clearly states that the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically designed for 'what should I bet on today' queries. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge scanning across multiple model families and segments.

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 detailed guidance on when to use the tool (discovering opportunities without paging through markets), how to interpret results (segments, diagnostics), and how to adjust parameters (knobs like min_liquidity, max_spread_pp). However, it does not explicitly state when not to use it or compare directly with sibling tools like polymarket_edge_tracker.

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

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

Annotations already declare readOnly, idempotent, openWorld. The description adds detail: it reads from daily snapshots (not live), computes trend/decay, shows expired opportunities, notes snapshot gaps. No contradiction with annotations. Adds value beyond structured fields.

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

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

The description is front-loaded with purpose and key question, followed by detailed response structure and limits. It is long but every sentence adds necessary context. Could be slightly more concise, but overall well-structured and informative.

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

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

Despite lacking an output schema, the description thoroughly explains the return fields (tracked[], expired[], snapshot_dates[]) and their meaning, plus limits (TTL, daily data). This compensates fully for the missing schema. No gaps for a read-only telemetry tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor clarifications: days clamped to 2-30, window corresponds to snapshot family. But these are largely redundant with the schema descriptions, providing little additional value.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' built from daily snapshots, answering a specific question about edge longevity. It distinguishes from siblings like polymarket_edges by focusing on trend analysis over time, not raw snapshot 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 explains when to use this tool: to assess whether an edge is fresh or decaying, with an example contrasting a new wide edge vs. a 3-week-old one. It does not explicitly state when not to use, but the context implies it's complementary to polymarket_edges. Limits (60-day TTL, daily data) provide guidance on scope.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it explains the two modes (single-market vs basket), return fields (e.g., verdict, forced_directional_risk), and risks of unhedged positions. This goes beyond the annotations but could be further enhanced with latency or auth constraints.

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

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

The description is thoroughly detailed yet efficiently structured: it begins with the core purpose, followed by requirements, a breakdown of each mode, and explicit usage guidance. Every sentence serves a purpose 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 (two modes, 4 parameters, no output schema), the description is remarkably complete. It enumerates return fields for both modes, explains risks of partial fills, and provides thresholds. It compensates fully for the lack of an 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%, so the parameter descriptions are already present. The description adds meaning beyond the schema by explaining the auto default for side in basket mode and the interpretation of size_usd differently for single-market vs basket. This provides valuable context not captured in 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', which is a specific verb+resource. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly recommending its use before acting on their signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged positions).

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

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

The description goes beyond annotations by explaining behavioral nuances: compatibility warnings for non-equivalent bet shapes, temporal alignment, and skipped cross-type/subtype counters. It details when spreads are meaningful and when they are not. 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 dense and informative, starting with the core purpose and then systematically explaining modes, output fields, safety fields, and caveats. While thorough, it could be slightly more concise without losing essential details.

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

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

For a complex tool with no output schema, the description comprehensively explains the response structure (spread[], compatibility_warning, temporal_alignment, counters) and edge cases. It covers all necessary context for correct invocation.

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

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

Schema coverage is 100%, so the description adds value by explaining the two modes, providing examples of valid inputs, and describing override behavior. This enriches understanding beyond the schema's minimal 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 identifies the tool's purpose as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison. The two modes and output are explicitly stated.

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

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

The description provides clear context on when to use the tool (for cross-venue spread analysis) and when not to (when compatibility warnings fire). It hints at limitations (most pre-mapped topics return warnings). However, it does not explicitly state alternatives or when to prefer explicit mode over topic mode.

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 (readOnly, idempotent, non-destructive), the description adds scoping by identifier and pairing with remember/forget, providing comprehensive 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?

Three sentences, each adding distinct value: core function, use case/benefit, scoping/pairing. No fluff.

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

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

No output schema, but description suffices for a retrieval tool. Explains both modes, scope, and relationship to siblings, covering needs for correct invocation.

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

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

Schema covers the single optional parameter fully (100% coverage). Description reinforces meaning of omitting key, but adds little 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 retrieves a value by key or lists all keys if key is omitted, distinguishing it from siblings like 'remember' 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?

Explicitly specifies when to use: to look up previously stored context without re-deriving. Implies alternatives: use 'remember' to save, 'forget' to delete.

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=true, idempotentHint=true, and destructiveHint=false. The description supplements this by explaining that mark_read:true flags events as read so subsequent calls return only newer ones, and that the tool returns the most recent alerts. This adds behavioral context beyond the annotations.

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

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

The description is two concise sentences. The first sentence delivers the primary purpose, and the second efficiently covers return fields, filter options, mark_read behavior, and alternative access. No redundant information.

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

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

Despite lacking an output schema, the description adequately explains the return data (source, citation_uri, raw payload). It covers all parameter behavior, the side effect of mark_read, polling suitability, and provides an alternative endpoint. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, baselining at 3. The description adds value by giving an example filter value ('sec_8k'), explaining that 'since' expects an ISO timestamp, and detailing the effect of mark_read on subsequent calls. This goes beyond the bare schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed', specifying the resource and action. It lists the specific data fields (source, citation_uri, raw payload) and distinguishes the tool from siblings by focusing on alerts from the subscription feed.

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

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

The description provides explicit usage guidance: filtering by type and/or since, setting mark_read to track read status, and notes that polling works fine. It also mentions an alternative REST endpoint for scripts/dashboards, which helps the agent decide when to use this tool versus the direct API.

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, idempotent, non-destructive. Description adds that it fans out to SEC EDGAR, GDELT/GNews, and USPTO, with fallback logic and soft-failure. Also describes return format with grouped changes, count, and citation URIs, providing comprehensive 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?

Description is detailed and well-structured, with examples and fallback information. While slightly lengthy, every sentence contributes useful information. Could be slightly more concise but overall efficient.

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

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

No output schema, but description explains return structure with changes[], total_changes, and pipeworx:// URIs. Covers all input parameters with examples, fallbacks, and limitations. Complete for a complex multi-source 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 descriptions already cover 100% of parameters. Description adds practical usage guidance: type is only 'company', since accepts ISO date or relative shorthands with recommendation ('30d' or '1m'), and value accepts ticker or CIK. This adds significant value 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 it provides a change feed for a company, with multiple example queries. It distinguishes from sibling tool entity_profile by specifying that entity_profile is for static profiles, while recent_changes is for recent activity.

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 gives example queries ('what's new with X') and tells when to use entity_profile instead. Also describes fallback behavior between GDELT and GNews, and notes USPTO soft-failure, providing clear context on when to use this tool.

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

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

Description adds context beyond annotations: key-value scoping, persistence details (authenticated vs anonymous), and session duration. Annotations (idempotentHint: true, destructiveHint: false) are consistent and enriched.

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

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

Three sentences, front-loaded with the core purpose, no filler. Every sentence adds value.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers functionality, usage, behavior, and related tools.

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

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

Schema already covers both parameters with descriptions (100% coverage). Description provides usage examples but does not add new syntactic or semantic details beyond the schema.

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

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

The description uses specific verbs ('save') and resources ('data') with concrete examples (resolved ticker, target address, user preference). It clearly distinguishes from sibling tools '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?

Explicitly states when to use: 'when you discover something worth carrying forward'. Explicitly names alternatives: 'Pair with recall to retrieve later, forget to delete.'

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 that calls cascade through multiple endpoints, replacing manual lookups, providing extra behavioral context beyond annotations.

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

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

Description is front-loaded with examples and structured by entity type. It is somewhat lengthy but every sentence provides necessary information, 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?

Despite no output schema, the description fully explains return values for each entity type. It covers supported input types, internal cascading behavior, and citation URIs, making it complete for agent 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%, but description enriches each parameter with concrete examples, accepted input formats, and return details (e.g., ticker+CIK+company_name for company, RxCUI+ingredient+brand for drug). Adds significant value beyond the schema.

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

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

The description clearly states the tool resolves entity names to canonical identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes between entity types and contrasts with sibling tools like resolve_term.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context. While no explicit when-not or alternatives are given, the guidance is sufficient for typical 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 readOnly, openWorld, idempotent, and non-destructive. The description adds the matching algorithm (exact first, then fuzzy flagged) and notes 'Keyless', which are valuable behavioral details beyond annotations.

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

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

Two sentences plus one word, front-loaded with the main purpose. Every sentence adds value: mapping purpose, algorithm details, and authentication status. 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 simplicity (2 params, no output schema), the description covers purpose, algorithm, and keyless access. It could mention the output format (list of descriptors) for completeness, but overall adequate.

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 3. The description provides examples for 'text' but no additional semantics for 'limit'. The schema already documents both parameters adequately.

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

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

The description uses a specific verb 'Map' and clearly identifies the resource: free-text term/synonym to canonical MeSH descriptor(s). It distinguishes from siblings by specifying the context of PubMed searching and the algorithm behavior.

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

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

Implied usage for PubMed MeSH mapping but no explicit guidance on when to use vs alternatives like search_descriptors or get_descriptor. The description does not mention when not to use this tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are complemented by the description's details: 'Probes each entity... with ai_visibility_check', 'Returns ranked list with score, confidence, signal density per entity.' No contradictions. The description adds behavioral context such as the ranking mechanism and output structure.

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

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

The description is three sentences, focused and front-loaded. The first sentence states the core purpose, the second elaborates on the mechanism, and the third provides a usage example. 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?

Given the tool's complexity (4 parameters, 1 required, no nested objects, no output schema), the description is complete. It covers all parameters, the expected output (ranked list with score, confidence, signal density), and the prerequisite structure (2-8 entities, first is subject). No gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains that the first entity is treated as the 'subject' for the narrative, the models parameter conditionally requires _apiKey, and the context parameter disambiguates common names. This guidance helps the agent use parameters correctly.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probing with ai_visibility_check), the result (ranked list, most/least recognized), and the use case (competitive AI-marketing audits). This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' This implies when to use the tool. However, it does not explicitly state when not to use it or directly reference alternatives. The sibling list includes ai_visibility_check for single-entity probes, but the description does not advise switching to that tool for single entities.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds key behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts, and the rest still returns.

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

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

Description is detailed but well-structured and front-loaded with the composite nature. Every sentence adds value, though it could be slightly more concise for a quick scan. Still, it efficiently covers use cases, ecosystem limits, and edge cases.

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

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

Despite no output schema, the description thoroughly explains the return format: summary block (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers behavior on partial failures and timing, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that scoped packages (e.g., @types/node) are accepted for 'package', and 'version' defaults to latest. Provides example values, enhancing understanding 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?

Clearly states the tool is a composite check for evaluating npm packages, combining deps.dev and bundlephobia data. Specifies the NPM ecosystem only, distinguishing it from sibling tools like deps.dev:version for other ecosystems.

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

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

Explicitly says use when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes that PyPI/Maven/Cargo/Go fall under a different tool (deps.dev:version), providing clear when-not 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 provide readOnlyHint, idempotentHint, and openWorldHint. The description adds the 'Keyless' behavioral trait (no API key needed) and specifies the return format (D-IDs). It does not contradict annotations and provides useful context beyond them.

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

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

Three sentences with no fluff: the first sentence states the action and resource, the second clarifies the output format, and the third highlights the core feature. Front-loaded and efficient.

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

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

For a search tool with 3 documented parameters, no output schema, and annotated safety profile, the description is complete: it explains the input (free-text), output (D-IDs), and key behavioral note (keyless). It could mention match mode behavior, but that is covered in the schema. Slight gap on pagination or result handling.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description does not add new parameter semantics beyond giving examples for the 'text' parameter (which align with the schema). Baseline 3 is appropriate as the schema carries the informational burden.

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 searches NLM MeSH descriptors by a term, with concrete examples ('diabetes', 'aspirin'), and identifies the output as MeSH descriptor IDs (Dxxxxxxx). This distinguishes it from sibling tools like 'get_descriptor' (which retrieves details for a given ID) and 'resolve_term' (likely for different ontologies).

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 describes itself as 'the core free-text-to-MeSH lookup', which implies primary usage, but does not explicitly mention when to use alternatives (e.g., 'get_descriptor' for known IDs) or provide exclusions. No explicit when-not or guidance against using other tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds rich behavioral details: embedding model (BGE-base-en), similarity (cosine), windowing (500-char overlapping), character offset return, 200K char cap with truncation flag. No contradiction with annotations.

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

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

Description is a single paragraph, but information density is high. It is front-loaded with main purpose and usage. Could be slightly more structured (e.g., bullet points for limitations), but remains concise without wasted words.

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

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

Given no output schema, description adequately explains return structure (passages with character offsets and similarity scores). Addresses limitations (200K cap, truncation flag). Explains embedding model and pairing with sibling. Covers all essential aspects for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds marginal value beyond schema: for 'text' it reinforces the 200K char cap and mentions truncation flag; for 'query' gives example queries. This lifts the score above baseline.

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

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

Description clearly specifies verb ('semantic search INSIDE a fetched record') and resource ('a fetched record'), with concrete examples like SEC 10-K. Differentiates from sibling 'ask_pipeworx_grounded' by noting that one should fetch first then search, making the tool's role distinct.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Provides direct alternative guidance: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'. No ambiguity.

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 mark idempotent, non-readonly, open world. Description adds return of subscription id, OAuth requirement, type-specific parameters, delivery limitations (SMS cap, webhook auto-disable), and signing details, far exceeding annotation coverage.

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

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

Very information-dense with no wasted words, but slightly long; could benefit from bullet points for readability. Front-loaded with main 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?

Complete coverage: purpose, parameters, return value, prerequisites, limitations, examples. No output schema, but 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?

Despite 100% schema coverage, description enriches every parameter with concrete examples (e.g., 'items:["5.02"]' for sec_8k) and delivery constraints (verified phone, 10/day cap, webhook signing), adding significant meaning.

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

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

The description clearly defines the tool as creating a proactive monitoring subscription, listing specific types and delivery channels, and distinguishes it 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?

Explicitly states requirement for Pipeworx OAuth account and when to use each type, but could be more explicit about when not to use or compare to alternatives like recent_alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: it's the onboarding entry point, returns specific categories, and can be called with no args.

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

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

The description is comprehensive and well-structured with example queries upfront, though it could be slightly more concise.

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

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

For an onboarding tool, the description covers when to use, what to expect, how to use arguments, and the return structure comprehensively.

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

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

Schema covers the single parameter fully, but description adds explicit list of valid topic values and explains the effect of omitting vs providing the argument.

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, distinguishing it from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains when to pass the topic parameter for focus.

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

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

Adds context beyond annotations: explains deactivation (consistent with destructiveHint=false) and ownership enforcement. No discussion of rate limits or error scenarios, but annotations already provide idempotentHint and openWorldHint.

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 fluff. Front-loaded with action and constraint, then behavioral detail. Highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, side effects (deactivation), and relation to another tool. 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 coverage is 100% with a clear description of the 'id' parameter. The tool description does not add additional meaning beyond the schema, so baseline 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?

Clearly states verb 'cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' and implies it is the inverse operation.

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

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

Explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear when-to-use guidance. Also explains the deactivation behavior and references 'recent_alerts' for historical data, but does not explicitly mention when not to use it beyond ownership.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it returns a verdict with specific categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), a structured form, actual value with citation, and percent delta. It also explains the underlying data source and that it consolidates multiple sequential calls.

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 each sentence serves a purpose: trigger phrases, purpose, domain, return values, and efficiency note. It is well-organized and front-loaded with the most important information. No unnecessary words.

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

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

Given that there is no output schema, the description fully explains the return format (verdict options, structured form, citation, delta). The tool has only one parameter, and the description covers its domain and provides examples. It is complete for an agent to understand what the tool does and what it returns.

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

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

Schema coverage is 100% with one parameter 'claim' described. The description adds examples of valid claims and clarifies the domain (company-financial), which goes beyond the schema's own description. Since the schema already covers the parameter well, the description adds meaningful context.

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

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

The description starts with clear natural-language triggers ('Is it true that…', 'fact check') and explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims) and sources (SEC EDGAR + XBRL), distinguishing it from sibling tools that are more general or focused on other tasks.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of user intents and mentions that it replaces 4-6 sequential calls, giving efficiency guidance. However, it does not explicitly state when not to use it or suggest alternatives for non-financial claims.

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