Drug Prices

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds valuable behavior beyond that: the default model (Llama-3.3-70b), the free tier, the cost implication of passing _apiKey ("you pay Anthropic directly"), and the external call to api.anthropic.com. This enriches the 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 main action is front-loaded in the first sentence, and each subsequent sentence earns its place: cost/model behavior, return format, and use cases. It is slightly dense — the cost point and return format could be tightened — but there is no fluff or redundancy beyond a minor BYO-key/pay overlap.

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

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

With no output schema present, the description correctly fills the gap by specifying the return shape (per-model score, confidence, signals, raw_response + combined view). It also covers cost, defaults, and use cases. Minor gaps remain: the meaning/orientation of the 0-100 score (higher = better visibility?) and failure behavior when anthropic is requested without _apiKey are not explained.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters with examples and format hints. The description adds only marginal enrichment — the concrete default model identity (Llama-3.3-70b) and the free-vs-paid cost distinction for models/_apiKey. This is a solid baseline with slight bonus, but the schema carries the heavy lifting.

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 and resources: "Probe one or more LLMs... and score visibility (0-100) per model." It names the subject (business/brand/product/topic), the action (probe + score), and the output shape, making it clearly distinguishable from Q&A siblings like ask_pipeworx and research tools like deep_research.

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

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

The final sentence gives concrete use cases ("AI-marketing audits, pre-launch brand checks, competitive monitoring"), and the second sentence provides operational guidance on model selection (default free model vs. BYO Anthropic key). However, it does not name alternative tools or state when not to use it, e.g., versus the sibling scan_competitor_ai_presence.

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 readOnly/openWorld/idempotent annotations, the description discloses routing behavior, argument filling, stable pipeworx:// citation URIs, and 'one fast call' performance. It does not mention failure modes or rate limits, but the additional behavioral context is meaningful.

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

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

The description is long but front-loaded with the most important guidance and organized into usage rules, examples, and escalation paths. Some redundancy exists between the trigger-phrase guidance and examples, but each section earns its place for such a broad default tool.

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

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

Even without an output schema, the description tells the agent what to expect (structured answer with citation URIs), which domains are covered, when to prefer alternatives, and provides concrete invocation examples. This is sufficiently complete for correct selection and use.

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

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

Schema coverage is 100%, and all parameters are documented as aliases of the same 'question' field. The description reinforces this with natural-language examples but does not add significant new semantic constraints beyond what the schema already provides.

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

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

The description states a clear purpose: route factual questions to one of 6,032 verified-source tools and return cited structured answers. It explicitly positions the tool as the default entry point over web search and distinguishes it from grounded and deep-research 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?

Gives explicit guidance: 'PREFER OVER WEB SEARCH', trigger phrases like 'what is' / 'look up' / 'current', concrete examples, and a hierarchy ('START HERE', 'Step up only when needed') with named alternatives ask_pipeworx_grounded and deep_research.

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

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

Beyond annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds context that no candidate is currently active, so it matches ask_pipeworx exactly today, and that it is a full working router with no fallback. It also explains the experimental nature and how outputs are used for merge decisions.

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 well-structured sentences: first establishes the beta identity and relationship to the stable router, second gives current-state status, third gives usage and boundary. No filler or redundancy; each sentence earns its place.

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

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

For a single-question router, the description covers key concerns: identical to ask_pipeworx, no active candidate, when to use, and comparison purpose. It references 'same response shape' to indicate output, though it doesn't detail the response structure; given no output schema and a sibling with known behavior, this is acceptable.

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 fully documents the single required 'question' parameter and all five aliases, with 100% schema coverage. The description adds no further parameter semantics, merely stating 'same arguments' as ask_pipeworx, so it does not exceed the baseline.

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

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

The description explicitly states the tool is a universal router, a beta variant of ask_pipeworx with the same 6,032 tools, arguments, and response shape. It clearly separates itself from the sibling ask_pipeworx by calling itself the experimental edge and the experimental edge.

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

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

Explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared against the stable router. It implies the alternative (ask_pipeworx for the stable version) is the alternative for non-experimental behavior, though it doesn't explicitly state the when-not-to-use condition.

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 the exact success return shape, the full refusal reason enum, and the grounded-only extraction behavior. It also surfaces the extra LLM call cost, which is not captured in annotations.

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

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

The description is dense but every clause earns its place: mode, routing behavior, return contract, refusal behavior, use cases, and cost trade-off. It is front-loaded with the most decision-relevant phrase, 'Hallucination-resistant answer mode for high-stakes reads.'

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 compensates fully by specifying both success and refusal JSON shapes, the refusal reason set, and the sourcing/evidence model. It also covers when to use it versus the sibling, making it complete for an agent to select 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 description coverage is 100%, with the question parameter and all aliases already documented, so the description does not need to repeat parameter details. It adds context about routing and argument filling, but no new syntax-level parameter semantics.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode that extracts answers using only tool-result content. It explicitly distinguishes itself from the sibling ask_pipeworx by adding grounded extraction and explicit refusal behavior.

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

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

It provides explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete high-stakes examples. It also says to prefer ask_pipeworx for casual lookups and discloses the extra LLM call cost.

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

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

Annotations already mark this as readOnly and idempotent, and the description adds meaningful behavioral context: the statutory 106% markup, the fact that the returned payment quarter and the source ASP data quarter differ by two quarters, and that the tool is keyless. This goes beyond the annotation safety profile to explain how the data behaves over time.

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

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

Four sentences, each earning its place: what it is, how to look up, domain context, return details including the critical two-quarter lag, and pointer to the alternative. The core definition is front-loaded and there is no filler or duplication of the 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?

With no output schema, the description correctly takes on the burden of explaining return contents (limit per dosage unit, in-force quarter, derived ASP quarter) and even flags why the two-quarter gap matters. It is complete for a read-only lookup tool, with only minor omissions like conflict handling when both hcpcs and drug are supplied, which the schema leaves open.

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 schema already documents drug, hcpcs, limit, and quarter including formats and defaults. The description reiterates the look-up options (J-code or drug name) but adds little new parameter-level meaning beyond the schema, mostly clarifying that the returned quarter and derivation quarter are distinct.

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: it 'Returns' the quarterly ASP payment limit for a provider-administered drug, and identifies the exact computation (106% of Average Sales Price). It explicitly differentiates from sibling nadac_price by framing this as the 'clinic/infusion benchmark' and retail as the alternative, so an agent can distinguish it without inspecting other 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 gives a clear when-to-use context ('clinic/infusion benchmark: oncology drugs, biologics, injectables and vaccines') and a direct when-not-to-use with an explicit alternative ('For retail pharmacy acquisition cost use nadac_price instead'). It does not enumerate every sibling relationship (e.g., nadac_history or drug_price_compare), but the key retail-vs-provider routing is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds non-obvious behavior: it returns pharmacy name/city/state/contract begin and termination dates, and it can act as a reverse lookup from pharmacy chain to covered entities.

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: the first defines the operation and reverse mode, the second states the return fields, and the third gives concrete questions it answers. No filler or duplication of schema details.

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

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

Combined with the fully described schema and annotations, the description is enough for an agent to select and call the tool correctly. It covers the two access patterns, return fields, and motivating use cases, and no output schema is needed because the return fields are named directly.

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 descriptions, so the baseline is 3. The description's references to 'covered entity' and 'pharmacy chain' reinforce the id340b and pharmacy parameters, but it doesn't add syntax or format details beyond the schema.

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

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

The description names a specific verb ('List') and resource, and immediately clarifies the two supported directions: covered entity → pharmacies and pharmacy chain → covered entities. This makes it easy to distinguish from sibling tools like b340_covered_entities even without opening the schema.

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

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

