Clinicaltables

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 that it makes LLM calls (network activity) and that Anthropic calls incur separate costs, which is valuable beyond annotations. It doesn't fully detail failure modes but is adequate.

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 serving a purpose: purpose and output, key usage note, return format. No redundant information. 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?

The description covers the main outputs (per-model score, confidence, signals, raw_response, combined view). Given no output schema, it provides a reasonable summary. It could mention error handling for invalid API keys, but overall complete for its complexity.

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

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

Schema coverage is 100% with descriptions. The tool description adds context about defaults ('default model is Workers AI Llama-3.3-70b (free)') and usage of _apiKey ('BYO key — you pay Anthropic directly'), which enriches the parameter meaning beyond the schema.

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

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

The description clearly states the tool probes LLMs for brand visibility and outputs a score 0-100 per model. It distinguishes itself from siblings by focusing on visibility scoring rather than general Q&A or competitor scanning.

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

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

The description lists specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default behavior and API key requirement. It doesn't explicitly compare to alternatives but provides enough context for when to use.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds behavioral detail: routes to 5,529 tools across 1,455 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. This goes beyond annotations without contradicting them.

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

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

The description is longer than average but front-loaded with the key directive ('PREFER OVER WEB SEARCH') and organized into clear use cases. Some minor redundancy ('START HERE' and 'default entry point') but overall each sentence contributes useful context.

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 exists, but the description explains the output type ('structured answer with stable pipeworx:// citation URIs'). It covers scope, routing behavior, alternatives, and example queries, making it complete for a high-level question-answering 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 covers 100% of parameters and the main 'question' property has a clear description. The description adds natural-language examples and clarifies that the question can be a lookup phrase. This enriches the parameter semantics beyond the alias-only schema entries.

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

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

The description clearly states the tool's purpose: 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists specific domains. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, and positions itself as the default entry point.

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

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

Provides explicit when to use ('Use whenever the user asks...', 'START HERE for most questions') and when not to ('Step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part questions use deep_research'). This directly addresses alternatives and exclusions.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive, and the description adds valuable context beyond these: the tool's behavior changes when a candidate routing improvement is under test, and it currently matches ask_pipeworx because no candidate is active. It also clarifies that it is a full working router, not a fallback stub. No contradiction with annotations.

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

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

The description is moderately sized and efficiently front-loaded: it starts with the key beta designation, then explains functional equivalence, current experimental state, usage guidance, and fallback behavior. Every sentence contributes new information, though it could be slightly condensed without losing meaning.

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 role as an experimental router, the description covers the essential context: what it does, how it relates to the stable version, when to use it, and its current behavior. No output schema exists, but the description's reference to "same response shape" as ask_pipeworx suffices. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema already documents all six parameters (question plus five aliases) with 100% coverage. The description does not add additional semantics about parameters, but none are needed since the schema fully explains them. Baseline of 3 is appropriate for high schema coverage.

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

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

The description clearly states it is a beta version of ask_pipeworx, identifies it as a universal router with the same 5,529 tools and arguments, and distinguishes it from the stable ask_pipeworx sibling. The verb "ask" plus "router" specifies the action and resource, and the beta context differentiates it from siblings.

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

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

The description provides explicit guidance on when to use this tool: "Use it exactly like ask_pipeworx when you want the newest routing." It also explains the comparison process against the stable router and clarifies the current state (no active candidate). However, it does not explicitly mention when not to use it or compare against other siblings like ask_pipeworx_grounded.

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?

Goes far beyond annotations by explaining the internal routing process, the strict extraction from tool results, the output schema including refusal_reason values, and the extra LLM call cost. It fully discloses refusal behavior and error modes.

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 every sentence contributes essential operational detail. It is well-structured: definition, behavior, use cases, and trade-off. Slightly verbose but justified by complexity.

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

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

With no output schema, the description fully specifies the return shape on success and failure, including refusal reasons, evidence quotes, and metadata. It also covers when to use vs ask_pipeworx, making it complete for an AI agent.

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

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

Input schema already describes the 'question' parameter and aliases at 100% coverage. The description adds no additional parameter-level detail beyond 'natural language', so baseline 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that routes to tools and extracts answers using only tool results, distinguishing it from the sibling ask_pipeworx. It details the exact output structure and when to use it, making the purpose unmistakable.

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

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

Explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and contrasts with 'prefer ask_pipeworx for casual lookups', naming the alternative and providing concrete scenarios (financial verdicts, legal claims, etc.).

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

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

The description richly discloses behavioral traits beyond annotations: it explains market resolution, classification, fan-out to category-specific data packs, evidence packet return, model comparison, market matching confidence, parent event extraction, news field fallbacks, safety mechanisms for low-confidence matches and closed markets, and resolution-rule risk. This is consistent with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is comprehensive but lengthy, containing multiple sections and examples. It is well-structured with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loads the main purpose. While not overly concise for an AI agent, it earns its length given the tool's complexity.

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

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

With no output schema, the description thoroughly explains response shapes, evidence structure, matching confidence, parent event extraction, news fields, and safety behaviors. It covers all critical aspects an agent needs to use the tool correctly, leaving little ambiguity.

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

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

