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?

The annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover the tool's safety profile. The description adds meaningful behavioral context beyond the annotations: the tool routes to one of 5,596 tools across 1,465 verified sources, fills arguments, and returns structured answers with stable citation URIs. This delegation model is non-obvious and useful for an agent. It does not mention rate limits or auth, but the annotations already cover the key operational characteristics, so this is above baseline.

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

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

The description is front-loaded with the most important directive, PREFER OVER WEB SEARCH, and the list of relevant data domains is useful for routing decisions. The final START HERE sentence repeats some routing and citations information from earlier, which is slight redundancy, but each section still earns its place through examples, exclusions, or clarifying scope.

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

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

For a tool with no output schema, the description covers its scope well: it specifies supported data categories, natural-language examples, the fact that it delegates to many internal tools, and the citation-bearing return format. It does not explain what happens with ambiguous, multi-part, or unsupported questions, and there is no explicit note about the output schema absence, but an agent has enough context to call the tool correctly in normal use.

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

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

The schema already covers all parameters with clear aliases and descriptions, so the baseline is 3. The description adds value through concrete question examples and explicit phrasings that tell an agent exactly what kind of natural-language input to put in the question parameter. It also emphasizes that the tool works even when web search could answer, which helps the agent decide to forward a raw or lightly reformulated user request. This is enough to raise the score modestly over the schema-only 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 begins with a clear directive: prefer this tool over web search for current or historical factual questions. It specifies what the tool does with a concrete verb and resource: routes the question to the right one of 5,596 tools, fills arguments, and returns a structured answer with stable citation URIs. The categories, examples, and explicit reference to web search make the purpose unmistakable and distinct from sibling tools.

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

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

The description gives robust usage triggers: whenever the user asks what is, look up, find, get the latest, how much, current, or asks any factual question about real-world entities, events, or numbers, even if web search could also answer it. It also says START HERE for most questions and gives concrete examples such as 'current US unemployment rate' and 'Apple's latest 10-K'. However, it does not explicitly contrast itself with sibling tools like ask_pipeworx_grounded or deep_research, so it lacks a fully explicit when-not-to-use instruction.

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, the description reveals important behavioral traits: it is a full working router, not a fallback, no candidate is currently active, and results may eventually be compared or merged based on outcomes. The description does not contradict the readOnly/destructive 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 mostly front-loaded and every sentence conveys relevant information: beta status, active-candidate state, and the difference from stable. The long parenthetical could be trimmed slightly, but it still serves the purpose of quantifying the tool's breadth.

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 includes enough context for an agent to call the tool safely and appropriately, including current experimental status, equality to ask_pipeworx right now, and the absence of a fallback. Given the rich annotations and 100% parameter descriptions, the lack of an output schema is not a critical 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 100%, so the input schema itself already explains the aliases and notes that question accepts q, prompt, text, and input. The description adds only 'same arguments as ask_pipeworx', which does not materially improve parameter understanding beyond the schema.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, an identical universal router for answering questions, with the difference being experimental routing changes. It names the stable sibling ask_pipeworx and clarifies that this variant is the experimental edge, which distinguishes it sufficiently.

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

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

It explicitly says to use it like ask_pipeworx 'when you want the newest routing' and that results are compared against the stable router, providing clear context for when this beta is applicable. It does not provide explicit exclusions for when not to use it, but the stable alternative is referenced and the experimental nature is stated.

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

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

Annotations already declare readOnly and non-destructive behavior; the description adds substantial behavior beyond that: it extracts only from tool results, returns verbatim evidence, and provides a structured refusal with specific refusal_reason values. It also discloses the extra LLM call cost. No contradiction with annotations exists.

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

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

The description is front-loaded with the most important trait ('hallucination-resistant') and packs the routing, extraction, output format, refusal reasons, usage guidance, and cost tradeoff into a compact block. A few sentences are dense, but every sentence carries information; it's appropriately sized for a high-stakes read tool.

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

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

The tool description fully defines the return shape including the success fields and all possible refusal reasons, states when to use it over the sibling, and gives the cost tradeoff. Even though there is no output schema, the description carries the entire contract. Everything an agent needs to call and interpret this tool is present.

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

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

Schema description coverage is 100%; each of the six parameters is fully documented as an alias for question in the schema. The description does not go beyond the schema, but because coverage is complete, the baseline of 3 is appropriate — no additional parameter semantics are required.

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 'Hallucination-resistant answer mode for high-stakes reads' and then details exactly what the tool does: same routing as ask_pipeworx but with a final extract-only-from-source step that returns an answer or an explicit refusal. It clearly differentiates itself from the sibling ask_pipeworx and the sibling list, making the tool's specific 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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and names risk contexts (financial, legal, medical, public statements). It also states the alternative: 'prefer ask_pipeworx for casual lookups' and mentions the additional LLM call cost, so the agent knows both the trigger and the tradeoff.

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 the tool read-only and idempotent. The description adds the types of queries accepted and the fields returned (e.g., record id, ORCID, affiliations). It does not mention pagination or rate limits, so it adds some but not extensive behavioral context beyond the annotations.

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

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