It gives concrete use cases ('how large a hospital 340B pharmacy network is', 'which chains a health center contracts with', 'how many 340B relationships a chain like Walgreens or CVS holds') that tell the agent when to invoke it. It stops short of explicitly contrasting it with sibling tools such as b340_covered_entities, so it loses the fifth point.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context (HRSA registration) and output field transparency, but does not mention behavior around pagination, the default exclusion of terminated entities, or open-world result variation. 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?

Three sentences each earn their place: the first defines scope, the second summarizes filters and outputs, and the third frames concrete use cases. The description is front-loaded with the core verb and resource, and contains no filler 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?

With no output schema, the description compensates by listing key returned fields (340B ID, start date, parent hospital, Medicare CCN, NPIs, contract pharmacy count) and answerable questions. It relies on the schema for defaults and limits, which is acceptable given the schema's richness; a short note about the active-by-default behavior would make it 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 description coverage is 100%, so every parameter already has detailed meaning in the input schema. The description briefly restates filtering by state, type, and name, but adds no syntax, defaults, or format details beyond what the schema provides. This meets the baseline but does not elevate it.

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 ('Find') and a well-scoped resource ('340B drug pricing program covered entities registered with HRSA'), then enumerates entity types and outputs such as 340B ID, registration start date, and NPI numbers. It clearly conveys what the tool does, though it does not explicitly differentiate itself from the sibling b340_contract_pharmacies beyond the phrase 'how many contract pharmacies each one uses.'

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 closing sentence provides clear context for when to use the tool: answering which providers can buy drugs at 340B ceiling prices in a state, whether a named hospital participates, and when it joined. There are no exclusions or explicit comparisons to alternative tools, but the intended use is not left to inference.

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

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

Annotations cover only the safety profile (readOnly/openWorld/idempotent/non-destructive), and the description adds far beyond that: BLOCKING short-circuit statuses (low_confidence_match, market_closed_or_inactive, market_expired_or_resolved), the resolver contract with match confidence scores, GDELT 429 fallback fields, illiquid_wide_spread flagging, and cancellation-rule settlement parsing. These are exactly the operational traits an agent needs to avoid misusing results (e.g. sizing on phantom matches).

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?

Purpose is front-loaded, but the body is an unusually dense wall of ALL-CAPS headers and enumerated classifier/fan-out/status lists. Much of this is useful given the absent output schema, yet the density and length exceed what most agents will parse, so structure is adequate but not economical.

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

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

With no output schema, the description carries the full return-shape burden and does so: result.market fields, result.analysis fields (model_probability/edge_pp/kelly_fraction_half), result.evidence keying, resolver contract fields, parent_event partition fields, and news fallback metadata are all documented. An agent can interpret responses without guessing.

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 genuine meaning: it explains WHY to prefer an undated slug (dated slugs stop resolving once settled because Polymarket de-indexes resolved markets) and ties fuzzy matches to the suggestions[]/market_match_alternatives[] re-query hints. The depth and include_raw semantics largely restate the schema, so it is not a full 5.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and enumerates the full pipeline (resolve → classify → fan out → evidence packet + model comparison). Sibling Polymarket tools (edges, arbitrage, fill_risk, kalshi_spread) are implicitly distinguished by the 'should I bet on X / what does the data say / is there edge' trigger framing, which reads as research rather than scanning or spread-monitoring.

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?

Trigger phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') give clear usage context, and the safety section explains when the tool effectively won't produce analyzable output. However, it never names an alternative sibling or states when NOT to use this tool (e.g. bulk edge-scanning belongs to polymarket_edges/arbitrage), so routing vs. alternatives is left to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by detailing exact behavioral guarantees: it never returns 0 for missing data, never lets YTD answer a quarterly question, never converts currency, and provides named statuses for each non-answer type. It also discloses the source (SEC EDGAR XBRL) and the deterministic single-read behavior. This extensively adds context beyond annotations, with 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 long but every sentence earns its place. It opens with a crisp statement of purpose, then systematically covers differentiators, guarantees, statuses, and source. It is front-loaded with the core scope and uses clear paragraph breaks (implied by the flow) to separate concerns. No filler or redundancy.

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

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

Given the tool's complexity (5 parameters, nested period object, no output schema), the description is exceptionally complete. It explains parameter semantics in depth, enumerates all possible non-answer statuses, describes the response content (us-gaap concept, accession, restatement trail, contract/derivation version), and even mentions the non-MCP endpoint. An agent has all necessary information to invoke it correctly.

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

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

While schema coverage is 100%, the description adds substantial meaning: it explains fiscal period anchoring to the filer's own year-end, the ambiguity handling for company names, the mapping of attributes to specific us-gaap concepts (e.g., net_income vs profit/loss), and the restatement default. It clarifies that 'basis' only supports consolidated and explains the significance of each enum value. This goes far beyond the 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?

The description states a specific purpose: typed, deterministic financial facts for a US public company for an explicitly named reporting period. It uses strong verbs and clearly distinguishes from siblings by contrasting with entity_profile and get_company_financials, which return the most recent figures. This differentiates the tool's role without ambiguity.

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: 'PREFER OVER entity_profile / get_company_financials whenever the period matters' and explains why those alternatives are unsuitable for specific periods. It also enumerates what the tool never does (e.g., never substitutes the latest period) and lists named statuses for non-answers, providing clear operational boundaries.

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 read-only/idempotent annotations, the description reveals important runtime behavior: it executes as one parallel call, pulls specific financial fields from SEC EDGAR/XBRL or FAERS data, handles off-calendar fiscal years, sorts results by the primary metric, and returns paired data with citation URIs. This is far more than the annotations alone provide.

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

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

The description is dense but every sentence earns its place: trigger phrases, selection guidance, type-specific data sources, output ordering, and citations. Important guidance is front-loaded with the natural-language triggers and the 'ALWAYS PREFER' instruction.

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

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

Despite lacking an output schema, the description tells the agent what data will come back, how results are ordered, what citations are included, and why this tool beats sequential lookups. An agent has enough information to select and invoke it correctly without needing further clarification.

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

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

Although the schema already covers both parameters at 100%, the description adds meaningful semantics: it explains what each type value retrieves, gives concrete ticker and drug examples, and clarifies that values must be 2–5 entities. This goes well beyond the schema's minimal descriptions.

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

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

The description opens with concrete user phrasings ('Compare X and Y' / 'X vs Y' / 'rank these companies') and then states the core operation: side-by-side comparison of 2–5 companies or drugs in one parallel call. It also distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear selection rule. It gives trigger examples, the entity types, the count range, and the value proposition ('Replaces 8–15 sequential lookups'), so an agent knows exactly when to invoke 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?

Well beyond the readOnly/openWorld/idempotent annotations, the description discloses auth requirements (free sign-in; thorough needs paid plan), latency (15-60s, up to ~90s for thorough), return packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), the never-invents guarantee on gaps[], contradictions[] on standard/thorough, hop semantics, guaranteed-resolvable citation_uri, and semantic excerpting behavior. No contradiction with annotations — openWorldHint is consistent with live structured sources even though it is not web search.

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 (~230 words) but every sentence earns its place for a tool of this complexity — front-loaded with the most critical operational constraint (account required + fallback) before the generative details. Minor redundancy exists where depth-mode behavior overlaps with the schema's depth description, but the length is justified by the wealth of non-obvious behavioral detail.

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

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