Schema coverage is 100%, yet the description adds significant meaning: it explains that 'market' can be a slug, full URL, or question text; describes 'depth' values (quick vs thorough) and their implications; and details 'include_raw' when to use raw vs summarized payloads. 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 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 differentiates from sibling tools like polymarket_arbitrage by emphasizing the comprehensive, single-call nature.

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

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

The description explicitly suggests use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of classifiers and fan-out behavior. However, it does not explicitly state when not to use this tool or compare it to alternatives, though the context implies it.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description adds details on data sources, handling of off-calendar fiscal years, result sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is comprehensive and front-loaded with example queries and a clear directive to prefer over sequential lookups. While it is slightly verbose, every sentence adds value, making it 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?

Given the tool's complexity (two entity types, multiple financial metrics, no output schema), the description covers all necessary aspects: data sources, handling of fiscal years, sorting, output format (paired data + URIs), and replacement of many sequential lookups. It is complete for agent invocation.

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

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

The input schema already provides descriptions for both parameters (type with enum, values with constraints). The description adds further context on how to specify values (tickers for companies, drug names for drugs) and what data each type retrieves, enhancing clarity.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2–5 companies or drugs in one call, using specific data sources (SEC EDGAR for companies, FAERS for drugs). It includes example queries and distinguishes itself from sequential single-pack lookups.

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

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

The description explicitly instructs to always prefer this tool over sequential lookups when comparing entities. It provides context on when to use it (comparison queries) and explains the data returned for each type, making the usage clear.

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

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

Annotations already declare safe read-only, idempotent, open-world behavior. Description adds specifics: vocabulary size (~700), match type (prefix/contains on canonical names), and tokenization (whitespace-split AND). No contradictions.

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

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

Description is concise (~80 words), front-loaded with example queries, and packs essential details without redundancy. 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, so description should explain return structure. It says 'returns canonical names' but the input schema includes df and ef parameters implying displays and extra fields. Description does not detail the output format or field behavior, leaving some ambiguity for a search tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds minimal extra meaning—provides a search example ('migraine') and notes that the result includes canonical names. It does not elaborate on df/ef fields beyond what schema says.

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 searches a specific NLM vocabulary of ~700 patient-friendly conditions, listing example queries and typical uses like symptom-to-condition lookup. It distinguishes itself from siblings (e.g., disease_names, icd10cm) by focusing on lay-reader terms.

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

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

Description provides explicit use cases (symptom lookup, intake forms, simplifying clinical text) and hints at context (prefix/contains match, AND tokenization). It does not explicitly mention when not to use or name sibling alternatives, but the use cases are clear enough.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses a wealth of behavioral traits: account and paywall requirements, 'NOT open-web search', parallel routing to 5,529 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] with 'never invented', contradictions[] for standard/thorough, the hop field, citation_uri fetchability, semantic excerpting of large records, and latency expectations (15-60s, up to ~90s for thorough).

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 (roughly 250 words) but every sentence earns its place with a dense new fact: account gating, the structured-data distinction, parallel routing, findings packet, gaps[], contradictions[], hop field, citation fetchability, excerpting, and latency. It is front-loaded with the most critical action (account requirement and alternative) and follows a logical order. It could arguably trim some redundancy around 'NOT open-web search' and current-news exclusion, but overall it is structured and necessary for a tool of this complexity.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers prerequisites (account, paid plan), target use cases, limitations (current news yields gaps), what the returns look like (findings packet with fields), timing, and alternatives. It even explains edge cases like unanswerable facets and fetchable citations, leaving an agent with almost no unknowns for selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches meaning beyond the enum names and property descriptions: it explains depth values in terms of facet counts and hops ('quick=3 (single hop)', 'standard=5 (default...)', 'thorough=8 (paid...)'), which the schema does not convey. It also clarifies that 'question' should be broad/multi-part and that decomposition is the feature, adding decision-relevant semantics.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and clearly distinguishes from siblings with 'this is NOT open-web search' and explicit comparisons to ask_pipeworx for single lookups and current news. It also explains the internal mechanism (decompose into facets, route in parallel to 5,529 tools) which leaves no ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and detailed when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names an alternative for unsigned-in users ('use ask_pipeworx instead') and clarifies account/tier prerequisites upfront.

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, destructiveHint=false. The description adds that it returns top-N relevant tools with schemas ready to call, no second lookup needed. This adds context beyond annotations about the return format and usability.

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 purpose, then return details and usage advice. No wasted words, every sentence adds value.

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

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

Without an output schema, the description fully explains what is returned (top-N tools with schemas, ready to call) and covers the domains. For a discovery tool with simple params, this is complete.

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

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

Schema description coverage is 100%, so baseline 3. The description mentions aliases and examples but doesn't add significant meaning beyond what the schema already provides for parameters.

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 tools by describing data or task, using verbs like browse, search, look up, or discover. It lists specific domains, making purpose concrete and distinguishing it from sibling tools which are individual data 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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies it's for exploration before selecting a specific 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 provide idempotent/readOnly hints; description adds search behavior (prefix/contains, AND tokens), ~12k entries, and broader coverage. 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?