Three sentences, each adding value—context, return values, and purpose. The description is front-loaded and free of verbose filler, though the opening appositive could be trimmed slightly.

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

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

The description covers the tool's purpose, query format, and return fields. With an output schema present and only two parameters (one explained), the description is adequate for correct invocation, though the 'size' parameter remains a minor 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?

The explanation of 'query' as a Lucene/Solr query with examples (surname or ORCID) adds meaningful semantics beyond the bare string type. However, 'size' is left undefined with no guidance on maximum values or default behavior.

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 'search its HEPNames author records with a Lucene/Solr query such as a surname or ORCID,' which clearly identifies the action (search) and resource (author records). It also specifies the output (record id, name forms, affiliations, ORCID, arXiv categories), distinguishing 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?

It states the tool 'answers which particle physicist a name refers to in INSPIRE and what their author record id is,' giving clear context for when to use this tool. However, it does not explicitly mention alternatives or exclusions, 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?

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 declare the tool as safe (readOnly, idempotent, non-destructive). The description adds beyond annotations by explaining the query language (Lucene/Solr) and the exact fields returned (record id, title, acronym, dates, location, series, proceedings links), giving the agent a clear picture of behavior 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 database name and scope, then detailing the query format and return fields. Every sentence adds value; no verbose or redundant content. Highly structured and easy to scan.

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

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

Given the tool's simplicity (2 params, output schema present, strong annotations), the description covers purpose, query syntax, and return contents. It is complete for an agent to select and invoke correctly. Output schema handles return details, so description depth is appropriate.

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%, so the description must explain parameters. It clarifies that 'query' is a Lucene/Solr query, which adds meaningful syntax context. However, it does not explain the 'size' parameter, leaving it to the schema's name/type to convey meaning. This partial compensation warrants a middle 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 clearly states the tool's function: searching the INSPIRE-HEP conferences collection for particle-physics meetings, workshops, and schools. It specifies the resource (conferences), the action (search), and distinguishes from siblings like literature_search or authors_search by focusing on conference records.

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

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

The description implies when to use this tool: for questions about physics conference events, their dates, locations, and proceedings. It does not explicitly name alternatives or exclusions, but the conference-specific focus and the mention of 'answers when and where' give clear contextual guidance.

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

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

Annotations already provide read-only, idempotent, open-world, non-destructive signals, and the description adds substantial behavioral detail beyond them: the findings packet structure, verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation URIs, gaps[] for unanswered facets, contradictions[], semantic excerpting of large records, and latency expectations. It also explicitly claims it does not invent answers. This is rich, practical behavioral disclosure.

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 well organized: the account requirement and fallback tool appear first, followed by resource scope, output contract, exclusions, depth behavior, and latency. Every sentence adds decision-relevant information, and the structure front-loads the most urgent blocking fact: an account is required. Despite length, it remains manageable because all of it matters.

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 there is no output schema, the description carries the full burden of explaining what the agent should expect from the response. It covers return shape, evidence, citations, gaps, contradictions, excluded data, auth requirements, paid-tier requirements, and latency. Nothing critical is missing for an agent to decide whether to invoke this tool and what the result will look like.

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

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

Schema description coverage is 100%, so the baseline applies. The description largely restates the depth taxonomy already present in the schema: quick=3, standard=3 with gap-recovery and contradictions, thorough=6 with paid plan. It adds useful context like the paid plan and fallback tool when not signed in, but does not substantially enrich parameter meaning beyond what the schema already provides.

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

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

The description clearly identifies the tool as grounded multi-source research over Pipeworx's 1,465 structured data sources and immediately distinguishes it from open-web search. It also positions it against its siblings with explicit best-fit use: broad/multi-part questions like 'compare X and Y's regulatory + financial exposure.' The resource, action, and scope are all specific, so an agent can tell it apart from ask_pipeworx and search-style 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 is unusually explicit about when to use it and when not to: use ask_pipeworx if not signed in, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking/colloquial news. It also gives clear positive guidance: deep_research is for broad/multi-part questions over structured data. This provides an agent with actionable routing criteria before it even inspects schema.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: it accepts a Lucene/Solr query (implying query syntax) and returns specific fields (id, ICN code, names, address, country). This goes beyond annotations without contradicting them.

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

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

