Inspire Hep

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

Annotations already declare safe behaviors (readOnly, openWorld, idempotent, non-destructive), lowering the description's burden. The description adds meaningful context beyond annotations: probing multiple LLMs, free default model, BYO-key cost transfer for Anthropic, and the per-model response structure. It does not contradict annotations and provides useful operational details like cost and return format.

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 zero fluff. The first sentence states the core action and output; the second covers configuration and cost; the third lists use cases. Critical information is front-loaded, and each sentence contributes unique value without redundancy.

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

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

For a tool with 4 parameters, 1 required, and no output schema, the description is highly complete. It covers the return shape (per-model {score, confidence, signals, raw_response} + combined view), model options, key requirement, and applicability. The annotations further fill the safety profile, making this a well-rounded contextual package.

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 significant value: it clarifies the dependency between 'models' and '_apiKey' (requiring the key only when 'anthropic' is included), explains the free default model, and notes that '_apiKey' is passed straight through. These details go beyond the schema's field descriptions, enhancing the agent's understanding.

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

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

The description opens with a specific verb 'Probe' and clearly identifies the resource (LLMs) and the task: scoring visibility 0-100 for a business/brand/product/topic. It further distinguishes this tool from siblings like ask_pipeworx or scan_competitor_ai_presence by explicitly stating its use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). The inclusion of default model and return structure adds precision.

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 use cases ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') which indicate when to apply the tool. It also explains configuration choices (default Workers AI vs. passing _apiKey for Anthropic) and costing implications. However, it does not explicitly name sibling tools to avoid (e.g., ask_pipeworx for internal queries) or state when not to use it, so it narrowly misses 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description adds meaningful context: it fills arguments, returns stable citation URIs, works on every tier, and makes one fast call. It also describes routing behavior across live news and -news-feeds packs. No contradictions with annotations.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and each section provides value: use cases, examples, alternatives, and scope. It is somewhat verbose, but the detail is justified for a tool with no output schema and many sibling tools.

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 routing tool with no output schema, the description is remarkably complete: it explains the question scope, the nature of the sources, the output format (structured answer with citations), tier compatibility, and how it relates to alternative tools. It gives enough context for an agent to select and invoke it correctly.

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

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

Input schema covers 100% of parameters, including all aliases for the 'question' field. The description adds examples and clarifies the natural-language input, but it does not add semantic detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states this tool routes questions to one of 5,354 tools across 1,395 verified sources and returns structured answers with pipeworx:// citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, 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 provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and exactly when to step up to ask_pipeworx_grounded or deep_research. It also covers breaking-news routing and acknowledges that web search could answer some questions but this tool is preferred.

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

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

The description adds valuable context beyond the annotations: it is a beta, candidate improvements are only active when under test, no candidate is currently active, and it currently matches ask_pipeworx exactly. This helps an agent understand the experimental nature and current behavior without contradicting the read-only, idempotent 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 fairly concise and front-loaded with the key phrase 'Beta version of ask_pipeworx.' Each sentence contributes useful information, though the specific retirement date ('2026-07-26') is an extraneous detail that slightly reduces 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?

Given the simple input schema and the annotations covering safety, the description sufficiently explains the beta nature, current no-active-candidate state, usage, and relationship to the stable router. It mentions the same response shape, which partially compensates for the absence of an output schema. It is complete enough for an agent to decide whether to invoke this experimental variant.

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 all six parameters with 100% coverage, so the baseline is 3. The description only says 'same arguments as ask_pipeworx' and does not add any semantic detail beyond what the schema provides.

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

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

The description clearly identifies ask_pipeworx_beta as a beta version of ask_pipeworx, a universal router with the same 5,354 tools, arguments, and response shape. It distinguishes itself from the stable sibling by mentioning candidate routing improvements, but it relies on the reader already knowing what ask_pipeworx does, so it is not fully self-contained.

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 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear when-to-use context. It names ask_pipeworx as the stable alternative, but it does not explicitly state when NOT to use this beta version, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the exact refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the return format with verbatim evidence and confidence, and the cost overhead of one extra LLM call. These are critical behavioral traits that the annotations do not cover, and the description adds them without contradiction.

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

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

The description is dense but logically structured: it starts with the primary purpose, then explains the routing and extraction mechanism, details the return/refusal format, and ends with usage guidance and cost tradeoff. It is longer than average but every sentence earns its place, though a slight tightening would be possible without losing value.

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

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

Despite having no output schema, the description fully compensates by specifying the return shape ({answer, evidence, confidence, ...}) and all refusal reasons. It also covers routing, tool selection breadth, and when to prefer this over the sibling. For a complex tool with high-stakes use cases, the description is entirely self-sufficient for an agent to select and invoke it correctly.

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

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

The schema already provides 100% coverage for all six parameters, clearly defining them as aliases for the 'question' field and noting natural language input. The description simply refers to asking a question, adding no new meaning beyond what the schema already conveys. Thus, with full schema 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 specifics the tool as a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers only from tool results, with explicit refusal on insufficient data. It clearly differentiates from the sibling ask_pipeworx by stating it's for 'high-stakes reads' that will be 'quoted, cited, or acted on', making the purpose unambiguous and distinct.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and when-not: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. It also names the alternative (ask_pipeworx), satisfying both usage clarity and alternative comparison.

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, covering the safety profile. The description adds the context that record_id is an INSPIRE ID but discloses no additional behavioral traits such as rate limits or response format.

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 front-loaded, conveying the core function in a single short phrase without any unnecessary words.

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

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