Single paragraph front-loaded with examples; every sentence adds value; no wasted words.

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

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

No output schema, but description explains return values (UMLS CUIs, canonical names) and search semantics; sufficient for a lookup tool with 4 well-documented parameters.

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

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

Schema covers all 4 parameters with descriptions; description adds practical usage guidance (e.g., count ranges for typeahead vs. browsing) and example queries for terms.

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

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

The description clearly states the tool searches the NLM Disease Names vocabulary, returns UMLS CUIs and canonical names, and distinguishes it from sibling tool 'conditions' by noting broader coverage of rare diseases, syndromes, and clinical terminology.

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 you need clinical-grade vocabulary linkage rather than patient-friendly labels,' contrasting with conditions, but doesn't explicitly list when not to use.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: prefix/contains matching, whitespace-split AND tokens, and return format with route/strength. No contradictions.

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

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

The description is front-loaded with examples, followed by purpose, use cases, and parameter tips. It is slightly verbose but well-structured. 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?

With 4 parameters, no output schema, and good annotations, the description covers search behavior, return format, parameter usage, and use cases adequately. Minor missing details about tokenization or sorting are not critical.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning: explains ef options with examples, suggests count values for different UX (typeahead vs browsing), and clarifies terms matching logic.

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 is for drug name lookup, autocomplete, and prescription entry using RxTerms. It provides specific examples like 'Aspirin (Chewable)' and distinguishes it from sibling medical tools.

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

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

The description explicitly lists use cases: prescription entry, autocomplete, and stepping-stone to RxNorm RxCUI lookups. It gives parameter advice (e.g., using ef to include strengths and RXCUIs) but does not compare with siblings like 'conditions' or 'disease_names'.

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 behavioral detail: fans across multiple sources, returns specific data points, notes soft-failure for patents (USPTO API sunset May 2025), and mentions it returns URIs. No contradictions; fully transparent.

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

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

Description is long but well-structured: starts with examples, then purpose statement, then detailed return list. Some repetition ('Names not supported' appears twice) but every sentence adds value. Could be slightly tightened but still effective.

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

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

No output schema exists, so description must cover return values. It does so comprehensively: lists CIK, company name, filings with URIs, fundamentals (period_end descending), patents with sunset note, news, LEI. Also covers input constraints. 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%, baseline 3. Description adds value by explaining the 'value' parameter can be ticker or zero-padded CIK, and reiterates that names are not supported with a pointer to resolve_entity. This actionable guidance lifts score to 4.

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

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

Description starts with clear user query examples, then states 'full cross-source profile of a US public company in ONE parallel call.' It explicitly names the verb (research/profile) and resource (US public company). It distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

Provides explicit when-to-use: when user asks for a holistic view of a US public company. It says 'ALWAYS PREFER over chaining' and also gives when-not: 'Names not supported — use resolve_entity first if you only have a name.' This clearly guides the agent on alternatives.

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

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

Annotations already indicate destructiveHint=true, idempotentHint=true. Description adds context about clearing sensitive data, which aligns and provides extra nuance 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?

Three concise sentences front-loaded with core action, usage conditions, and sibling pairing. 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?

Simple tool with one parameter and no output schema; description fully covers what, when, and related tools, leaving no gaps.

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

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

Schema has 100% coverage with a clear description for the key parameter; description mentions 'by key' but doesn't add new 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?

Description clearly states 'Delete a previously stored memory by key' with verb, resource, and method, distinguishing it from siblings remember/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?

Explicitly tells when to use: context stale, task done, clear sensitive data. Also pairs with remember and recall for completeness.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the process: fetches page, extracts title/description/key links, and emits standard llms.txt format. It also specifies the output is a single text blob ready for deployment.

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 serving a purpose: main action, process details, and usage examples. No unnecessary words, front-loaded with the core purpose.

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

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