With no output schema, the description carries the full burden of explaining return values — and it does: findings packet, gaps[], contradictions[], hop field, citation_uri resolvability, and excerpting behavior. It also covers prerequisites (sign-in), edge cases (empty gaps for unsupported topics), latency, and the when-not-to-use path. For a 2-param tool with subtle failure modes, nothing an agent needs to invoke it correctly 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%, giving a baseline of 3 since the schema already documents both parameters. The description adds genuine value beyond the schema: it clarifies what makes a good question (broad/multi-part over structured data) and what yields empty gaps (news/colloquial topics), and it explains the practical behavioral difference between depth values (gap-recovery hop, lead-chasing, contradiction scan). This exceeds the baseline.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1569 STRUCTURED data sources... in ONE call.' It explicitly disambiguates from siblings with 'this is NOT open-web search' and does not merely restate the title 'Deep Research.' An agent can tell exactly what this tool does and how it differs from the 38 sibling tools.

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

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

Provides explicit when/when-not/alternative guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx (one LLM call, not many),' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It even names the auth-based fallback ('If you are not signed in, use ask_pipeworx instead') and gives worked example questions. Nothing is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds substantial value by disclosing the exact return shape: top-N relevant tools with names, descriptions, full input schemas and curated examples, and that results are ready to call without a second schema lookup. This is especially useful because no output schema is provided.

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

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

The description is front-loaded with the core purpose, followed by use cases, return value, and a clear first-step instruction. Each sentence earns its place, and the domain list is dense but directly relevant.

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 discovery tool with straightforward parameters, high schema coverage, and no output schema, the description fully compensates: it explains what the tool does, when to use it, and exactly what the response contains. Nothing materially needed by an agent 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%, and the schema already documents query, all aliases, and limit defaults/max. The description only restates that the input is a natural-language description of a data/task, adding no parameter-level 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 first sentence names a specific action and resource: 'Find tools by describing the data or task.' It also lists concrete domains and frames the tool as a discovery/meta tool, which distinguishes it from the many operational sibling tools and clarifies it is not itself a domain-specific search.

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

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

The description explicitly says when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to call it FIRST when many tools are available. It does not name specific alternative tools or give explicit exclusions, though 'not just one answer' hints at when a direct tool is more appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context beyond that: it 'States the vintage of each number and warns when they are measured months apart,' and explains that it 'Returns whichever benchmarks exist' — valuable caveats for a data-comparison tool.

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 bit dense but every sentence earns its place: the opening states the core action, the second gives use cases, the third explains the vintage warning, and the final sentences cover partial data and authentication. It is front-loaded with the most important information and contains 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?

Without an output schema, the description compensates by stating what is returned ('whichever benchmarks exist') and that vintage information is included. It covers the main caveats for a comparison tool. It does not mention error cases or units, but for a read-only lookup this is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3 even without additional explanation. The description mentions 'for one drug' and 'Keyless' but does not add new parameter semantics beyond the schema's own descriptions for 'drug' and 'ndc'. No extra detail about format or constraints is provided.

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

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

The description opens with a specific verb and resource: 'Put the two US drug price benchmarks side by side for one drug' and immediately defines the two benchmarks (NADAC and ASP limit). It clearly differentiates from siblings like nadac_price and asp_payment_limit by emphasizing the side-by-side comparison and the 'returns whichever benchmarks exist' behavior.

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

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

The description explicitly states when to use the tool: 'Use to see the spread between acquisition cost and reimbursement, or to check whether a drug is a retail or a clinic-administered product at all.' It does not name alternatives explicitly, but the positioning against individual benchmark tools is clear from the function and context.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds genuinely useful behavioral context: one parallel call, USPTO soft-fail behavior, FDA small-molecule expected-empty case, resolved:false + notes for private companies, and sources_used/sources_failed semantics. This goes well beyond what annotations provide, though it doesn't document rate limits or latency.

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 information-dense; the trigger examples are front-loaded, then the fan-out list, then return semantics. It earns its length by covering many data-source edge cases and expected failures. It could be tightened with bullets, but the content is purposeful and not padded.

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 broad fan-out and no output schema, the description covers inputs, resolution behavior, per-source quirks, and failure semantics well. The main gaps are missing names or numbers of sibling tools that would further disambiguate it from deep_research or compare_entities, and no explicit mention of typical latency or upper bound on sources.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully, including the interchangeability of type values and the accepted value shapes. The description reinforces the same semantics and adds the resolved_from/resolved_to nuance for name-based values, but its baseline is the schema doing the heavy lifting.

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

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

The description opens with concrete trigger phrases and a clear verb-object pair ('full cross-source profile of a US public company'). It names the resource and the fan-out sources, and explicitly contrasts with chaining single-pack lookups, which differentiates it from siblings like deep_research, compare_entities, and resolve_entity.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', gives accepted input shapes, and explains the empty-section semantics and private-company fallback. This gives clear when-to-use and when-not-to-fail guidance.

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

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

The explicit 'Delete' verb aligns with the annotations destructiveHint=true and readOnlyHint=false, and key-based deletion is consistent with idempotentHint=true. No contradiction. The description adds context beyond the flags by scoping the target to 'previously stored memory by key' and by noting the sensitive-data use case, though it does not describe edge-case behavior like deleting a missing key.

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

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

Three short sentences with the core action front-loaded, followed by usage triggers and sibling pairing. Every sentence earns its place; there is no filler or redundant restatement of the 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?

For a one-parameter delete action, the description covers purpose, usage conditions, sibling context, and destructive nature; annotations cover idempotency and mutation, and the schema covers the parameter with an example. Nothing material an agent needs to invoke the tool correctly 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% and the schema already documents key as 'Memory key to delete' with an example. The description merely restates the mechanism as 'by key,' adding no format, lifecycle, or edge-case semantics beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb ('Delete') with a specific resource ('previously stored memory') and the mechanism ('by key'). The description also names the paired sibling tools remember and recall, making the tool's role in the memory family unambiguous.

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

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

Gives three explicit trigger conditions: stale context, task complete, and clearing sensitive data previously saved by the agent. Names the related tools remember and recall as its pair, though it stops short of an explicit when-not-to-use statement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety/purity of the operation is established. The description adds valuable behavioral context: it fetches the page, extracts specific elements, and emits a single text blob ready for site-root deployment. It does not disclose edge cases (e.g., inaccessible URLs), but the annotation coverage lowers the burden.

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

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

The description is three tight sentences: purpose, process/output, and use cases. Every sentence earns its place, the core action is front-loaded, and the use-case list communicates practical value without drifting into irrelevant detail.

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

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

This is a simple tool with only two parameters, full schema coverage, and annotations covering safety and idempotence. The description explicitly states the output format and where to place the result, compensating for the absence of an output schema. An agent has everything needed to invoke it correctly for typical use cases.

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

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

Schema description coverage is 100%: url and max_links are both explained, including max_links' default (25) and maximum (50). The description adds no meaning beyond 'any URL' and does not mention max_links at all, so it stays at the baseline of 3 where the schema carries the parameter documentation.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly details the process (fetches page, extracts title/description/key links) and the exact output (single text blob in standard llms.txt markdown), making it easy to distinguish from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The 'Useful for:' section provides concrete scenarios for when to invoke this tool: indexing a client's site, drafting for one's own project, or auditing how an AI crawler sees a competitor. It does not explicitly name alternative tools or describe when not to use it, but the context is sufficiently 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?

The description goes far beyond the annotations by disclosing non-obvious behavioral traits: markets settle on Weather Company, not NWS; station is derived from settlement clause; forecast_prob uses an assumed normal distribution; edge_pp is gross; and it exposes a concrete measured result showing the market beat the forecast. These are exactly the kind of caveats an agent needs to interpret results correctly, and they are not visible in the read-only/open-world annotations.

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

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