The description is minimal and lacks context about when to use this tool over authors_search, nor does it mention expected output or limitations. Even though an output schema exists, the absence of usage guidance leaves the description incomplete for an agent.

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

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

The schema provides no description for record_id, only its type and requirement. The description clarifies that the ID is an INSPIRE ID, which is crucial for correct usage. However, no further semantic details are 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 'Author record by INSPIRE id' clearly indicates the tool retrieves an author record identified by an INSPIRE ID. Although it lacks an explicit verb like 'get' or 'fetch', the intent is unambiguous and sufficiently distinguishes it from sibling search 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?

No guidance is provided on when to use this tool versus alternatives like authors_search. The description does not mention whether it is for exact ID lookups or how it compares to searching by name.

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, open-world, idempotent, and non-destructive behavior. The description adds no extra context such as result format, pagination, or query semantics. Since annotations carry the behavior disclosure, this is neutral rather than insufficient, but no additional value 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 a single, direct sentence with no wasted words. It is perfectly concise and front-loaded, delivering the core function immediately.

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 the tool's simplicity and strong annotations, the description fails to explain what 'query' accepts or what 'size' controls. With 0% schema description coverage and no parameter details in the description, the agent lacks necessary invocation context. The output schema existence doesn't compensate for this gap.

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 0%, and the description 'Search authors' gives no meaning to the 'query' or 'size' parameters. Unlike cases where partial parameter info is listed, here there is zero compensation. The examples in the schema belong to structured data, not the description, so the agent gets no parameter guidance.

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 'Search authors' clearly states the action (search) and the target resource (authors), which distinguishes it from sibling tools like institutions_search or conferences_search. However, it doesn't explicitly differentiate it from more generic tools like 'search' or 'author', and the scope of 'authors' is left vague.

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 offers no guidance on when to use this tool versus alternatives. It doesn't mention whether to prefer it over generic search, or what types of queries are appropriate. The sole sentence implies usage but lacks explicit context or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond that, disclosing detailed behavioral traits: resolver contract with match confidence and alternatives, parent-event extraction, news fallback behavior, low-confidence short-circuit statuses, closed/dead market handling, wide-spread illiquidity flags, and cancellation-rule parsing (including refund_50_50 pure-rules loss). This is extensive behavioral transparency beyond the annotations.

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

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

The description is long but well-structured into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is front-loaded with the core purpose and usage. Every section adds necessary context for a complex research tool with many edge cases; no filler. It earns a 4 because, while detailed, it remains organized and purposeful.

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

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