Given the simple tool (2 params, no output schema), the description covers input, process, output, and usage scenarios completely. Annotations further clarify safety and idempotency.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about the output format but does not significantly enhance parameter understanding 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 uses a specific verb ('Generate') and resource ('llms.txt file for any URL'), and distinguishes it from sibling tools like 'scan_competitor_ai_presence' by focusing on the llms.txt generation task.

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 three use cases (indexing a client's site, drafting for own project, auditing competitor). Lacks explicit when-not-to-use or direct alternative tool names, but guidance is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds search behavior (prefix/contains match, AND tokens), return format (code + full description), and example output, 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?

Description is compact, front-loaded with example queries, and every sentence adds value. No wasted words.

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

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

For a simple lookup tool, all aspects are covered: purpose, parameters, behavior, output format, use cases. Schema annotations cover safety. No output schema needed as return value is described.

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 3. Description reinforces 'terms' parameter but adds little beyond schema. No additional semantics for df, ef, or count 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 explicitly states 'search ICD-10-CM diagnostic codes' with verb and resource, and provides example queries and use cases (medical billing, EHR coding). It distinguishes from siblings via name (ICD-10 vs ICD-9) and context.

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?

Clear use cases provided (medical billing, EHR diagnosis coding, claim coding). Lacks explicit when-not or alternatives like icd9cm, but the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. Description adds context of being a search tool for legacy codes and references icd10cm for shape, reinforcing the read-only nature. 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 two sentences long, with no filler. Every word serves a purpose: defines the tool, specifies usage context, and references a sibling tool for shape consistency.

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 4 well-documented parameters and rich annotations, the description covers scope, legacy nature, and usage guidance. Lacks explicit output format but references icd10cm shape, which is sufficient. Minor gap in not describing return structure independently.

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 parameters are fully documented in the schema. Description does not add additional meaning or usage hints beyond the schema, but baseline score of 3 is appropriate as schema adequately defines parameters.

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 searches legacy ICD-9-CM diagnostic codes, specifying verb (search) and resource (legacy codes). It distinguishes from sibling icd10cm by noting it is for pre-2015 records, and mentions 'Same shape as icd10cm' for consistency.

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 ('only when working with pre-2015 US clinical records') and when not to ('new claims must use icd10cm'). Provides clear directional guidance by naming the alternative 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 that it returns certain fields, but annotations already declare readOnly, idempotent, not destructive. No additional behavioral context beyond what annotations provide.

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

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

Uses only two sentences, front-loaded with core information and usage guidance. Efficient and no wasted words.

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

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

For a simple list tool with one optional param and no output schema, the description covers return fields and usage context adequately.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema for the boolean include_inactive parameter. 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?

Clearly states the tool lists the caller's subscriptions, with specific fields returned. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says use to review before adding more or to find an id to cancel. Provides clear context, though no explicit when-not-to-use.

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

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

Annotations already declare idempotent, read-only, open-world, and non-destructive. Description adds search behavior details (prefix/contains match, AND tokens), display field customization via `df`/`ef`, and return format example. No contradictions.

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

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

Three sentences with examples. Front-loaded with purpose and usage patterns. Every sentence adds value; no filler.

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

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

Describes input (search terms, display/extra fields, count) and output (example code with component and units). Missing formal response structure (no output schema), but the example suffices for a search tool. Adequate given tool 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 covers all 4 parameters (100%). Description enriches `df`/`ef` with default behavior and reference to external docs, provides concrete value suggestions for `count`, and gives a clear example for `terms`. Adds meaningful context beyond schema.

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

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

The description uses specific verbs ('search', 'lookup') and identifies the resource ('LOINC lab test codes'). Examples clarify the output format. It distinguishes from sibling tools like ICD10CM/ICD9CM by focusing exclusively on lab test identifiers.

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

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

Provides explicit guidance: 'Use when normalizing lab results across institutions.' Includes example queries and result formats. Does not explicitly mention when not to use or list alternatives, but sibling tools cover other code systems, making the context clear.

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

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

Annotations declare readOnly, idempotent, and not destructive. The description adds that the registry has ~5M entries, returns NPI numbers and provider names, and that terms can be name, NPI, or specialty. This provides useful behavioral context beyond annotations without contradiction.

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

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

The description is a single, information-dense sentence that starts with example queries, then states the core action, return content, and extra fields. Every part is relevant, though it could be slightly more structured for readability. No wasted words.

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

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

Despite no output schema, the description explains what is returned (NPI numbers + provider names) and how to enrich results with 'ef'. For a search tool, this is sufficient for an agent to understand invocation and expected output. The count parameter is documented in schema, so not repeated.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'terms' can be a name fragment, NPI, or specialty (schema only says 'prefix/contains match against canonical names'). It also clarifies that 'ef' includes address, specialty, gender, which is more user-friendly than the schema's field list.

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

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

The description clearly states the tool searches the NPPES registry for individual US healthcare providers and returns NPI numbers and provider names. It provides example queries (find doctor by name, look up NPI, verify credentials) and distinguishes from siblings via the title 'Npi Individual' and the mention of 'individual' providers, contrasting with sibling 'npi_organization'.

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

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

The description gives concrete usage scenarios (find doctor, look up NPI, verify credentials) and explains acceptable input types (name fragment, NPI, specialty). It also advises using 'ef' for extra fields. However, it does not explicitly exclude organizational searches, which would be better handled by the sibling 'npi_organization'.

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 the tool as read-only, idempotent, and non-destructive. The description adds useful context about the data volume (~1.8M entries) and searchable fields (name, NPI, city), but does not contradict annotations. Behavioral disclosure is adequate given the annotation coverage.

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

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

The description is front-loaded with examples, then provides the functional description in a concise format. Every sentence adds value without extraneous text.

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

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

Given the tool has 4 parameters, no output schema, and high schema coverage, the description adequately covers the tool's purpose and search capabilities. The note 'same shape as npi_individual' provides indirect output structure context. It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor value by specifying that terms can include city (beyond schema's 'canonical names') and clarifying default behavior for df. However, it does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool is for searching the NPPES NPI registry for organizational providers like hospitals and group practices. It includes specific verb phrases ('Find a hospital / clinic by name', 'look up NPI for [organization]') and distinguishes from the sibling tool npi_individual by noting the same shape but for organizations.

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 usage scenarios (e.g., 'verify a healthcare facility') and mentions that terms can be org name, NPI, or city. While it references npi_individual as 'same shape,' it does not explicitly state when to use one over the other, but the context and sibling listing make it inferable.

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

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