The description is long but tightly packed with critical trading caveats. It is front-loaded with purpose and modes, then structured warnings (1-4), then a measured result, followed by edge-case handling. While not concise, the density is justified given the financial stakes and the need to prevent misuse; it could be slightly more scannable with headers, but overall each sentence carries weight.

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

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

With no output schema, the description must specify return values, and it does: LIVE mode returns the strike ladder with market_prob, forecast_prob, edge_pp, and the settlement clause; BACKTEST returns brier_market vs brier_forecast, settlement-vs-forecast basis, and a plain-English verdict. It also covers international and precipitation fallbacks, and the warning section covers all major edge cases. Nothing an agent needs to call the tool correctly 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%, but the description adds substantial meaning to each parameter: 'city' includes a default and fallback behavior (unmapped cities return known_cities[]), 'date' explains open/close timing, 'market_type' clarifies precipitation returns no forecast, 'backtest_days' explains the scoring methodology and max, and 'series_ticker' overrides city. This is a textbook example of enriching schema with operational context.

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

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

The description clearly states the tool's function: 'Prices Kalshi daily high-temperature markets against the NWS forecast...' and explicitly defines two modes (LIVE and BACKTEST) with distinct outputs. It differentiates itself from sibling tools by focusing on a niche weather-edge analysis, and the many specific details (station codes, edge_pp, brier scores) leave no doubt about its purpose.

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

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

The description provides explicit when-to-use guidance: 'LIVE (default)' vs 'BACKTEST (`backtest_days: N`)', and tells the user to run backtest before believing any edge. It also covers exclusions: international series return forecast_unavailable, precipitation is not priced, and it warns about using city-centre forecasts when stations are derived from settlement clauses. This is model-guidance beyond what any sibling alternative offers.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail by scoping to the caller's active subscriptions and enumerating the returned fields, which goes 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?

Two sentences carry all the essential information: what the tool lists, what it returns, and when to use it. The primary action is front-loaded and there is no redundant wording.

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

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

For a simple read-only list tool with one optional documented parameter and no output schema, the description is complete: it names the resource scope, the returned fields, and the use cases. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the single optional include_inactive parameter is already fully documented. The description does not add further parameter context, which matches the baseline of 3 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 names a specific verb and resource: 'List the caller's active subscriptions.' It also lists the exact return fields, making the operation concrete and clearly distinct from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly says when to use this tool: 'review what you're monitoring before adding more' and 'find an id to cancel.' It gives clear context, though it does not explicitly name sibling alternatives or state when not to use 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?

Annotations already mark the tool read-only, idempotent, open-world, and non-destructive, so the description correctly focuses on additional behavior: one row per published week, oldest-to-newest ordering, pricing unit, percentage change across the window, and 'Keyless'. This adds useful context beyond the annotations.

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

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

Three sentences, each earning its place: purpose/scope, usage signals, and return behavior. The most identifying information is front-loaded, and the final 'Keyless' note is compact and useful.

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 two-parameter read tool with no output schema, the description adequately covers input scope, intended use, return row structure, and ordering. It is complete enough to call correctly, though the exact meaning of 'percentage change across the window' is slightly ambiguous.

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

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

Schema description coverage is 100%, with both ndc and weeks clearly documented in the input schema. The description adds no new parameter-level meaning beyond restating 'one drug NDC' and weekly observations, so the baseline of 3 applies.

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

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

The description opens with 'Weekly price history for one drug NDC' — a specific verb and resource — and immediately clarifies it tracks NADAC pharmacy acquisition cost over time. It also names concrete use cases, making it easy to distinguish from a current-price tool like nadac_price.

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 usage signals: 'has the price of this generic gone up', 'shortage-driven price spikes', and 'generic erosion after a patent expiry'. It does not explicitly name alternatives or state when not to use it, but the use cases are specific enough for an agent to route correctly.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds further behavioral detail: it returns the most recent weekly price per NDC, includes pricing unit, brand/generic classification, and applicable week, and explains the literal matching behavior. Since there is no output schema, this return-format disclosure is especially valuable.

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

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

The description is dense but efficient: every clause earns its place, from the acquisition-cost definition to the literal-matching caveat to the sibling-tool pointer. The key limitation is front-loaded, and the terminal 'Keyless.' is a useful one-word guidance note.

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 read-only lookup tool with no output schema, the description is complete: it states what is returned, how matching works, how to disambiguate from related tools, and which parameter to use for historical dates. Nothing essential is missing 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 four parameters well, so the baseline is 3. The description adds extra meaning by clarifying how drug name matching behaves ('Eliquis' vs 'apixaban') and that `as_of` returns the pricing week in effect on that date, which goes beyond the schema text.

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

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

The description names the exact resource (NADAC acquisition cost), a specific verb ('look up'/'returns'), and clearly distinguishes this from related tools like asp_payment_limit. It also explains what the price is not, preventing confusion with retail prices, copays, or Medicare clinic payments.

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 the agent when to use this tool vs. alternatives, including 'for a drug given in a doctor's office or infusion centre see asp_payment_limit.' It also gives practical search guidance (literal name matching, try brand vs. generic name) and notes that the tool is keyless.

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, so the description carries the burden—and it delivers. It discloses the anonymous claim_token flow, the behavior of passing the token later to read resolution status, rate limiting to 5 per identifier per day, freedom from quota, and the digest/roadmap impact. No contradictions with annotations.

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

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

The description is a single dense paragraph, but every sentence earns its place: scope, exclusions, token workflow, rate limit, and content guidance are all non-redundant. Slight restructuring into bullets or shorter paragraphs would improve scannability, but it is already front-loaded and free of 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?

For a complex feedback tool with nested objects, enum types, and no output schema, the description is remarkably complete. It explains what the response token means, how to follow up, what to include in the message, what not to include, rate limits, and scope. An agent has everything needed to invoke it correctly and to route unrelated feedback elsewhere.

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 real value beyond the schema by explaining how to frame the message (in terms of Pipeworx tools/packs, not end-user prompts) and how claim_token is used round-trip. It does not relist parameter names, but it enriches the practical meaning of 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 opens with a precise verb and resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly differentiates this from the sibling ask_* tools by specifying this is a feedback channel for Pipeworx itself, not a data-querying tool.

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

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

It explicitly states when to use the tool (bug, feature/data_gap, praise) and when not to use it (issues with tools from other MCP servers, which should be filed with that server). This is the strongest possible usage guidance: concrete conditions, explicit exclusions, and a clear alternative action.

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

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

The annotations already mark this as readOnly, openWorld, idempotent, and non-destructive, and the description adds meaningful context beyond that: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This gives the agent a strong behavioral model of what it is querying.

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 compact and well-structured, front-loading the core purpose and then using a numbered list for use cases and a short final sentence for technical caveats. It contains minor redundancy around 'hot/current' language, but every sentence earns its place and the structure aids skimmability.

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 only one optional parameter, a fully descriptive schema, and strong annotations, the description covers what an agent needs to invoke the tool correctly: what it returns, the available windows, the caching behavior, and the privacy/aggregation properties. Since there is no output schema, the description's mention of 'top tools, top packs, and total call volume' provides sufficient return-value context.

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

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

The input schema already provides 100% coverage for the single 'window' parameter, including the enum values, the default, and guidance on short vs long windows. The tool description only restates the window options and does not add unique parameter semantics beyond what the schema already covers, so the baseline of 3 is appropriate.

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

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