With no output schema, the description fully compensates by detailing response shapes (result.market, result.analysis, result.evidence, result.parent_event), status outcomes (low_confidence_match, market_closed_or_inactive), and blocking conditions. It also covers safety guidance and cancellation-rule risk, making it complete for an agent to trust and interpret results. The sibling tool context further clarifies its niche.

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% for all three parameters (market, depth, include_raw), including defaults and accepted formats. The description adds examples and ties parameters to fan-out behavior, but the schema already documents the key semantics. Baseline 3 is appropriate since the schema does the heavy lifting and the description doesn't significantly augment parameter-level meaning.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the workflow (resolve market, classify, fan out, return evidence packet) and explicitly lists user intents ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different tasks.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete examples of when to inspect certain fields (e.g., resolver contract, cancellation rule) before acting. However, it doesn't explicitly mention when NOT to use this tool or name alternative sibling tools for other use cases, so it's clear but not exhaustive.

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 (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral detail: specific data pulled (10-K financials, FAERS counts, FDA approvals, trials), handling of off-calendar fiscal years, sorting by primary metric, and the return of citation URIs. 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 longer than typical but every sentence adds value, covering purpose, usage triggers, data specifics, and output. It is front-loaded with the core purpose and trigger phrases, making it effective despite its length.

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

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

Given the complexity of comparing multiple entities and the absence of an output schema, the description adequately explains return values (paired data + citation URIs) and key behaviors (sorted results, data sources). It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the schema already describes both parameters. The description adds meaning by specifying data sources per type, what metrics are pulled, and the sorting behavior, going beyond the schema's basic enum and array 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 ('compare') and resource ('companies or drugs'), with explicit trigger phrases like 'Compare X and Y' and 'which is bigger'. It distinguishes itself from sequential lookups and sibling tools by emphasizing parallel comparison.

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

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

Provides explicit when-to-use context: trigger phrases for comparisons, range of 2-5 entities, and an explicit preference over sequential single-pack lookups. It also differentiates between company and drug types and their data sources.

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

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

Annotations already cover the tool's safety profile (readOnlyHint, idempotentHint, destructiveHint), but the description adds no behavioral context beyond the verb. It doesn't explain query syntax, result limits, or pagination, offering no additional transparency.

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

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

The description is a single concise sentence with no redundant information. However, it is under-specified; while it earns its place by stating the core action, it lacks the detail expected for a tool with multiple parameters and alternatives.

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 an output schema and safety annotations, the description is incomplete for a search tool. It doesn't clarify what types of conference searches are supported, how to structure queries, or the effect of the size parameter. This is insufficient given the many similar sibling tools.

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

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

Schema description coverage is 0%, and the description does not explain the 'query' or 'size' parameters at all. The only hints come from schema examples, which is insufficient. The description fails to compensate for the missing 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 'Search conferences.' clearly identifies the tool's purpose with a specific verb and resource. It is self-explanatory, though it doesn't explicitly distinguish from sibling tools like authors_search or institutions_search, relying on the tool name for distinction.

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

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

The description provides no guidance on when to use this tool over alternatives. There are no context signals, exclusions, or prerequisites mentioned, which is a significant gap given the wide array of sibling search tools.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses account requirements and paid-plan limitations, exact return packet structure (evidence, confidence, source, citation), gaps[] behavior that never invents facts, contradictions[], hop fields, citation_uri semantics, semantic excerpting, and expected latency. No contradiction with the annotations.

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

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

The description is long but every sentence packs unique operational value: account prerequisites, scope, tool comparisons, depth semantics, return format, and latency. It is well-structured with clear colons and semicolons, and although front-loading could be slightly improved, there is zero wasted text.

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

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

Despite having no output schema, the description fully documents return values, gaps[] and contradictions[] behavior, citation formats, hop fields, and timing. It also covers prerequisites and appropriate alternatives for edge cases, making it complete for a complex research 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?

Input schema already provides 100% parameter descriptions, so the baseline is 3, but the description adds meaningful usage context: it explains that 'question' can be broad/multi-part and that depth values affect iteration and gap recovery. It also adds operational specifics like the paid requirement for 'thorough' and latency expectations per depth, going beyond the schema's enum 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 and resource: it performs grounded multi-source research across Pipeworx's 1,395 structured data sources in one call, decomposing questions into facets and routing to 5,354 tools in parallel. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its unique purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, while single lookups should use ask_pipeworx. It also warns that breaking or colloquial current-news topics should prefer ask_pipeworx because deep_research would return mostly empty gaps. Depth-specific iteration behavior and account-tier requirements further clarify when to use which mode.

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

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

While annotations already indicate read-only/idempotent behavior, the description adds valuable return-format details: returns top-N tools with names, descriptions, full input schemas, and curated examples, ready to call without a second lookup. This goes beyond annotations and informs the agent of what to expect.

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 few sentences long and front-loaded with the purpose. The long domain list is arguably necessary to convey scope, but it could be slightly more compact without losing meaning.

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

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

With no output schema, the description compensates by explaining the return format ('top-N ... with names, descriptions, and full input schemas'). It also covers usage scenarios. Minor gaps: doesn't specify how relevance is ranked, but this is not critical for a discovery tool.

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

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

Schema coverage is 100% with each parameter described, including aliases for query. The description adds little beyond the schema—just rephrases 'describing the data or task'—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 clearly states the tool's function: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by focusing on tool discovery rather than data retrieval, and the enumerated domain list (SEC filings, FDA drugs, etc.) gives concrete scope.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available...' This tells the agent when to invoke it and positions it as a first-step discovery tool, implicitly against directly calling data tools.

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

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

Beyond the read-only/idempotent annotations, the description discloses detailed behavior: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; limits recent_filings to 5; soft-fails patents due to USPTO API sunset; uses GDELT→GNews fallback. This adds significant behavioral context without contradicting annotations.

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

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

The description is dense but efficient, front-loading examples and usage preference. It's longer than average but every sentence contributes value (sources, fields, fallbacks, constraints), with minimal redundancy. Structure is coherent and scannable.

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

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

With no output schema, the description compensates by enumerating all returned components and details: cik + company_name, recent_filings (up to 5 with URIs), fundamentals fields and sort order, patents status, news fallback, LEI. This gives a complete picture of what the agent can expect.

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 description's input guidance mirrors the schema exactly (ticker or zero-padded CIK, names not supported, use resolve_entity). No new parameter semantics are added beyond the schema, so baseline 3 is appropriate.

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

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

Description explicitly states it produces a 'full cross-source profile of a US public company in ONE parallel call' with concrete examples. It distinguishes itself from alternative approaches by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is requested.

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

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

Provides explicit usage guidance: prefer over chaining single-pack lookups for holistic views, and instructs to use resolve_entity first when only a name is available, since names are not supported. This clearly delineates when to use the tool vs alternatives.

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

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

Annotations already declare destructiveHint=true, but the description adds context by clarifying it deletes a stored memory and can be used to clear sensitive data. It does not contradict the annotations and provides some behavioral context beyond the safety hints.

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

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

The description is two sentences, front-loaded with the action, and includes use cases and sibling references. Every sentence serves a purpose with 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 single-parameter destructive tool with annotations and schema coverage, the description covers what it does, when to use it, and how it relates to sibling tools. No critical information is missing.

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

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

The input schema already describes 'key' as 'Memory key to delete' with 100% coverage. The description only reiterates 'by key' without adding new details, so it meets the baseline for schema-covered parameters without adding extra meaning.

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

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

The description explicitly states 'Delete a previously stored memory by key,' which is a specific verb+resource combination. It also distinguishes this tool from siblings like 'remember' and 'recall' by describing its complementary 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?

The description provides clear usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also tells the agent to pair it with 'remember and recall,' offering practical guidance on tool relationships.

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 covering readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds useful process details: fetches the page, extracts title/description/key links, and emits standard markdown format. It also clarifies output distribution. 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 three sentences, front-loaded with the core purpose and output, then enriched with practical use cases. No redundant or extraneous information; every sentence contributes value.

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

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

For a simple fetch-and-format tool, the description covers purpose, process, output format, and use cases. There is no output schema, so explicitly noting the output is a text blob ready to drop at site-root/llms.txt is important and provided. Minor omissions like error handling or URL validation are acceptable for this simplicity level.

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 description coverage is 100% for both parameters, so the description doesn't need to repeat parameter details. It reinforces that URL is the site to summarize but adds no new 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 uses a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states what the tool does—fetch, extract, and emit—and is distinct from siblings like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description lists concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing clear context. It does not explicitly name alternatives or when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral context beyond that, such as match behavior, result ordering, or scoping, but it does not contradict annotations.

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

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

The description is a single sentence, making it concise but extremely sparse. It is essentially a restatement of the tool title, lacking any structural elements such as examples, caveats, or emphasized key details to aid an agent.

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 presence of sibling search tools, the description is insufficient to help an agent determine when to select this tool. The output schema may cover return values, but the tool's scope, expected input format, and behavior remain under-specified.

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 0%, and the description does not explain the 'query' or 'size' parameters. While the names are somewhat self-explanatory, the description fails to compensate for the missing documentation, leaving the meaning of 'size' and query syntax ambiguous.

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 'Search institutions.' clearly identifies the verb and resource, but it lacks specificity about what constitutes an institution or what the search returns. It does not differentiate from sibling tools like authors_search or conferences_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?

No guidance is given about when to use this tool over other search tools such as authors_search or conferences_search. There are no exclusions, references to alternatives, or contextual cues for selection.

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, and the description adds concrete behavior: returns specified fields, scoped to caller, defaults to active only. No contradiction.

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

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

Two crisp sentences, front-loaded with purpose, no wasted words.

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

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

Covers return fields and use cases; no output schema so field listing is helpful. Slightly could mention include_inactive but not necessary.

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

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

The schema fully documents include_inactive with default behavior; description adds no extra parameter semantics beyond that, so baseline 3.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates returned fields, distinguishing it from sibling tools like subscribe/unsubscribe by framing use cases.

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

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

Explicitly instructs when to use: to review current monitoring before adding more subscriptions or to obtain an id for cancellation. This directly ties to subscribe and unsubscribe functions.

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, covering the safety profile. The description adds the context that the record comes from INSPIRE, but does not disclose behavior beyond that. With annotations present, this is adequate but not exceptional.

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, direct sentence with no unnecessary words. It is appropriately sized for a simple tool with one parameter, and it conveys the essential purpose concisely. No waste.

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

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

The tool has only one parameter, an output schema, and strong annotations, so the description doesn't need to explain return values or safety. However, it lacks any context about when to use this tool compared to other search-oriented siblings. For a one-record lookup, the functionality is clear, but the missing usage guidance prevents a higher score.

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 has 0% description coverage, but the description explicitly mentions 'INSPIRE record id,' which clarifies that record_id is an INSPIRE record identifier. However, it does not explain the format, range, or whether it expects a numeric ID beyond the schema's type 'number' and example. This modest clarification earns a midpoint score.

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 'Single literature record by INSPIRE record id,' clearly identifying the resource (literature record) and the key (INSPIRE record id). Though no explicit verb like 'get' or 'retrieve' is present, the phrasing implies retrieval. It distinguishes from sibling tools like authors_search or search by focusing on a single record identified by a specific ID.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios where a user should use this instead of search or authors_search, nor any exclusions or prerequisites. The description only states what it does, not when to choose 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 are all false and offer no behavioral insight. The description compensates by disclosing rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and workflow context ('The team reads digests daily...'). It also gives guidance on content formatting ('don't paste the end-user's prompt'), which goes beyond the schema.

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

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

The description is compact (4 sentences) and well-structured: purpose first, then usage scenarios, content guidance, and operational notes. Every sentence contributes useful information; 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 is a simple feedback submission without an output schema, the description covers all necessary aspects: what it's for, when to use it, content constraints, rate limits, and cost. No critical gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by telling users to 'describe the issue in terms of Pipeworx tools/packs' and to avoid pasting the end-user's prompt, which supplements the message parameter description. This is more than just repeating schema info.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the feedback categories (bug, feature, data_gap, praise), which distinguishes it from the sibling research and search 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 provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' This clearly defines the boundary vs. other tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable non-annotated traits: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This goes beyond the structured metadata.

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

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

The description is well-structured: a lead sentence, a bulleted use-case list, and a concise data-detail sentence. It is slightly verbose with the 'Useful for' list repeating some of the first sentence, but overall efficient and front-loaded.

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

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

For a simple one-parameter read-only tool, the description covers return contents (top tools, packs, total call volume), data shape ((pack, tool, count)), caching, and usage scenarios. No output schema exists, but the description sufficiently explains what to expect.

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 single parameter 'window' is fully documented in the schema with enum values and explanation. The description only restates the window options without adding new semantic meaning (e.g., recommended choices for different scenarios), 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 clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses a specific verb ('Returns') and resource, distinguishing it from all sibling tools as the only trending/aggregation tool.

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

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

The 'Useful for' list provides explicit scenarios (discovering hot data sources, confirming canonical tools, checking use case alignment). However, it does not mention alternatives or when not to use this tool, so it stops 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?

Despite annotations declaring readOnly/idempotent/non-destructive, the description goes far beyond them by disclosing thresholds (3pp, 0.30 Jaccard, 20% placeholder), filter behavior (dropping placeholder slugs, returning null arb signal), fill-check pricing against live CLOB depth, and output fields. It adds significant behavioral context that the annotations do not 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 quite long, but every section adds value: semantic anchor, partition filter, fill check, and response format. The use of CAPS headers helps structure the content. It is slightly dense but justified by the tool's complexity; no gratuitous 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 fully explains the response structure (opportunities[], partition_check fields, fill check fields). It also covers edge cases (skipped_low_similarity, placeholder fraction), mode selection, and points to a sibling tool for custom sizing. This is complete for a complex, multi-mode 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?

Input schema covers both parameters with descriptions, but the tool description enriches them with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifies that full URLs are accepted for event, and explains how each parameter changes mode. This goes well beyond the baseline 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 opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by naming its unique detection methods and multiple modes (trending_scan, event, topic).

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names the alternative for custom sizing ('use polymarket_fill_risk') and even provides actionable guidance on when not to trade ('realizable_edge_pp ≤ 0 ... do not trade it').

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

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

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral details: response structure (by_segment, fed_candidates, _diagnostics), 1h KV-level caching keyed on knobs, 24h-move warning, Kelly caps at 0.25, placeholder-slug filters, and why Fed bets are excluded from ranking. 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 a single dense paragraph with heavy use of ALL-CAPS markers and many parenthetical details. It front-loads the core purpose and contains valuable information, but the lack of line breaks and excessive specificity (e.g., 'Run 8') hurt scannability. It is appropriately sized for complexity but not concise.

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

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

With no output schema, the description carries full responsibility for return values. It thoroughly covers top-level response keys, per-opportunity fields (edge_pp_net, kelly_fraction, market metrics, 24h warning), segment definitions, and diagnostics so callers understand empty segments. This is complete for a complex 9-parameter tool with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful meaning: explains why min_kelly cannot filter partition arbs (parent-level kelly_fraction_half=0 by design), gives real-world slippage context (20-50bp typical), and maps tradeable-edge knobs to parameters. This exceeds 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 opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly ties to a use case and distinguishes itself from siblings by describing three model families and output segments.

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

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

Provides clear usage context ('Built for "what should I bet on today"') and explains when filters (min_liquidity, max_spread_pp, min_partition_leg_kelly) should be applied. However, it does not explicitly name alternatives or exclusion conditions relative to sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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

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

Annotations already cover read-only and non-destructive behavior, but the description adds substantial behavioral context: response structure (tracked, expired, snapshot_dates), TTL limitations, gaps in snapshot coverage, and the fact that decay is computed from daily closes, not intraday. No contradiction with annotations.

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

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

The description is long but well-structured: purpose, args, response fields, and limits are labeled. Every sentence earns its place by providing valuable detail (e.g., median lifespan as 'competition clock', negative edge_pp_net meaning SELL YES). It is thorough without being redundant.

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

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

Despite lacking an output schema, the description fully specifies the response shape and semantics. It covers the tool's purpose, parameters, data source, limitations, and edge cases (snapshot gaps, TTL). No significant gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100%, with both parameters clearly described. The description repeats defaults and clamps but does not add meaningful new semantics beyond the schema. Baseline 3 is appropriate since the schema carries the load.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on time-series decay rather than current edge values.

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 context is clear: use this when edge persistence/decay matters, e.g., comparing fresh vs old wide edges. It does not explicitly name alternatives or exclusions, so it does not earn a 5, but the situational guidance is strong enough for a 4.

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

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

Annotations already declare read-only/idempotent, so the bar is lower. The description adds depth: it walks the ladder, enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), and highlights forced_directional_risk as a dominant loss mode. 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?