Annotations are all false, providing no behavioral information. The description compensates fully by disclosing the claim_token follow-up mechanism, rate limiting, freedom from quota, and that the team reads digests daily. 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 well-structured and front-loaded with the purpose, followed by usage, exclusions, operational details, and limitations. Every sentence provides distinct value, and the length is appropriate for the tool's complexity.

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

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

The description is comprehensive: it covers usage triggers, exclusions, input guidance, token lifecycle, rate limits, and roadmap impact. With all parameters documented in the schema and no output schema, the description fully equips an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by explaining how to use claim_token for follow-up and advising against pasting end-user prompts, which complements the schema's parameter 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 verb 'tell' with the resource 'Pipeworx team' and specifies the scope: 'something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools by focusing on feedback rather than research or data retrieval.

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

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

It explicitly lists when to use the tool (bug, feature/data_gap, praise) and when not to (different MCP server, file with that server instead). It also provides a heuristic for uncertainty: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating safe, read-only operation. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, cached (5min-1h), and aggregate nature. This supplements the 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?

The description is concise and well-structured. It front-loads the core purpose, then lists use cases in numbered points, and ends with technical details. Every sentence adds value without 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 simplicity (1 optional parameter, no output schema, rich annotations), the description is complete. It covers what it returns, the source, caching behavior, and privacy. An agent can confidently decide to use it based on this description.

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

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

Schema coverage is 100% with a single optional parameter. The schema already includes a detailed description and enum values. The main description does not add additional parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Returns the top tools, top packs, and total call volume over a recent window.' It specifies the resource (trending data on Pipeworx) and uses specific verbs ('returns'). It distinguishes from sibling tools by focusing on usage statistics derived from other AI agents.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case), providing clear guidance on when to use the tool. It also mentions caching and data derivation. However, it does not explicitly state when not to use it or directly compare to siblings, which would enhance the score.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safety; description adds rich algorithmic details: monotonicity checks, partition_sum, semantic anchor similarity, placeholder filtering, fill check logic. 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?

Long but well-structured: first sentence states purpose, then modes explained in logical order. Each sentence adds necessary detail; could be slightly trimmed but not excessive.

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

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

Comprehensive given no output schema: explains algorithm, outputs, fill check, edge cases (low similarity, placeholder filters). Covers all aspects needed for an AI agent to use correctly.

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

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

Schema has 100% coverage with descriptions; the description adds value by explaining the modes, accepted formats (slugs/URLs), and behavior when no args given.

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

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

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

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

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

Explicitly describes when to use each mode: no args for trending scan, event for specific event, topic for cross-event. Also provides guidance on when not to trade (e.g., when fill check shows realizable edge ≤0) and points to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant transparency beyond annotations: explains output structure (by_segment, diagnostics), caching policy (1h KV-level), edge calculation details, and knob behavior. No contradiction with annotations.

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

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

Description is lengthy but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.). It front-loads the main purpose and uses structured format. While not maximally concise, every sentence serves a purpose and avoids redundancy with schema.

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 tool complexity (9 parameters, no output schema, rich output semantics), description is highly complete. It explains response segments, edge metrics, filter knobs, diagnostic info, and caching. Output schema is absent but description fully compensates by detailing return structure and diagnostic fields.

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 param descriptions. Description adds meaning beyond schema for several parameters (e.g., min_partition_leg_kelly explains why it exists separately from min_kelly, and slippage_pp provides context on Polymarket fees). Not all parameters get extra explanation, but the added value is meaningful.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan), the resource (Polymarket markets), and the unique value proposition (disagreement detection). The detailed breakdown of model families and response segments distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Description explicitly targets 'what should I bet on today' use case and mentions caching behavior. It provides clear context for when to use the tool, though it does not explicitly state when NOT to use it or directly reference alternatives. The sibling list implies alternatives but description lacks explicit exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral details: explains decay computation, snapshot gaps, and data limitations (60-day TTL, no intraday). 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 informative and front-loaded with the key question. While slightly verbose, every sentence adds value, listing response fields and limitations efficiently.

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 comprehensively explains the response structure (tracked[], expired[], snapshot_dates[]) and key fields (edge_pp_net time-series, trend, decay, first_seen, lifespan, snapshot dates). It also addresses limitations (60-day TTL, gaps, no intraday).

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 100% of parameters with basic descriptions. The tool description adds meaning by explaining how 'days' affects lookback (default 14, max 30) and 'window' selects snapshot family (default 1wk), tying parameters to the tool's purpose.

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 analyzes edge persistence and decay from historical snapshots, distinguishing it from the sibling 'polymarket_edges' (current edges). It answers a specific question: 'how long has this edge existed and is it shrinking?'

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 (understanding edge persistence, comparing fresh vs. old edges) and provides context about history depth and TTL limits. However, it does not explicitly mention when not to use or name alternative tools beyond the sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=False. Description adds substantial value by detailing outputs like top_of_book, vwap_fill_price, slippage_pp, verdict, and critical risks such as forced directional risk and thin_legs. 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 dense but well-structured with CAPS for mode names and bullet-style output lists. Every sentence adds value, though could be slightly tightened. Front-loading the main purpose and separating modes by paragraphs aids readability.

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

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