The description opens with a specific, question-shaped statement — 'What other AI agents are calling on Pipeworx right now' — then names the concrete outputs: top tools, top packs, and total call volume. This clearly positions it as a meta/trending tool, distinct from related siblings like discover_tools, without needing to open the schema.

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 three explicit, practical use cases: discovering hot data sources, confirming a canonical tool, and checking alignment with broader agent demand. It does not state when not to use this tool or explicitly name an alternative, so it falls just short of the top bar, but the usage context 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 mark this as read-only, idempotent, and non-destructive. The description goes far beyond these by disclosing detailed fee modeling (taker fee rates, gas costs, fee_basis sources), the behavior when fees flip net_positive to false ('that is the correction, not a regression'), fill-check logic that can recommend not trading, and the partition filter that returns null under placeholder-heavy partitions. It also notes the tool does not double-count spread cost. This is exceptional transparency that anticipates potential misinterpretations.

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

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

Although the description is long, every section earns its place: it is organized into clearly labeled blocks (SEMANTIC ANCHOR, PARTITION FILTER, FEES, FILL CHECK) and front-loads the core purpose and invocation modes. There is no filler—each sentence adds a constraint, an example, or a caveat that an agent needs to invoke and interpret the tool correctly. Given the tool's inherent complexity, the density and structure are appropriate rather than verbose.

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

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

The tool has two optional parameters, no output schema, and high nominal complexity. The description compensates fully: it details the response shape (opportunities[] with fields, partition_check fields, fees components), explains edge calculations (gross, net, fee basis), covers edge cases (fill check, thin legs, placeholder filters), and references a companion tool for deeper analysis. An agent has everything needed to call it correctly and interpret results, even without an output schema.

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

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

While the schema descriptions for event and topic are already helpful (100% coverage), the tool description adds significant operational meaning: concrete example slugs ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), what the tool does with each value (walks child markets, runs partition checks, cross-event flattening), and the semantic/anchor filters (Jaccard similarity) that govern pairing. It even explains the difference between event and topic in terms of scope and output. This goes well beyond the schema's field-level comments.

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

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

The description opens with a specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the mechanism from sibling tools (e.g., polymarket_edges likely focuses on edge detection, not arbitrage) and enumerates three operational modes (trending_scan, event, topic) that map to distinct use cases. 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?

The description explicitly instructs when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. It even recommends event for specific markets and refers to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' It also explains the comparative advantage of cross-event mode, so an agent knows exactly when to choose this tool over alternatives.

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

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

With annotations already declaring readOnly/openWorld/idempotent, the description still adds substantial behavioral context: exact response segments, per-opportunity fields (edge_pp_net, kelly fractions, spreads), a 24h-move warning that an edge may already be priced in, the per-leg Kelly design quirk for partition arbs, diagnostics funnel counters, and 1h caching keyed on all knobs. 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 opening is front-loaded and every cluster of information is dense, but the description is a single wall-of-text paragraph with all-caps segments and parentheticals that are hard to scan. Some details (per-sport alpha values, 'gates relaxed Run 8' history) are irrelevant for tool selection or invocation and make it longer than needed.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It fully specifies the top-level by_segment structure, fed_candidates/fed_note, _diagnostics with funnel counters, the fields on every opportunity, and how all nine knobs affect results. An agent has enough to call the tool and interpret its output 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 meaning beyond the schema by grouping knobs into 'TRADEABLE-EDGE KNOBS,' explaining that min_liquidity/max_spread_pp drop unrealizable edges, clarifying that min_partition_leg_kelly applies to per-leg Kelly instead of parent-level, and noting that caching is keyed on all knobs. This is meaningful extra context without restating defaults.

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 opening sentence states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The intended use case is explicit ('what should I bet on today'), and the detailed model-family breakdown makes the tool's role unmistakable, distinguishing it clearly from arbitrage or tracker siblings even without naming them.

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

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

The description gives clear when-to-use context: agents discover daily opportunities without paging hundreds of markets. It also explains the tradeable-edge knobs and why Fed bets are excluded, but it never explicitly names alternative tools or states when to prefer them, leaving some routing to inference.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive. The description goes well beyond annotations by disclosing concrete behavioral traits: snapshots are written only on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage rather than intraday, and expired opportunities are those gone from the latest snapshot. No contradiction exists.

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 densely informative and well-structured into purpose, arguments, response shape, and limits. Every clause carries operational value, such as the sign convention for edge_pp_net, the median lifespan as a competition clock, and snapshot date gaps. This is not padding; it earns its length.

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

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

There is no output schema, so the description fully carries the burden of explaining return values. It defines tracked[], expired[], snapshot_dates[], explains trend and decay fields, clarifies the sign of edge_pp_net, and covers edge cases like gaps and TTL. For a two-parameter, read-only tool, this is complete enough for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the input schema already documents both days and window. The description adds only mild context: days is the lookback with default/max, and window refers to the polymarket_edges window family. This does not meaningfully exceed the schema's explanations, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots and explicitly frames the question it answers: 'how long has this edge existed and is it shrinking?' This is specific and distinguishes it from the sibling polymarket_edges tool, which presumably provides current edge data rather than historical tracking.

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 does not explicitly say 'use this instead of X', but it strongly implies when this tool is appropriate: for historical edge persistence and decay analysis across snapshot history, whereas polymarket_edges would be the current-edge sibling. It also sets expectations with limits like the 60-day TTL and snapshot-gap behavior, giving an agent enough context to select it correctly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read-only check. The description adds meaningful behavioral context: it walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), identifies thin legs, and names forced-directional-risk legs. It also explains the dominant loss mode (partial basket fills → unhedged directional position). It doesn't fully disclose rate-limit or data-freshness behavior, but it exceeds the annotation baseline.

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

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

The description is information-dense but formatted as a single long block of text. It front-loads the core purpose, then covers modes, parameters, and usage guidance. However, it could benefit from paragraph or bullet separation to improve scannability; the density makes it slightly harder to parse quickly.

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

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

Despite lacking an output schema, the description enumerates the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers prerequisites (market or event slug/URL), defaults, and failure semantics. Nothing essential is missing for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds value by explaining the interpretation of size_usd in each mode ('max spend on buys, target proceeds on sells' in single-market; 'settlement notional S (shares per leg; each share pays $1)' in basket), and clarifies that side defaults to auto from partition sum in basket mode. This goes beyond 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 a specific verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and distinguishes two modes (single-market vs basket). It explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) in its usage guidance, making it easy to select correctly.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable; partial fills create unhedged directional risk), which helps an agent decide between this and 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?

It adds rich behavioral detail beyond the readOnly/openWorld/idempotent hints: exact fee calculation methodology and versions, the limitation that spread-crossing cost is not modeled, clarification that temporal_alignment_unknown is not the sample aligns, and the rule that non-equivalent pairs are never suppressed. This directly changes how an agent would interpret the tool's answers.

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 with labeled sections, but it is extremely long, with multiple layers of fee detail, version numbers, and references to internal fleet batches. Every detail is informative, but token cost, and over-specification makes it harder for an agent to find the essential facts.

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

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

With no output schema, the description carries the full burden of explaining the response structure, flags, error cases, fee semantics, resolution comparison, skip counters, and the meaning of aligment fields. It arguably over-explains, ensuring an agent can safely invoke and interpret the tool in non-trivial situations.

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?

Even though parameter schema covers the fields, the description adds crucial semantics: alias and keyword resolution for topic, the difference between exact/alias vs phrase/token verdicts, and how explicit kalshi_event_ticker/polymarket_event_slug override the mapped topic. These behavioral details are not discoverable from the schema alone.

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

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