Though lengthy, the description is tightly organized with uppercase mode labels and separate sections. Every sentence adds value—no filler—and the core purpose is front-loaded. The density is justified by the tool's complexity.

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

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

No output schema exists, so the description carries the full burden of explaining return values. It lists all key outputs for both modes, including verdict values and per-leg details, and even describes the relationship to sibling tools. This is more than 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 coverage is 100%, but the description adds crucial semantics: `size_usd` has different meanings per mode (max spend vs settlement notional), `side` includes auto behavior for baskets, and the `market`/`event` distinction is clarified with URL/slug formats. This goes well beyond the schema's one-line 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 opens with a precise verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two operational modes (single-market and basket) and references specific sibling tools, making selection 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?

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why via the risk of theoretical overround and partial fills, and which parameter switches between modes.

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 and non-destructive behavior, but the description adds substantial context: it details the compatibility_warning cases, temporal alignment semantics, and skipped_cross_type/subtype counters. This goes well beyond the structured fields and gives the agent a realistic picture of when the tool returns meaningful results vs. when it flags non-equivalence. 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 densely structured with clear sections (modes, response, safety fields). It front-loads the core purpose and uses capitalization to highlight key terms (TWO MODES, RESPONSE, SAFETY FIELDS). While it could be trimmed, the length is justified by the complexity of the tool and the many edge-case explanations.

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

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