No output schema exists, so description fully explains return values for both modes, including specific fields like capture_ratio, profit_usd, thin_legs[], and forced_directional_risk. Also covers failure modes (partial fills, unhedged positions), making the tool's behavior completely predictable.

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 each parameter described. Description adds significant meaning: explains modes (single-market vs basket) and how size_usd is interpreted differently (max spend vs target proceeds for single-market, settlement notional for basket). Also clarifies side defaults and auto-detection in basket mode.

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 performs a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket). It distinguishes from sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges, advising usage 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?

Provides explicit when-to-use guidance: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also specifies prerequisites (arb signals) and warns against partial basket fills converting arb into directional risk, effectively excluding misuse.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false. The description goes beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains when spreads are meaningful or not. No contradictions.

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

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

The description is lengthy but well-structured: first core purpose, then modes, response fields, safety fields. Every sentence adds value, though some sentences are dense and 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 a complex tool with no output schema, the description is remarkably complete. It covers modes, response structure, compatibility conditions, temporal alignment, skipped comparisons, and real-world rarity of spreads. No important aspect is missing.

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

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

Schema coverage is 100% with parameter descriptions. The description adds semantic meaning: it explains the topic parameter's 10 shortcuts, explicit tickers override topic mapping, and the interplay between them. This adds 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue instead of intra-venue.

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

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

The description specifies two modes (topic shortcuts and explicit tickers), provides examples, and warns that most pre-mapped topics yield compatibility warnings, advising against assuming tradeability. It does not explicitly mention alternative tools, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds context about data source (NLM, ~7k entries), result style (short names, e.g. 'Colonoscopy'), and search mechanism (prefix/contains match). 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?

Two efficient sentences: first gives query examples, second states purpose, data source, and usage boundaries. No unnecessary words, front-loaded with examples.

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

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

For a simple query tool with complete schema and annotations, the description sufficiently covers purpose, usage, data source, and limitations. No missing critical information.

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

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

Schema coverage is 100%, so description adds value by explaining the search mechanism ('prefix/contains match against canonical names. Whitespace-split into AND tokens'), which goes beyond schema field descriptions.

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

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

The description clearly states the tool searches clinical procedure names from NLM-curated list with patient-friendly names. It includes example queries and distinguishes from billing code tools (icd10cm, CPT).

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 ('for forms or intake screens') and when not to ('For billing codes use icd10cm or a CPT source instead'). Also mentions patient-facing language.

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, destructiveHint. The description adds value by explaining scoping to user identifier, behavior when key is omitted (list all keys), and pairing with remember/forget. No contradictions.

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

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

The description is well-structured with actionable guidance. Although it is somewhat lengthy, every sentence provides useful information. Could be slightly shorter.

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 is quite complete. It covers purpose, usage, scoping, and pairing. Minor missing detail: return format or type, but not critical.

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds semantics by explaining that omitting the key lists all saved keys, which is not in the schema description.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly identifies the resource ('value previously saved via remember', 'saved keys'). It distinguishes from sibling tools 'remember' and 'forget' by explicitly mentioning pairing.

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

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

The description explains when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and provides scoping and pairing info. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: setting mark_read:true flags events as read, affecting subsequent calls. It also explains that polls work fine. 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 (one compound) that front-load the purpose and key details. Every sentence adds value without redundancy. Perfect structure for quick comprehension.

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

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

Given no output schema, the description explains what is returned (source, citation_uri, raw payload). It covers filtering, marking read, and alternative access. Minor omissions like pagination or error handling are acceptable for a read-only polling tool with good annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context (e.g., 'Filter by type' and 'mark_read:true to flag returned events read') but does not significantly augment the schema's parameter descriptions. The schema already explains each parameter 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 clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull). However, it does not explicitly differentiate from sibling tools; given the sibling list includes many unrelated tools, this is acceptable but not a 5.

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

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

The description provides clear usage context: explains filtering by type and ISO timestamp, mentions polling suitability, and notes an alternative access method (GET endpoint). It lacks explicit when-not-to-use scenarios but covers the main guidance needed.

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 idempotent and read-only behavior. The description adds significant detail: fans out to multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains fallback mechanism, and notes soft-fail for USPTO. It also describes return format including grouping and citation URIs. No contradiction with annotations.

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

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

The description is well-organized, front-loading typical queries and then detailing behavior. It is slightly long but each sentence adds value. Could be trimmed slightly without losing clarity.

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

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

Given no output schema, the description adequately explains the return value: structured changes grouped by source, total_changes count, and pipeworx:// URIs. It covers edge cases like GDELT→GNews fallback and USPTO soft-fail. The complexity of multiple sources is handled well.

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 each parameter described. The description adds practical usage guidance: explains that 'since' accepts ISO dates or relative shorthand and recommends '30d' or '1m' for typical monitoring. The 'value' parameter is clarified as ticker or CIK. Marginal additional 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 explicitly states the tool is a 'change feed for a company' and provides clear examples of queries like 'What's new with X' or 'latest on Y'. It distinguishes from the sibling tool 'entity_profile' by stating when to use that instead.

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

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