The description is two sentences, front-loading the purpose and key details. It includes examples and output fields. Slight redundancy in the last clause ('Answers what INSPIRE's record is...') but overall efficient.

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

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

With annotations and an output schema present, the description covers the essential behavior: what it searches, how the query works, and what fields are returned. It does not explain the 'size' parameter or pagination, but the schema provides examples. Adequate for a simple search tool.

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

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

Schema coverage is 0%, so description must compensate. It explains that 'query' is a Lucene/Solr query, adding semantics. However, 'size' is left unexplained, and the examples in the schema do not suffice. Partial compensation only.

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

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

The description clearly states the tool searches the INSPIRE-HEP institutions collection, naming specific examples (CERN, Fermilab, DESY). It distinguishes itself from sibling search tools like authors_search and conferences_search by focusing on institutions. The verb 'search' and resource are explicit.

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

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

The description provides clear context for when to use the tool: when seeking an institution's record in INSPIRE-HEP. It does not explicitly mention alternative tools or exclusions, but the purpose is specific enough to guide selection. No contradictory or misleading guidance given.

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

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

Annotations already declare 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 (not read-only, not idempotent, not destructive), and the description adds substantial behavioral context: returns a claim_token for anonymous submissions, later pass the token to retrieve resolution status, rate limited to 5 per identifier per day, free and not counted against quota, and that the team reads digests daily. This fully covers safety and side-effect expectations 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 longer than average but every major section earns its place: purpose, usage exclusions, message guidance, claim-token flow, processing cadence, and rate limits. It is front-loaded with the core purpose. Slightly verbose phrases like 'signal directly affects roadmap' could be trimmed, but overall it is well-structured and readable.

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

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

Given that there is no output schema, the description adequately explains the return behavior (claim_token and subsequent polling), rate limits, and submission constraints. It does not explicitly describe error cases or the exact shape of the eventual confirmation, but for a feedback tool with rich schema and annotations, this is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not significantly add beyond the schema for `type`, `context`, or `message`; it only provides a usage example for `claim_token` ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), but the schema itself already explains the token workflow in comparable detail.

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 'Tell' with a clear resource ('the Pipeworx team') and enumerates exactly what kinds of feedback are accepted (broken, missing, needs to exist). It clearly distinguishes this from the research/search sibling tools by positioning it as a feedback channel rather than a data retrieval tool.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and includes a clear exclusion: do not report issues from other MCP servers, and file those with the appropriate server instead. Provides additional guidance on identifying Pipeworx tools and what content to include (avoid pasting user prompts).

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

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

Annotations already declare 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?

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description reveals critical behaviors: cascading through multiple lookup endpoints, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), explicit labeling of identifier sources, and clear handling of unresolved identifiers. These details far exceed what annotations provide, giving the agent a robust understanding of the tool's runtime 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 front-loaded with example queries and the core purpose, then logically expands into supported types and behavioral details. Each section adds value. However, it is slightly verbose (e.g., detailed explanation of ISIN resolution for non-US issuers) and could be trimmed without losing clarity, preventing a top score.

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 (cascading lookups, multiple identifier sources, no output schema), the description covers the return behavior well: identifiers are labelled by source, unresolved identifiers are stated explicitly, and graceful degradation is described. It also explains edge cases like ISIN resolving to legal entities. Missing explicit output structure (e.g., example JSON) prevents a perfect score, but the description is sufficient for an agent to understand 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 input schema already covers both parameters (type, value) with 100% description coverage. The description adds significant extra meaning: for 'company' type it lists acceptable input forms (ticker, CIK, ISIN, company name) and details the output identifiers (CIK, ticker, LEI, FIGI); for 'drug' it specifies RxCUI, ingredient, brand, and citation. This goes well beyond the schema's brief descriptions, though some details (like ISIN-to-LEI mapping) could be considered extraneous.

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 identifiers other tools require as input.' It provides specific example queries (e.g., 'What's the ticker for…') and lists supported entity types. The instruction 'Use FIRST whenever you have a name but need an ID' distinguishes it from sibling tools, making its primary role 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 advises to 'Use FIRST whenever you have a name but need an ID,' establishing clear priority. It also notes that the tool 'replaces 2-3 manual lookups,' implying efficient usage. However, it does not explicitly list sibling tools to avoid or provide concrete 'when-not-to-use' scenarios, which would elevate the score.

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

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

Annotations 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 declare readOnly/non-destructive, but the description adds crucial behavioral detail: the dual-path routing, the six-verdict taxonomy, the verbatim evidence + pipeworx:// citation, and the error object semantics. It even warns that could_not_verify must not be treated as evidence—valuable 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?

Long but dense, every sentence carries load: examples, routing, output, caveats, and efficiency rationale. Front-loaded with query patterns and structured into clear segments. No fluff, and the length is warranted 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?

With no output schema, the description takes full responsibility for return values—and succeeds, listing all six verdicts, the actual value with citation, reasoning, and the error object. It also covers fallback behavior, edge cases (unsupported), and caller warnings, making it fully self-contained.

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 both parameters are well-described, yet the description adds extra nuance: concrete claim examples, how tolerance_pct overrides implied wording, the 5% cap, and the recommended 1–2 range for hallucination detection. This goes well beyond the structured 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 leads with a battery of natural-language query examples and a crisp definition: 'natural-language claim verification against authoritative sources.' It names a specific verb+resource (verify claim) and distinguishes itself from sibling tools by being the fact-checking tool, even noting it replaces 4–6 sequential calls.

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

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

It states explicitly: 'Use whenever the agent needs to check whether something a user said is factually correct.' It then gives a precise decision rule (company-financial claims → SEC EDGAR/XBRL; any other → grounded pipeline) and clarifies the meaning of could_not_verify vs unsupported, preventing misuse.

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