For a tool with no output schema, the description thoroughly covers return fields, safety warnings, temporal alignment, and failure modes. It prepares the agent for common pitfalls (non-equivalent bet shapes, incompatible resolution dates) and explains the meaning of counters. This is complete enough for reliable invocation given the tool's complexity.

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

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

Schema coverage is 100% with per-parameter descriptions, so the baseline is 3. The description adds value by explaining how the parameters interact: explicit tickers override the topic-mapped side, and the topic list is enumerated. It also clarifies the meaning of 'pre-mapped' vs custom pairing, which is not explicit in 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 specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from Polymarket-only siblings by emphasizing the cross-venue nature and the matched-outcome spread, making the purpose unambiguous.

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

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

The description explains two operational modes (topic shortcuts vs explicit identifiers) and when each is appropriate. It also warns that pre-mapped topics are often not tradeable, providing practical usage caveats. However, it does not explicitly name alternative tools or state 'use X instead when...', so it stops slightly short of full alternatives 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?

Given the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds valuable context beyond them by disclosing scoping behavior ('Scoped to your identifier') and the ability to list all keys. It does not cover failure modes, but the annotations already provide sufficient safety context.

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

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

The description is concise and well-structured: three sentences that cover the core function, usage scenarios, and related tools. It is front-loaded with the action and contains no redundant or extraneous 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 tool with a single optional parameter and no output schema, the description is remarkably complete. It covers the core function, when and why to use it, scoping details, and associated tools, providing all necessary context for an agent 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?