The description tells when to use this tool (for dynamic recent changes) and explicitly advises 'Use entity_profile instead when you want the static profile'. It also includes example queries that set clear expectations.

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 provide idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds valuable behavioral context: 'scoped by your identifier', persistence differences for authenticated vs anonymous users. No contradictions.

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

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

Three sentences, each earning its place: first declares purpose, second gives usage guidance with examples, third details scoping and retention. Front-loaded with 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?

Given 2 simple parameters, 100% schema coverage, no output schema, and comprehensive annotations, the description adequately covers purpose, usage, and behavioral details. Lacks error handling but sufficient for core understanding.

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?

Input schema covers 100% of parameters with decent descriptions. The description adds illustrative examples for keys (e.g., 'subject_property') and clarifies value as free-text. This enhances 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 saves data for reuse across conversations or sessions, specifying verb 'save' and resource 'key-value pair'. It distinguishes from siblings recall and forget by mentioning pairing, and provides examples of what to store.

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

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

The description explicitly tells when to use: 'when you discover something worth carrying forward' with concrete examples. It also mentions pairing with recall and forget, but does not explicitly state when not to use or contrast with other tools beyond those siblings.

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

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

Goes well beyond annotations by explaining that identifiers are labeled with source, unresolved entries are listed explicitly, and GLEIF/OpenFIGI degradation does not affect EDGAR results. Adds valuable context about multi-source cascading, which is not implied by the readOnly/idempotent hints.

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

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

The description is long but every sentence adds value, with clear sectioning (SUPPORTED TYPES) and a memorable opening example. The front-loading of example queries makes the purpose immediately understandable. Slightly dense but warranted for the tool's complexity.

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

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

Despite no output schema, the description explains the key aspects of the return behavior: identifier sources, unresolved handling, and graceful degradation. It could be more precise about the exact return format, but given the complexity and annotations, it is nearly complete.

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

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

While schema coverage is 100%, the description enriches the parameters by explaining the behavior for each type (e.g., company returns a spine of identifiers, drug returns RxCUI plus citation). It adds meaning beyond the schema's simple enum and example 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?

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific verbs ('resolve', 'look up') and resource types ('company', 'drug'). It distinguishes itself from siblings by highlighting its role as the first step when a name but no ID is available, and lists exact identifier types (CIK, LEI, FIGI, RxCUI).

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use context. It does not explicitly mention when not to use or name alternative sibling tools, but the context is strong enough for an agent to decide.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds probing mechanism, ranking, and return details (score, confidence, signal density per entity), going well 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 well-organized sentences: first states primary purpose and mechanism, second gives usage scenario and return format. No fluff.

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

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

Despite 4 params and no output schema, description covers return format (ranked list with score, confidence, signal density), parameter roles, and usage context. Sufficient for an agent.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains 'context' disambiguates common names, and 'entities' first entry is subject. Offers examples and clarifies roles.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side using ai_visibility_check, ranks results, and surfaces most/least recognized. It differentiates from sibling ai_visibility_check by focusing on multiple entities and ranking.

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

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

Provides explicit context for use (competitive AI-marketing audits) and mentions the first entity is treated as subject. Lacks explicit when-not-to-use or alternative tools, but context is clear enough.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral context: fans out to two external services, partial failures degrade gracefully, bundlephobia timing (5-30s on first measurement), and sources_failed list.

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 useful information but could be more structured. Front-loads purpose and usage, then details behavior, ecosystems, and edge cases. Reasonably 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 exists, but description thoroughly explains return content (summary block, advisory detail, links, alternative versions). Covers ecosystem limitation, timing, partial failure handling. Complete for a composite 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% (both parameters described). Description adds practical meaning: scoped packages accepted, version defaults to latest. While schema already covers basics, the extra details enhance usability.

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's purpose as a composite check for evaluating npm packages, specifying the verb 'scan' and resource 'dependency'. It distinguishes from siblings by detailing its unique function and scope.

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

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

Explicitly tells when to use (agent asks about safety, popularity, size, cost) and provides alternatives (direct deps.dev for other ecosystems). Also notes partial failures and timing for bundlephobia.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. Description adds valuable behavioral details: uses BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flagged, and output includes offsets for verification.

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 perfectly front-loaded: action, use case, technical details. Every sentence adds value—no filler, no tautology, no repetition of annotations.

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 3-parameter tool with full annotation coverage, the description is comprehensive. It explains output (top-N passages with offsets and similarity), technical constraints, and integration with sibling. No output schema, but the description compensates adequately.

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

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

All 3 parameters are described in schema with 100% coverage. Description adds meaningful context: natural-language query examples ('supply-chain risk', 'fiscal year 2024 revenue'), the default limit (5), and the max text size (200K chars). This enriches parameter understanding beyond bare 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 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article, tool result). It distinguishes from siblings by naming 'ask_pipeworx_grounded' as a complementary tool and explains the unique value proposition.

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 when to use: 'when the record is too big to cram into the prompt' and how it saves context. Mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use, but context is clear enough.

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

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