The first sentence explicitly names the tool's core behavior: cross-venue spread between Kalshi and Polymarket for the same resolving question. It then lays out two precisely defined modes and distinguishes itself by mentioning pre-mapped topics and explicit pairings.

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

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

The description clearly describes when to use topic mode vs explicit tickers, and explicitly warns that pre-mapped topics often are not tradeable and that 'phrase'/'token' matches are guesses. It recommends using resolution_audit/resolution_diff when a specific pair of legs is needed, but it does not name alternative sibling tools for similar arbitrage comparisons.

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 convey read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those: the omit-key listing mode, the scoping of memory to an identifier, and the relationship to remember/forget. It does not describe missing-key or empty-result behavior, but annotations lower the burden.

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

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

The description is three sentences with no filler. It front-loads the core behavior, then adds use-case context, then scoping and sibling-tool relationships. Every sentence contributes useful information.

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

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

For a simple optional-parameter lookup tool with read-only and idempotent annotations, the description is complete: it covers both invocation modes, gives realistic use examples, explains scoping, and points to related tools. No critical information is missing for an agent to call 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?

The input schema already fully documents the single optional key parameter, including the omit-to-list behavior, so schema coverage is 100%. The description reinforces this but adds little semantic detail beyond what the schema states, aside from concrete examples of what kind of values are stored.

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 leads with a crisp verb and object combination: 'Retrieve a value previously saved via remember, or list all saved keys.' It also names the sibling memory tools (remember/forget) and distinguishes this tool by its read-only lookup role.

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 clearly explains when to use the tool: to look up stored context without recomputing it. It also points to siblings by saying 'Pair with remember to save, forget to delete,' though it stops short of an explicit if-then exclusion like 'do not use for saving.'

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 establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context beyond that: return fields (source, citation_uri, raw payload), the mark_read side effect that affects subsequent calls, and polling suitability. No contradiction with annotations is present.

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

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

Four dense sentences, each earning its place: the opening states the core action, the second details return contents, the third covers filtering and mark_read semantics, and the fourth mentions polling and an alternative endpoint. It is front-loaded and contains 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?

Without an output schema, the description compensates by describing the return payload. It also covers filtering, mark_read behavior, polling, and alternative access. Minor omissions like limit defaults and unread_only details are already present in the schema, so the description is nearly complete for a read-oriented tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying ISO format for since, and explaining the consequence of mark_read ('so the next call only shows newer ones'). This exceeds what the schema descriptions alone provide.

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

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

The description uses a specific verb and resource ('Pull fired events from your subscription feed') and clarifies it returns recent alerts from the evaluator's persisted feed. It is conceptually distinct from siblings like list_subscriptions or recent_changes, but it never explicitly names or differentiates those alternative tools, so it falls short of 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 gives clear usage context: it says polling works fine, explains the mark_read pattern for advancing to newer events, and points to the GET registry.pipeworx.io/alerts.json endpoint as an alternative for scripts and dashboards. However, it does not explicitly contrast with sibling MCP tools, so it lacks full when-not-to-use guidance.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, yet the description still adds substantial context: the parallel fan-out to three sources, the GDELT→GNews fallback trigger conditions, and the USPTO PatentsView sunset with soft-fail behavior. It also discloses the return shape (changes[] grouped by source, total_changes, pipeworx:// 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?

Dense but every sentence earns its place: the leading query examples aid intent matching, the fan-out and fallback details set correct expectations, and the closing sentence routes to the sibling. It is front-loaded with user phrasing before the technical machinery, and the length is proportionate to 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 having no output schema, the description discloses the top-level return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs) so the agent knows what to expect. It covers sources, failure modes, since formats, and the sibling distinction — complete for a high-complexity, multi-source read tool. The only minor gap is that fields inside a changes[] item aren't enumerated.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents type, since, and value. The description adds only a usage preset ('Use "30d" or "1m" for typical monitoring') and restates the since shorthand formats; this is marginal value, not substantial 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?

States a specific verb and resource: 'change feed for a company in the last N days/weeks/months', backed by six natural-language query patterns. It distinguishes itself from the sibling entity_profile by explicit contrast (time-windowed changes vs static profile), and its multi-source scope (SEC/GDELT/GNews/USPTO) clearly separates it from recent_alerts.

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 names the alternative and the condition that selects it: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also prescribes a default window ('Use "30d" or "1m" for typical monitoring') and documents the fallback policy (GDELT preferred, GNews when rate-limited or 5xx).

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 read-only, idempotent, and non-destructive, but the description adds far more: ≤60s TTL caching, no push/webhook, empty-window error behavior, court category always empty with unsupported:true, and the honesty contract that releases with zero matched markets are returned rather than dropped. Match labels (true/likely/unclear) and matched_by are disclosed so callers can judge match quality.

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

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

The description is long but well-organized into labeled sections (CATEGORIES, MATCHING AND ITS HONESTY CONTRACT) and front-loads the core purpose. Some clauses are defensive or verbose, such as 'which is an accurate answer, not a bug', but they prevent false bug reports; the density is justified for a multi-source tool with several behavioral caveats.

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

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

Covers every behavioral edge case a caller needs: category semantics, empty-window error behavior, match confidence labels, timestamp conventions, and how to verify a match before trusting it. Even with an output schema present, the description adds return-value semantics (markets:[], resolves_on_this_release, matched_by, scheduled_at) and is complete for a complex tool.

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

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

Although the schema covers both parameters at 100%, the description adds rich semantic context: what each category means and which underlying source feeds it (fred_release_dates, fomc_calendar, pdufa_catalysts, federal-register), the hours cap and default, and the clock-time conventions for econ vs fed vs FDA/SEC dates. This transforms how an agent should set categories and hours.

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

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

States a specific verb and resource: JOIN of the official release calendar (econ, FOMC, FDA, SEC) against live Polymarket/Kalshi markets, returning scheduled releases in the next N hours and which live markets resolve on them. The 'POSITIONING tool, not a speed product' framing further distinguishes it from arbitrage/spread tools among the 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?

Explicitly says when not to use it ('do not use this to try to beat a release') and names concrete alternatives: call resolution_audit / resolution_diff before sizing anything. It also gives category-selection guidance and warns that a short window should be widened rather than assumed empty.

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 write semantics (readOnlyHint=false), idempotency, and non-destructiveness. The description adds genuinely new behavioral context beyond those annotations: the key-value store is 'scoped by your identifier' and retention is auth-dependent — persistent for authenticated users versus 24 hours for anonymous sessions. 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?

Five sentences, each carrying distinct information: purpose, when-to-use triggers, storage model, retention policy, and sibling routing. The opening is front-loaded with the verb and resource, though the final pairing clause ('forget to delete') reads slightly ambiguously despite the sibling literally being named 'forget'.

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 two-parameter tool with strong annotations and 100% schema coverage, the description covers purpose, usage triggers, memory scoping, and retention semantics. The only notable omission is any statement of the return value or confirmation behavior, which is minor given the absence of an output schema.

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

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

Schema description coverage is 100%, with both key and value fully described in the input schema including format examples. The description reinforces the key-value storage model but adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource — 'Save data the agent will need to reuse later' — and explicitly names the sibling operations ('Pair with recall to retrieve later, forget to delete'), so an agent can distinguish it from recall and forget without opening their schemas. Concrete examples (resolved ticker, target address, user preference, research subject) make the tool's job 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?