Although schema coverage is 100%, the description enriches the parameter meaning by explaining the effect of omitting the key ('or list all saved keys') and providing concrete examples of key values (target ticker, address, research notes), which goes beyond the schema's basic description.

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

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

The description clearly states the action ('Retrieve a value previously saved via remember, or list all saved keys') and identifies the resource (saved memory). It also distinguishes itself from sibling tools by referencing 'remember' and 'forget', making it unambiguous.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and provides examples of appropriate use cases. It also pairs with related tools ('Pair with remember to save, forget to delete'), effectively communicating its place among 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behavioral details: the mark_read parameter has a side effect of flagging events as read so subsequent calls show only newer ones, and it reveals the return payload includes source and citation_uri. It also notes the feed is persisted, adding value beyond the structured hints.

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

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

The description is four concise sentences, front-loaded with the core purpose ('Pull fired events from your subscription feed'), and each sentence adds relevant detail (return payload, filtering, mark_read, polling). No redundancy or filler; every clause earns its place.

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

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

For a read-oriented tool with no output schema, the description is remarkably complete: it explains what the tool returns, how to filter (type, since), the side effect of mark_read, and even provides an alternative public endpoint. It covers all key aspects an agent needs to select and invoke the tool correctly, and clearly differentiates it from related tools.

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

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

The input schema already provides 100% coverage with descriptions for all 5 parameters, so the baseline is 3. The description adds extra meaning by giving a concrete type example ('sec_8k') and explaining the consequence of mark_read ('so the next call only shows newer ones'), which enriches understanding beyond the schema alone.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly explains the tool's function (returning recent alerts) and details the payload structure (source, citation_uri, raw event payload), making it easy to distinguish from sibling tools like recent_changes or list_subscriptions.

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

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

The description states 'Polls work fine', indicating the tool is suitable for repeated polling, and mentions an alternative HTTP endpoint for scripts/dashboards, which guides usage context. However, it does not explicitly compare to sibling tools or specify when not to use it, so it lacks explicit exclusions.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses important behavioral traits: fans out to SEC EDGAR, GDELT→GNews fallback under rate-limits/5xx, and USPTO PatentsView API sunset causing soft-fail. These failure modes and fallback logic are not apparent from annotations and are valuable for an agent to anticipate inconsistent results.

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 well-organized: natural language examples, then a definition, source list, fallback details, input format, return summary, and alternative pointer. Every sentence adds value, and the use of dashes separates distinct clauses. Despite length, it remains focused and front-loaded with the core purpose.

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

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

Given the tool's complexity (multiple sources, fallbacks, time windows) and lack of output schema, the description covers input formats, source behavior, failure modes, return shape (changes[], total_changes, citation URIs), and an explicit alternative. This is a complete picture 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 description coverage is 100%, and each parameter is already documented (type enum, since format, value examples). The description repeats the `since` format ('ISO date or relative shorthand') and adds no new parameter semantics. It does add context about the overall call pattern but not per-parameter meaning, so baseline 3 is appropriate.

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

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