Discloses behavioral traits beyond annotations: OAuth requirement, type-specific parameter behaviors, SMS cap (10/day), phone verification prerequisite, webhook auto-disable after 10 failures, and signing mechanism. No contradiction with annotations (readOnlyHint=false, idempotentHint=true).

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

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

The description is front-loaded with the main purpose, but is dense with information. While every sentence earns its place, readability could be improved with more structured formatting (e.g., bullet points for types). Still, no wasted words.

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

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

Given the complexity (multiple types, delivery channels, constraints) and no output schema, the description covers all necessary aspects: return value (subscription id), parameter details, error conditions (anonymous accounts), and functional behavior (auto-disable, signing). Fully complete.

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

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

Schema coverage is 100%, but description adds significant value: concrete examples for each type (e.g., items:['5.02'] = officer change), webhook HMAC signing details, and constraints like phone verification. This far exceeds what the schema alone provides.

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

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

The description uses a specific verb (Create) and resource (subscription), states the return value (subscription id), and distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It is not a tautology.

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 requires a Pipeworx OAuth account, lists supported types with example parameters, and explains delivery channels (feed always on, optional email/SMS/webhook). While it doesn't say 'when not to use', the context with sibling tools makes the usage boundaries clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it returns example questions with exact tool and argument shape from the live catalog, providing useful 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 somewhat lengthy but front-loaded with key phrases. It is structured with examples in parentheses and clearly separates use cases. Could be slightly shorter but still effective.

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

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

For a simple informational tool with no output schema, the description covers purpose, usage, parameters, and context (onboarding, live catalog). It is fully adequate for the agent to understand and invoke correctly.

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

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

Schema coverage is 100% for the single parameter. The description lists possible topic values (finance, pharma, etc.) that are not in the schema's enum description, adding significant meaning and explaining behavior differences without arguments.

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 is the onboarding entry point for new agents, returning category-bucketed example questions. It distinguishes from sibling tools by specifying it is for learning what Pipeworx can do and how to call meta-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, or to learn how to call the meta-tools.' Also explains calling without arguments for full spread or with topic 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?

Annotations already provide strong behavioral hints (readOnly, idempotent, non-destructive). The description adds no further behavioral details beyond stating it searches and returns codes, which is consistent. It does not contradict annotations.

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

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

The description is two sentences with no wasted words. It front-loads purpose, provides examples, and a use case. 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 4 parameters (1 required), no output schema, and rich annotations, the description fully informs the agent: what it does, when to use, and what it returns. No critical 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% with descriptions for all 4 parameters. The description adds general context but no per-parameter details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches UCUM codes for units of measure, explicitly mentions its use in health-IT systems (FHIR, LOINC), and gives concrete examples of returned codes (mg/dL, [in_i]). This distinguishes it from sibling tools like loinc or conditions.

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: 'normalizing lab result units or rendering measurements.' While it doesn't list alternatives or when not to use, the sibling context (e.g., loinc for lab codes) implies differentiation. The guidance is clear and actionable.

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

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

Description adds significant behavioral context beyond annotations: ownership enforcement, deactivation vs deletion, historical events staying available. Annotations (destructiveHint=false) 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?

Two sentences with no wasted words. Efficiently communicates purpose, constraints, and behavioral nuance.

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

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

For a simple mutation tool with one param, description covers purpose, usage, behavior, and side effects. No gaps given annotations and schema richness.

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

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

Single parameter 'id' is fully described in schema coverage (100%). Description does not add additional meaning beyond schema, so baseline score of 3.

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

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

Clearly states 'Cancel a subscription by id.' Specific verb (cancel/unsubscribe) and resource (subscription). Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement and that the row is deactivated, not deleted. Provides context on when to use (own subscriptions) and behavior, though no explicit alternative tool mentioned.

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 far beyond the annotations by explaining important behavioral nuances: the verdict list, the distinction between 'could_not_verify' (a failed check, not evidence) and 'unsupported' (no source covers it), the fast-path for SEC EDGAR financial claims, and the grounded pipeline for other claims. It also notes the citation/reasoning output, which is not present in the output schema.

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

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

The description is long, but the extra length is justified by the tool's complexity and the absence of an output schema. It is front-loaded with trigger phrases and purpose, then structured into routing, return semantics, and caller warnings. Some redundancy exists (multiple paraphrases for 'fact check'), but each section earns its place.

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

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

Despite having no output schema, the description fully explains what the tool returns: a verdict, the actual value with a pipeworx:// citation, and reasoning. It also covers error semantics ('could_not_verify' vs 'unsupported') and the two execution paths, making the tool's behavior sufficiently clear for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable meaning beyond the schema. It gives natural-language examples for 'claim', and for 'tolerance_pct' it explains that setting 1–2 is useful for hallucination detection where material errors must be refuted, which is more specific than the schema's default description.

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

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

The description clearly identifies the tool as a natural-language claim verification service with a specific verb+resource: 'validate claim' / 'fact check'. It distinguishes itself from sibling research tools by focusing on factual correctness checks that return verdicts, and even mentions replacing multi-step sequential calls.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for company-financial claims vs. any other factual claims, and states that the tool replaces 4–6 sequential calls, effectively directing the agent away from a slower alternative pipeline.

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