The description gives an explicit trigger condition — 'Use when you discover something worth carrying forward' — with concrete examples of what qualifies and the motivating rationale ('so you don't have to look it up again'). It routes to the related siblings (recall for retrieval, forget for deletion), though it stops short of stating explicit when-not conditions, leaving exclusion largely to inference.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: deterministic regex + vocabulary with no LLM pass, confidence:'low' for unusual clauses, reuse of bet_research's cancellation_rule detector, and the known gap of returning evidence_standard:'unspecified' rather than guessing. No contradiction with annotations.

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

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

The description is long but dense and front-loaded: the first sentence carries the core purpose and output fields, then input semantics, usage context, companion tool, and known gap follow in logical order. Every sentence contributes necessary information with 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?

With no output schema, the description carries the full burden of explaining what the agent gets back. It enumerates the extracted fields, the confidence fallback, the evidence_standard enum values, void_handling reuse, and the known limitation, making the tool fully callable without guessing.

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 still adds meaningful value: concrete examples for Polymarket slugs and Kalshi tickers, clarification that Kalshi event tickers fall back to a representative market, and why that fallback is safe. This goes well beyond the bare schema properties.

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

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

The description opens with a specific verb and resource: 'Extract the settlement clause of a single Polymarket or Kalshi market.' It enumerates exactly which attributes are extracted (source, clock time, precision, evidence standard, void handling) and explicitly distinguishes this tool from resolution_diff and polymarket_kalshi_spread, making sibling differentiation unambiguous.

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

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

It explicitly states when to use the tool: before treating a polymarket_kalshi_spread row as real arbitrage. It also names the companion tool resolution_diff for comparing two markets, and explains the Kalshi event-ticker fallback behavior, leaving no ambiguity about when or how to invoke 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=falsechers. The description adds important behavioral nuance beyond those hints: it explains the three-way equivalence outcome, the confidence threshold for comparing, and the specific-versus-generic source rule that prevents false conflicts. It also discloses that the tool internally runs resolution_audit, which is useful to set expectations.

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

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

The description is information-dense and front-loaded with the core purpose, but it is long and contains a lengthy parenthetical example and an extended heuristic explanation. Every point is relevant, but the phrasing is verbose and could be tightened or restructured with bullet-like separators. It earns its content but sacrifices conciseness.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: it explains the possible values of `equivalent` (true/false/unclear), mentions `differing_fields`, and instructs the caller to read `raw_clause` in unclear cases. It also covers the non-conflict heuristic. The only gap is not fully specifying the entire output structure or exact field locations, but the guidance is sufficient for the agent to decide when to call it.

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

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

Schema description coverage is 100% with both parameters described as 'First market to compare' and 'Second market to compare.' The description adds that they are markets on either Polymarket or Kalshi and that the tool runs resolution_audit on both sides, which slightly clarifies roles. However, it does not add meaningful detail beyond the schema's enum and nested-object definitions, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Field-by-field diff of TWO markets' settlement clauses.' It clearly states that the tool runs resolution_audit on both sides and compares source, settle time, precision, and evidence standard, which differentiates it from the sibling resolution_audit. The three-way return value is also summarized, leaving no ambiguity about the tool's core function.

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 usage context: 'Use this before sizing a polymarket_kalshi_spread pair as a real cross-venue arb, or standalone to sanity-check any two markets you suspect settle on different things.' This clearly states when to use the tool. It does not, however, explicitly name alternatives or say when not to use it, so it stops short of a full when/when-not guide.

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 the description adds substantial behavior beyond them: ambiguity handling ("asserts nothing and returns figi_candidates"), graceful degradation ("if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return"), explicit reporting of failures ("an identifier that could NOT be resolved is stated explicitly under `unresolved` rather than omitted"), source-labelled identifiers, and the internal cascade across endpoints. No contradiction with the read-only/idempotent annotations exists — the description is consistent with 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 definition is front-loaded with purpose and trigger examples, and nearly every sentence earns its place. However, it is a dense wall of prose: the "company" type is explained in a single ~200-word run-on sentence with deep parentheticals (FIGI candidates, bond behavior, ISIN mapping all nested inside), which makes parsing harder than necessary. Reformatting into bullets or shorter sentences would preserve all content while improving 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?

With no output schema, the description carries the return-value burden, and it largely delivers: it names response elements (figi_candidates for ambiguous matches, `unresolved` for failures, source labels, drug result shape of RxCUI + ingredient + brand + pipeworx citation). For a two-type, multi-endpoint resolver this is thorough. Minor gaps: no concrete example response object, and the drug path is given much less depth than the company path.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema's `value` description is already exemplary. The description adds meaning beyond it: ISIN as a fourth accepted input form (the schema lists only ticker, CIK, or name), the ISIN-to-LEI legal-entity resolution for non-US issuers, and the enrichment-degradation behavior that affects what the returned identifiers mean. It also expands the `type` enum values with concrete output semantics (CIK+ticker+LEI+FIGI vs. RxCUI+ingredient+brand).

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

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

The description opens with concrete natural-language triggers ("What's the ticker for…", "find the CIK for…") and then states a crisp verb+resource contract: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It enumerates two supported types (company, drug) with distinct output summaries, and differentiates itself from the sibling set by claiming "Use FIRST whenever you have a name but need an ID," which separates it from research-oriented tools like entity_profile and compare_entities.

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

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

The description gives an explicit trigger condition — "Use FIRST whenever you have a name but need an ID" — and even states what it replaces ("replaces 2-3 manual lookups"). The input-format rule ("Pass the ENTITY NAME ONLY… never the question's full noun phrase") is highly actionable guidance. However, it never names sibling alternatives or provides when-not-to-use conditions, so it stops short of full exclusion guidance.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density per entity. It does not mention cost/rate-limit implications of multi-probe execution, but the core behavior is 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?

Three sentences with no filler. The first sentence states the core action, the second explains the mechanism, and the third provides a concrete use case plus output shape. Every sentence earns its place and the key differentiator is front-loaded.

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

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

With no output schema, the description appropriately explains the return value: a ranked list with score, confidence, and signal density per entity. It covers the main intended scenario and behavior. Minor gaps remain around error cases, cost/rate-limit expectations for multi-probe execution, and explicit alternative guidance, but the description is largely complete 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?

Schema coverage is 100%, so the schema already documents all four parameters and their semantics. The description adds no new parameter-level detail beyond what the schema provides, such as the role of the first entity or the optional Anthropic key. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

The description uses a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It further distinguishes this tool from the single-entity ai_visibility_check by stating that it probes each entity, ranks by score, and surfaces which entity is most/least recognized. The purpose is unambiguous and clearly separated from sibling tools.

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

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

The description gives a concrete use case: competitive AI-marketing audits, with the example 'does Claude know about us as well as our competitors?'. It also names ai_visibility_check as the underlying probe mechanism, implying when this tool is the multi-entity counterpart. It does not explicitly state when not to use it versus compare_entities or other siblings, but the context is clear enough for an agent to route appropriately.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: it is a composite fan-out call across two external services, partial failures degrade gracefully via sources_failed, and bundlephobia's first measurement on a new version can take 5-30s. The latency warning and timeout behavior are exactly the kind of operational context an agent needs before invoking.

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

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

Four dense sentences, each earning its place: purpose, usage triggers, scope/return shape, and failure/latency behavior. The core purpose is front-loaded. It is slightly run-on in the returns enumeration, but with no output schema available, listing the summary fields is justified rather than wasteful.

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

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

For a composite tool with no output schema, the description is remarkably complete: it specifies sources, the summary block's fields, per-advisory detail and links, the NPM-only scope, latency behavior, and partial-failure degradation. Nothing an agent needs to decide whether and how to call it 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 description coverage is 100%, so the baseline is 3 — both package and version are already documented with examples ('@types/node', '18.3.1'). The description adds ecosystem context (npm-only) and reveals that version interacts with the is_latest output field, but it does not materially deepen parameter-level semantics beyond the schema.

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

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

The description states a precise job — 'Composite "should I add this npm package to my project" check in ONE call' — and names the data sources (deps.dev, bundlephobia) and exact data points (license, advisories, bundle size, dependency count, ESM/tree-shake support). It is clearly distinguishable from sibling research tools like validate_claim, compare_entities, and resolve_entity, none of which evaluate npm packages.

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

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

Gives explicit trigger phrases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a concrete exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. An agent gets both when-to-use and when-not-to-use with a routed alternative.

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 carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower, and the description adds genuinely non-obvious behavior: the 200K-char cap with truncation flagged, BGE-base-en embeddings with cosine over 500-char overlapping windows, and offsets enabling verbatim-quote verification. It stops short of a 5 only because how the truncation flag is represented and no-match behavior are left unspecified.

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

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

Four sentences with zero waste: the core operation, the when-and-why, the companion-tool workflow, and implementation constraints each occupy one sentence. The purpose is front-loaded in the first sentence, and no sentence repeats what annotations or schema already provide.

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 correctly carries the burden of explaining return shape — top-N passages with character offsets and similarity scores — and adds windowing mechanics and truncation behavior. For a simple 3-parameter tool with full schema coverage, only edge-case behavior (no matches, exact truncation-flag representation) is missing, which is minor.

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% — text, query, and limit each have descriptions with defaults, ranges, and examples. The description adds only marginal context (what counts as a fetched record, why the 200K cap and windowing matter) without materially extending parameter semantics, so the high-coverage baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource — 'Semantic search INSIDE a fetched record' — and immediately distinguishes itself from fetching tools by requiring 'the text you already pulled.' It names the sibling ask_pipeworx_grounded and specifies its exact output (top-N passages with character offsets and similarity scores), so an agent can tell it apart without opening the schema.

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

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

Explicit when-to-use guidance is present: 'Use when the record is too big to cram into the prompt,' with the reasoning that search_within saves context and returns only the passages that matter. It also routes around a specific sibling, describing the fetch-then-ground workflow with ask_pipeworx_grounded rather than searching the whole document.

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=false, idempotentHint=true, destructiveHint=false), the description discloses auth needs, account-type persistence limits, an SMS phone-verification prerequisite, and a 10/day rate cap. No contradiction with annotations; it enriches them with concrete operational constraints.

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

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