The description opens with multiple natural language query examples ('What's new with X', 'latest on Y') and then defines the tool as a 'change feed for a company in the last N days/weeks/months'. It clearly distinguishes from sibling entity_profile ('static profile... regardless of window'). This gives a specific verb (change feed) and resource (company changes) with explicit scope and differentiation.

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

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

The description explicitly names when to use an alternative: 'Use entity_profile instead when you want the static profile...' It also provides context for when this tool is appropriate (time-bounded change queries) and mentions efficiency ('in ONE parallel call'). This is a clear when-to-use with a named 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 note readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavior not in annotations: storage as a key-value pair scoped by agent identifier, persistent memory for authenticated users, and a 24-hour retention for anonymous sessions. 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?

The description is four sentences, each earning its place: the first explains the core action, the second gives use cases, the third covers scoping and retention, and the fourth names sibling tools. It is front-loaded with the primary purpose and contains no redundant or filler content.

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

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

For a simple 2-parameter write tool with no output schema, the description fully covers the purpose, explicit usage triggers, persistence behavior, and tool relationships. It lacks no critical information an agent would need to decide when and how to call this tool.

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

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

The input schema already describes both key and value with examples, so coverage is 100%. The description adds the concept of a key-value pair scoped by the agent's identifier, which gives extra semantic meaning to the parameters beyond what the schema states, but does not substantially elaborate on parameter syntax or constraints.

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 the specific verb 'Save' and identifies the resource as data the agent will need to reuse later, clearly stating the tool's function. It distinguishes itself from sibling tools by explicitly pairing with recall for retrieval and forget for deletion, and adds scope across conversations/sessions.

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 when you discover something worth carrying forward') and provides concrete examples like a resolved ticker or user preference. It also names alternatives (recall, forget) and clarifies the persistence model, giving the agent clear context for choosing this tool.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds useful behavioral context: it cascades through multiple lookup endpoints, auto-disambiguates inputs, and returns citation URIs. These traits go beyond what annotations provide, though it does not cover rate limits or error behavior.

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

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

The description is well-structured and front-loaded with example queries, then states the purpose and supported types. Every sentence adds value, and despite its length, it is efficiently organized for a tool with two distinct entity types.

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 two parameters and no output schema, the description fully covers what the tool does, what each type returns, and how to format inputs. It also explains why to use it (replaces manual lookups), 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 coverage is 100%, so the baseline is 3. The description adds significant value by giving examples and explaining what each type returns (e.g., company → ticker + CIK + company_name + citation URI; drug → RxCUI + ingredient + brand). This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: resolve a user-spoken NAME to the canonical/official identifier other tools require as input. It uses specific verbs (resolve) and resource (entity names to identifiers), and distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID.'

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: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. It does not name specific alternative tools, but the guidance is clear and contextually complete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavior: it probes each entity, ranks by score, surfaces which is most/least recognized, and returns a ranked list with score, confidence, and signal density. It also discloses that it calls ai_visibility_check per entity, which is a useful behavioral detail. It does not mention rate limits or cost, but annotations cover the non-destructive aspect.

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, front-loaded with the core purpose, and every sentence adds value: the action, the internal mechanism, the use case, and the return format. The quoted example is an effective, minimal illustration. No wasted words.

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

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

For a tool with 4 parameters (one required), no output schema, and moderate complexity, the description covers the main aspects: input (multiple entities), process (probing with ai_visibility_check), output (ranked list with score/confidence/signal density), and use case (competitive audits). It could be more complete by mentioning the optional Anthropic model and API key requirements, but these are documented in the schema. Overall, it gives enough context for an agent 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?

The input schema already provides descriptions for all 4 parameters (100% coverage), so the description is not required to compensate. It adds some contextual meaning by framing 'entities' as 'your brand + N competitors' and referencing the 'models' parameter implicitly through 'Probes each entity with ai_visibility_check,' but it does not go beyond the schema. This 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 opens with a specific verb-object pair: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (which might be broader) by stating it probes with ai_visibility_check and ranks results. The example use case ('does Claude know about us as well as our competitors?') makes the purpose concrete.

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

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

The description states when to use it: 'Useful for competitive AI-marketing audits' and gives a concrete example. It also implies the alternative ai_visibility_check for single-entity checks by stating it 'probes each entity with ai_visibility_check.' However, it does not explicitly mention exclusions or compare to the sibling compare_entities tool, so it falls short of a 5.

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

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

Adds substantial behavioral context beyond the readOnly/idempotent hints: composite fan-out, graceful degradation with partial failures, 5-30s first-measurement latency for bundlephobia, and the sources_failed field. This operational detail is valuable for an agent managing timeouts and partial results.

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 packed with necessary information but remains efficient given the tool's composite nature and absence of an output schema. Each clause serves a purpose, though the long return-field list makes it slightly dense.

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

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

With no output schema, the description fully compensates by listing the summary block fields, per-advisory details, links, and alternative versions. It also covers ecosystem scope, latency, and partial-failure behavior, making it complete for agent decision-making.

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% for both parameters (package and version), so the description adds little new parameter-level meaning beyond what the schema already provides. It does restate the default-latest behavior, but no syntax, format, or edge-case info is added.

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 composite check definition, naming the two underlying services (deps.dev and bundlephobia) and the exact question it answers ('should I add this npm package to my project'). It clearly distinguishes itself from sibling tools like search or validate_claim by focusing on dependency evaluation.

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 usage triggers are provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives exclusion guidance for non-NPM ecosystems (PyPI/Maven/Cargo/Go fall under deps.dev:version directly), helping agents choose alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scope 'literature' but does not disclose additional behavioral traits such as result structure or execution details, so it provides only marginal value beyond annotations.

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

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

The description is extremely concise with only two words, which is efficient but under-specified. While it is front-loaded and waste-free, it lacks the detail expected for a tool with a rich schema and many siblings, making it merely average rather than exemplary.

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 a detailed schema and strong annotations, the description leaves out essential context for selecting this tool among many similar siblings. It does not clarify the literature scope, how it differs from the 'literature' or 'search_within' tools, or any contextual use case. The output schema covers return values, but selection guidance is missing.

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

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

The schema has 100% description coverage for all five parameters, including query syntax, pagination, and sort options. The description adds no parameter-level meaning, so it neither enhances nor detracts from the schema's already complete 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 'Literature search.' clearly states the action (search) and resource (literature), making the core purpose understandable. However, it lacks any scope detail and does not differentiate from sibling tools like 'literature' or 'search_within', so it falls short of a perfect 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?

There is no guidance on when to use this tool versus alternatives. The description offers no context about use cases, prerequisites, or exclusions, leaving the agent to infer applicability from the name and schema alone.

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 non-destructive and read-only, but the description adds significant behavior beyond that: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagging, and the return of offsets and similarity scores. This transparently sets expectations for how the search works and its limits, with no contradiction to 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 sentence contributes: the core action, the use case, the mechanism, the limits, and the pairing. It is front-loaded with the main verb and resource, and while longer than a single line, it does not waste words or repeat schema content.

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

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

With no output schema, the description compensates by specifying the return shape ('top-N passages with character offsets and similarity scores'), including the cap and truncation behavior, and explaining why offsets matter (verifiable quotes). This fully equips an agent to understand what the tool will do and what to expect from it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving real-world examples of what 'text' can be (SEC 10-K body, article, long tool result) and reinforcing that queries are natural language, supplementing the schema without redundancy. It doesn't go deep into formatting beyond the cap, but the schema already covers parameter types.

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: 'Semantic search INSIDE a fetched record.' It clearly differentiates from siblings by emphasizing the 'inside' scope and by naming ask_pipeworx_grounded as its complementary counterpart, so an agent knows this tool operates over already-fetched text rather than external sources.

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 usage criteria are provided: 'Use when the record is too big to cram into the prompt.' It also gives a concrete alternative strategy ('fetch with the gateway, ground over the relevant passages instead of the whole document') and names the paired tool, which is strong guidance for when to choose this vs. other tools.

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

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

Annotations already mark this as non-read-only, non-destructive, and idempotent, but the description adds substantial behavioral context: auth requirements, the always-on feed, SMS verification and daily cap, one-time webhook signing secret, HMAC verification, auto-disable after 10 failures, and return of the subscription id. This goes well beyond the structured annotation data.

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. It is front-loaded with purpose and return value, then covers auth, types, and delivery in a logical order. Some details (especially webhook mechanics) are duplicated in the input schema, but the density is justified given the number of subscription types and delivery channels.

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 (three parameters, nested delivery objects, five type enums, no output schema), the description covers prerequisites, return value, delivery channels, type-specific filter examples, and critical constraints like phone verification and rate caps. It is sufficient for an agent to know when and how 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?

Schema coverage is 100%, and the schema already describes params and delivery. The description adds meaningful examples and constraints: sec_8k item codes (e.g., '5.02' for officer change), polymarket topic examples, fred_series series_id, phone verification requirement, SMS cap, and webhook signing behavior. This significantly enhances parameter understanding.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly names the return value (subscription id) and enumerates supported subscription types, distinguishing this tool from siblings like list_subscriptions, unsubscribe, and 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?

The description provides clear usage context: it explains the OAuth prerequisite, mentions delivery channels, and points to recent_alerts or a registry URL for pulling feed data. It does not explicitly say 'use list_subscriptions to view subscriptions' or 'unsubscribe to remove one,' so it falls short of an explicit alternatives comparison.

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. The description adds meaningful behavioral context: returns category-bucketed example questions drawn from a live catalog, and the exact tool+argument shape. No contradictions and enriches beyond annotations.

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

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

The description is long but every sentence earns its place: it lists natural language queries, explains the return format, enlists categories, gives invocation variants, and states first-use priority. It is front-loaded with examples and well-organized.

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

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

Despite no output schema, the description fully explains what is returned (category-bucketed questions with tool+argument shape), how to invoke (no args or topic), and why to use it. It covers the entry-point use case, meta-tool learning, and focus narrowing, leaving no significant gaps.

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

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

While the schema describes the topic parameter, the description adds crucial semantics: omitting gives a cross-category spread, passing a topic focuses the results, and provides example values (finance, pharma, betting). This goes beyond schema coverage and clarifies the parameter's effect.

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 lists example questions categorized by domain, with exact tool and argument shapes for each. It distinguishes itself from siblings by positioning as the onboarding entry point and explicitly naming meta-tools like ask_pipeworx and entity_profile.

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

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

Provides explicit when-to-use guidance: "Use this FIRST when you do not yet know what Pipeworx can do for you." It also explains how to call (no args for full spread, topic to focus) and references alternative tools, making usage context unambiguous.

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

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

The description adds meaningful behavioral context beyond the annotations: it explicitly states the row is deactivated (not deleted) and that historical events stay available via recent_alerts. Ownership enforcement is also disclosed. This complements the annotations (readOnly=false, destructiveHint=false, idempotentHint=true) without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value: operation, ownership constraint, and deactivation semantics. No filler or redundant information.

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

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

For a simple single-parameter mutation tool with strong annotations and schema coverage, the description fully covers essential aspects: what it does, ownership, non-destructive behavior, and where to access historical data. No output schema is needed, and the description is 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?

The input schema already provides 100% coverage for the single parameter, including a description of 'id' as the subscription UUID returned by subscribe. The description adds no further parameter details, so a baseline score of 3 is appropriate since 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 clearly states the tool cancels a subscription by id, with a specific verb ('cancel') and resource ('subscription'). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and adds the ownership constraint that clarifies scope.

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

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

The description provides clear context on when to use this tool (to cancel a subscription) and includes a key constraint (ownership enforcement). It also explains the effect on historical events, which implies an alternative (recent_alerts) for viewing history, though it does not explicitly name alternative tools for cancelling vs. deleting.

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, idempotent, open-world, and non-destructive, so the description adds beyond them. It discloses the dual pipeline (SEC EDGAR/XBRL fast path vs grounded fallback), the specific verdict types, the requirement for verbatim evidence with a citation, and the tolerance override behavior. This is rich behavioral context.

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

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

The description is longer than minimal but front-loaded with trigger phrases and kept dense without fluff. Each sentence contributes novel information about routing, output, or efficiency, though it could be slightly tightened without losing meaning.

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

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

Given no output schema, the description fully covers the return structure: verdict types, actual value with citation, and reasoning. It also explains the two execution paths and the tool's role versus alternative sequential calls, making it sufficient for an agent to invoke correctly.

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

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

Schema covers both params, so baseline is 3. The description adds value by explaining tolerance_pct as an override of implied tolerance, capping at 5 by default, and suggesting 1–2 for hallucination detection. It also gives a concrete claim example, enriching the schema's descriptions.

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

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

The description uses a specific verb ('validate', 'verifies') and clearly identifies the resource (natural-language factual claims). It includes trigger phrases and distinguishes itself from siblings by noting it replaces a multi-step pipeline and routes to specialized sources. The scope is 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives clear when-to-use context. It also delineates between company-financial claims and other claims, but does not explicitly name sibling alternatives or state exclusions, preventing a perfect score.

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