The first sentence carries the core purpose, and each following sentence adds operational detail (account requirement, per-type params, delivery rules). It is dense but not bloated, with only mild redundancy against the schema's parameter descriptions and a 'Supported types' list that omits two of the five enum values.

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?

This is a high-complexity tool — five subscription types, three delivery channels, no output schema — and the description covers the essential return value, preconditions, and delivery constraints. Remaining gaps (behavior for patent_grant/clinical_trial, duplicate-subscription behavior) are minor because the schema documents all parameters and the idempotentHint annotation signals retry safety.

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% — the schema already documents all three parameters, including type-specific filter shapes and webhook signing behavior. The description adds interpretive value on top, e.g. items:['5.02'] means officer change and concrete delivery examples, earning one point above the baseline 3.

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

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

States a specific verb and resource ('Create a proactive monitoring subscription to a live-data event stream') and names the returned artifact ('Returns the new subscription id'). The creation focus clearly separates it from lifecycle siblings list_subscriptions and unsubscribe, and from recent_alerts which consumes the feed.

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

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

Gives clear context for use: proactive monitoring of live data, plus a hard precondition ('Requires a Pipeworx OAuth account — anonymous + BYO cannot persist subscriptions'). It also routes feed consumption to the sibling recent_alerts and the public URL, but never explicitly states when not to subscribe or contrasts with list_subscriptions/unsubscribe.

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, which covers the safety profile. The description adds valuable context beyond annotations by explaining the tool returns category-bucketed examples derived from the live catalog, includes exact tool and argument shapes, and requires no arguments for a full spread. There is no contradiction with annotations.

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

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

The description is longer than average but every component serves a purpose: common user phrasings, the return format, the tool's role, parameter usage, and when to call it first. The natural language examples at the start and the explicit 'Use this FIRST' directive are front-loaded and impactful. Slight redundancy in listing example topics that appear again in the schema prevents a 5.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what the tool returns, how to invoke it, how to scope it, and when to use it. It even names the meta-tools it teaches, so an agent would have no difficulty calling it correctly or interpreting its purpose.

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

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

The schema already documents the single optional topic parameter with a complete description and examples, so baseline is 3. The description adds semantic nuance by framing the parameter as 'focus' with domain examples and clarifying that omitting it yields a cross-category spread. This meaningfully enriches the schema definition.

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 precisely identifies the tool as the onboarding entry point for a newly connected agent, explaining it returns category-bucketed example questions across domains and the exact tool and argument shape to answer them. It clearly distinguishes itself from sibling tools like discover_tools by focusing on 'what can I ask' rather than generic discovery, and even names specific meta-tools it teaches.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you,' giving a clear condition for when to invoke it. It also explains how to narrow the scope via an optional topic, but it does not explicitly name sibling alternatives or when to choose them, so it falls just short of a 5.

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

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

Discloses critical behavioral traits beyond annotations: ownership enforcement, soft-delete behavior ('deactivated not deleted'), and the consequence that historical events remain available via recent_alerts. This adds real context beyond the readOnlyHint/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?

Two sentences, front-loaded with the action, and no filler. The ownership constraint and deactivation detail each earn their place without bloating the definition.

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

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

For a single-parameter mutation tool with annotations covering safety, the description is fully sufficient. It covers prerequisites, side effects, and downstream visibility of historical data, leaving nothing essential missing.

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

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

The input schema already fully describes the single parameter, including its type and origin ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter-level meaning, so the baseline 3 applies.

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

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

The description leads with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe and list_subscriptions by naming the action of cancellation, and further clarifies the scope with ownership enforcement.

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

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

The description provides clear context for use: you must have a subscription id, and you can only cancel your own subscriptions. It does not explicitly name alternatives, but the use case is unambiguous and no exclusions are 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 readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to repeat safety. It adds real behavioral value by explaining that could_not_verify means the check did not happen, carries verification_error{stage,detail}, and must not be presented as evidence. It also mentions performance characteristics (replaces 4–6 sequential calls) and exact percent-delta math, which are meaningful beyond the structured annotations.

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

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

The description is dense but front-loaded with trigger phrases and a clear purpose statement. The later parts about verdict definitions and the 'IMPORTANT for callers' note are useful but could be slightly tightened; overall every sentence earns its place.

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

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

For a claim-verification tool with no output schema, the description adequately explains what returns: a verdict enum, the actual value with a pipeworx:// citation, and reasoning. It also explains the failure mode (could_not_verify vs unsupported). It lacks exhaustive detail on the grounded pipeline's source routing, but that is internal behavior an agent doesn't strictly need to 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 schema already covers 100% of both parameters with useful descriptions and examples. The description adds context about tolerance_pct's effect on grading and the default cap of 5, which reinforces but doesn't fundamentally extend the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with explicit natural-language trigger phrases and identifies the tool's core action: verifying the truth of a claim against authoritative sources. It also distinguishes the two internal paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for any other factual claim), which separates it from siblings like resolve_entity or ask_pipeworx_grounded.

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

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

It explicitly says to use whenever the agent needs to check whether something a user said is factually correct, and it names the exception path: company-financial claims go through the SEC EDGAR + XBRL fast path, while any other factual claim falls through to the grounded pipeline. It also tells callers what the verdicts mean and which verdict should not be shown as evidence.

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