Devdocs Io

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

Annotations already cover read-only/idempotent safety, so the bar is lower. The description adds valuable behavioral context: default model is free Workers AI, passing an Anthropic key incurs direct costs, and the return structure includes per-model score/confidence/signals/raw_response plus a combined view.

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

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

Three sentences, front-loaded with the core purpose, then configuration and use cases. No wasted words, every sentence earns its place.

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

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

With no output schema, the description explicitly states the return format. It also covers defaults, optional parameters, cost implications, and use cases. For a 4-parameter tool, this is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful nuance for `_apiKey` (BYO key — you pay Anthropic directly) and clarifies default behavior for `models`. It does not re-explain `entity` or `context`, but the schema already handles those well.

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

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

The description starts with a specific verb 'Probe' and clearly identifies the resource (LLMs) and action (score visibility). It distinguishes the tool from siblings like ask_pipeworx or compare_entities by focusing on LLM knowledge probing and scoring.

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

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

The description gives clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternatives or when not to use it, but the context is strong enough to guide an agent.

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 and idempotentHint=true, so the description adds context beyond that: 'one fast call', 'works on every tier', 'fills arguments', and 'stable pipeworx:// citation URIs'. It describes the routing behavior and return format. 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 and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). Every sentence contributes value, though some redundancy exists (e.g., repeated emphasis on 'START HERE' and factual questions). It earns its length due to the tool's broad 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 complex router tool with no output schema, the description covers scope, use cases, return format (structured answer with citations), alternatives, and performance characteristics. It lacks explicit failure modes or limitations, but the given annotations and detail make it sufficiently complete for an agent to select and invoke confidently.

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% — all six parameters are documented aliases for 'question' with descriptions. The description adds example questions but no additional meaning for the parameters themselves. Baseline 3 applies since the schema already carries the semantic 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 a specific verb+resource: 'Routes the question to the right one of 5,439 tools' and 'returns the structured answer'. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, and it defines its scope with a comprehensive list of domains (SEC filings, FDA drug data, etc.).

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?

Extremely explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). It also gives exclusion cases such as breaking news, saying ask_pipeworx already routes to live news. Provides trigger phrases and concrete examples.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: it is an experimental beta, no candidate is currently active (so it behaves identically to ask_pipeworx), and it is a fully functional router with no fallback. This transparency about the experimental state and current behavior is not present in the annotations, giving a 4.

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, well-structured paragraph that front-loads the key fact ('Beta version of ask_pipeworx') and then efficiently explains the current state, usage, and fallback behavior. Every sentence contributes information, though it is slightly longer than strictly necessary—five sentences for what could be condensed. Still, it is appropriately sized for the complexity of a beta variant 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?

Despite the absence of an output schema, the description explains that the response shape is identical to ask_pipeworx, giving the agent all it needs to know. Combined with strong annotations and schema coverage, the description is complete for the agent to decide when to use this tool and what to expect. It covers the experimental nature, current state, and usage instructions, leaving no critical gaps.

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

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

The input schema has 100% description coverage, enumerating all six parameters and their aliases. The description only says 'same arguments' and 'identical... use exactly like ask_pipeworx,' which does not add new semantic meaning beyond the schema. Since the schema does the heavy lifting, a baseline 3 is appropriate.

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

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

The description clearly states it's the beta version of ask_pipeworx, an identical universal router with the same 5,439 tools and arguments. It distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements and explicitly noting it currently matches ask_pipeworx exactly. This provides a specific verb+resource and differentiates it from its sibling 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 description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges, providing context for why to choose this variant. It even clarifies that there is no fallback—it is a full working router—so the agent knows it can rely on it without needing another 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?

The description goes well beyond annotations by detailing the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal modes with specific reasons. It also discloses the extra LLM call cost and the 'ONLY what the tool result contains' constraint, which is critical behavioral context. No contradictions with annotations.

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

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

The description is dense but well-structured, front-loading the core value proposition. Every sentence carries operational weight — purpose, mechanism, return format, refusal behavior, use cases, and cost trade-off. No filler or redundant 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 fully compensates by specifying the return object fields and refusal reasons. It also covers the decision context (high-stakes reads), constraints (grounded in tool result only), and practical limitations (extra LLM call). 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% with all aliases documented (q, text, input, query, prompt, question). The description does not add parameter-specific semantics beyond the schema; it only describes the tool's overall behavior. Baseline 3 applies because the schema handles the parameter documentation.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies the verb ('EXTRACTS the answer') and resource (tool results from 5,439 tools across 1412 sources), and distinguishes it from the sibling ask_pipeworx by emphasizing groundedness and evidence.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also explicitly names the alternative (ask_pipeworx) and the trade-off ('Costs one extra LLM call... prefer ask_pipeworx for casual lookups').

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, and idempotent hints, but the description goes far beyond. It details safety short-circuiting (status:"low_confidence_match"), market-closed/inactive handling, wide-spread tradeability warnings, news fallback retry logic, and resolution-rule risk (e.g., refund_50_50, ev_impact). This level of behavioral disclosure exceeds what annotations provide.

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

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

Although long, the description is tightly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence adds critical operational detail. The first sentence front-loads the core purpose, and the remaining prose is dense but purposeful for a complex tool.

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

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

With no output schema, the description thoroughly explains response shapes (result.market, analysis, evidence), resolver contract fields, parent-event extraction, news fallback flags, and status codes. It also covers edge cases like closed markets and low-confidence matches, making the tool's runtime behavior fully predictable.

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

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

The input schema has 100% coverage with detailed descriptions for all three parameters (market, depth, include_raw), including enums and defaults. The description adds some examples of market formats but largely duplicates schema content. No parameter meaning is missing, 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 a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by framing itself as a general research aggregator with classifier categories and fan-out behavior.

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

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

The description explicitly states when to use the tool: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also provides fan-out examples for various bet types. However, it does not explicitly mention when NOT to use it or name alternative tools for other use cases, so it lacks exclusion guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and returning paired data with citation URIs. This gives the agent a comprehensive understanding of tool behavior without any contradiction.

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

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

The description is dense but every sentence adds value: trigger phrases, core behavior, data specifics for each type, sorting rule, and output format. It is front-loaded with user-friendly phrases for classification and maintains a logical flow. No wasted words.

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

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

Given the absence of an output schema, the description explicitly states return values (paired data, citation URIs) and sorting behavior. It covers input requirements, entity types, data sources, and strategic advantages, making it fully self-contained for correct invocation.

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

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

Although schema coverage is 100%, the description enriches parameter meaning substantially: type='company' specifically maps to financial metrics from 10-K filings, while type='drug' maps to FAERS/FDA/trial data. It also provides concrete examples for the values parameter, adding clarity beyond the schema's generic 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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and lists trigger phrases like 'X vs Y' and 'which is bigger'. It distinguishes itself from siblings like entity_profile (single-entity lookup) and deep_research by emphasizing parallel comparison and replacing sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear directive on when to use this tool. It also provides a rich set of example queries and outlines what data each type pulls, enabling the agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds only the word 'large' as extra context, which is minimal and does not disclose how the tool behaves, what it returns, or any side effects.

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 short, which might suggest conciseness, but it is under-specified rather than concise. It omits essential action and context, so the brevity does not serve a useful 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?

With one required parameter, no schema description coverage, and a vague noun-phrase description, the tool is inadequate for an agent to select or invoke correctly. The output schema and annotations exist, but the description does not explain the purpose, input, or expected behavior.

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

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

Schema description coverage is 0%, and the description does not mention the 'slug' parameter at all. The description fails to compensate for the lack of parameter documentation, leaving the parameter's meaning entirely unexplained.

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 'Content database for a doc (large)' is a noun phrase that restates the tool name without an action verb. It does not clearly state what the tool does or how it differs from sibling tools like 'docs', 'entry', or 'search_within'.

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 phrase 'for a doc (large)' offers a minor hint about scope but no explicit context, exclusions, or alternative recommendations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, but the description adds substantial behavioral context: requires a free/paid account, never invents answers (gaps[]), returns contradictions[] for deeper depths, semantically excerpts large records, uses hop fields and pipeworx:// citations, and gives latency expectations (15-60s, up to ~90s). This goes far beyond what annotations provide, with no contradictions.

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

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

The description is lengthy but information-dense, front-loading the critical account requirement and then logically progressing through core function, alternatives, depth behavior, and output characteristics. Each sentence adds necessary value given the tool's complexity, though a bit tighter editing could make it more digestible. It is well-structured and not 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?

With no output schema, the description fully explains the findings packet structure: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers prerequisites (sign-in, paid plan), latency, and handling of unmatchable topics (empty gaps[]). For a complex tool with no formal output schema, this description is complete enough for an agent to understand expected inputs and outputs.

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 covers 100% of parameters (question, depth with enum), but the description adds meaning by explaining each depth level's behavior ('quick=3 single hop', 'standard=5 adds a gap-recovery hop + contradictions[] scan', 'thorough=8 paid... full iterative hop') and clarifies that the question parameter supports broad/multi-part questions because decomposition is the point. This enriches the schema rather than repeating it.

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

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

The description clearly states this is a 'grounded multi-source research' tool across 1412 structured data sources, distinguishing it from open-web search. It explicitly names the resource (structured data catalog) and the action (decomposes, routes to tools in parallel, returns findings packet), and even says 'this is NOT open-web search', setting it apart from siblings like ask_pipeworx.

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 ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also names the alternative tools directly and mentions the account-sign-in prerequisite, providing complete selection 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 declare read-only, idempotent, and non-destructive behavior. The description adds beyond this by explaining the return format: top-N relevant tools with names, descriptions, full input schemas, curated examples, and no need for a second schema lookup. This gives the agent actionable expectations.

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

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

The description is two sentences, front-loaded with purpose. The first sentence states what the tool does and when to use it; the second details return behavior. The domain list is slightly long but purposeful for a discovery tool. 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 discovery tool with no output schema, the description covers what it returns (tools with schemas and examples), how to use it (natural language query), and when to call it (first when browsing options). It also notes results are directly callable, which is essential operational context. The tool is fully specified.

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

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

Schema coverage is 100%, so all 6 parameters (query, q, task, search, description, limit) are described. The description does not add significant meaning beyond the schema; it mentions only the concept of 'top-N' and provides example query strings in the schema's examples. Thus a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' with a specific verb and resource. It lists many domains, which helps the agent understand when to use it, and it distinguishes itself as a discovery/meta-tool versus sibling tools that likely perform direct data access.

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 when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available.' It gives clear context for when to use it, though it does not explicitly state when not to use it (e.g., if the exact tool is already known).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, establishing a safe read operation. The description adds the 'full catalog' scope and field list, but does not disclose any behavioral nuances such as pagination, rate limits, or data freshness. This is on par with the get_calls example where the description adds limited context beyond annotations.

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

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

A single sentence that is front-loaded with the action and resource, followed by a list of returned fields. Every word is purposeful; there is no fluff or repetition of the tool name in a tautological way.

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 (no parameters, no nested objects) and the presence of an output schema (which covers return value details), the description is complete. It communicates the source (DevDocs.io), the scope (full catalog), and the fields returned, covering all necessary context for an agent to invoke it accurately.

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 tool has no parameters, so the description is not required to elaborate on schema properties. The baseline for zero-parameter tools is 4, and the description appropriately focuses on the return value rather than assumed inputs. No additional parameter semantics are needed.

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 ('Return') and identifies a clear resource (the full DevDocs.io catalog), specifying the included fields (name, slug, type, version, release). This distinctly differentiates it from sibling tools like search_docs, which imply targeted searching rather than a full catalog listing.

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

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

The description clearly conveys that this tool returns the entire catalog, implying use when a complete enumeration of documentation sets is needed. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it over search-oriented siblings.

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

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

The description discloses detailed behavioral traits beyond annotations: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifies return fields (e.g., recent_filings up to 5, fundamentals from latest 10-K), notes the USPTO API sunset and soft-fail behavior, and mentions GDELT→GNews fallback. This is rich context that the readOnly/idempotent hints do not convey.

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

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

The description is long but well-organized: examples, usage directive, sources/return fields, and input constraints. Each sentence carries unique information, though the list of example phrasings could be trimmed without loss. Overall, it is dense but not wasteful.

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

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

The description provides complete context for a complex tool with no output schema: it details the exact structure of the returned profile (cik, company_name, filings, fundamentals, patents, news, LEI), notes limitations (US public companies only, ticker/CIK input, patent API sunset), and includes fallback behaviors. This leaves minimal ambiguity about invocation and expected results.

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 has 100% descriptive coverage for both parameters. The description adds no new semantic detail beyond the schema; it repeats the same ticker/CIK example and the note about names not being supported. Since schema covers everything, 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 the tool's purpose: to generate a full cross-source profile of a US public company in one parallel call. Examples (e.g., 'Tell me about X', 'research Acme') illustrate the use case, and it distinguishes itself from sibling tools like compare_entities and deep_research by focusing on a single entity and aggregating 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 guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a when-not instruction for names not supported and directs to resolve_entity as an alternative, making the usage conditions very clear.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds no behavioral context such as response format, error handling, or prerequisites. It simply states the resource type without any additional detail.

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 very short, but it is under-specified rather than concise. It lacks any meaningful structure or content, making it a fragment rather than a concise description.

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

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

For a tool with two required parameters and no schema descriptions, this description is massively incomplete. It provides no purpose, parameter semantics, or usage context, and although an output schema exists, it cannot compensate for the total absence of functional explanation.

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 has no parameter descriptions, and the description does not explain the meaning of 'path' or 'slug'. With 0% schema coverage, the description completely fails to compensate, leaving the parameters unexplained.

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 'Single entry HTML' is a noun phrase that restates the tool name without specifying an action. It does not clarify what an 'entry' is or how this tool differs from siblings like docs or index.

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. It neither names alternative tools nor describes contexts where it should be used.

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

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

Annotations already declare destructiveHint=true, and the description adds context about what gets destroyed (a previously stored memory) and why (clear sensitive data). This goes beyond the structured annotations by specifying the object of deletion.

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

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

Two sentences, front-loaded with the main action, and every sentence earns its place. No wasted words, with clear guidance and cross-references to related tools.

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

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

The tool is simple (one parameter), has strong annotations, and the description covers purpose, usage conditions, and tool relationships. No output schema is needed for a delete operation, making this description complete.

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

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

Schema coverage is 100% and the parameter description already says 'Memory key to delete.' The description's 'by key' is redundant, adding no new semantic detail beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb (Delete), resource (previously stored memory), and mechanism (by key). It distinguishes from sibling tools 'remember' and 'recall' by explicitly pairing with them.

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

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

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It does not explicitly state when-not-to-use or alternative tools, but the 'when' conditions are clear and actionable.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' plus output location guidance. This goes beyond annotations by explaining the processing steps and output form.

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 with the primary action, followed by process and use cases. It fits in three sentences and a short 'Useful for' list, with no redundant wording or 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?

The tool is simple and low-risk; annotations cover safety, schema covers parameters, and description explains output format. It's complete for typical use, though it does not mention failure behavior (e.g., invalid URLs), which is a minor gap for a fetcher 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 described in the input schema (url and max_links, including default/max values). The description adds no additional parameter-level semantics beyond what the schema already provides, 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 states a specific verb ('Generate') with a clear resource ('llms.txt file for any URL') and outcome ('so AI crawlers can index the site cleanly'). It outlines the process (fetches, extracts, emits) and differentiates from siblings by focusing on llms.txt generation, unlike scan_competitor_ai_presence or ai_visibility_check.

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

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

Explicit use cases are listed ('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'). It does not name alternative tools or when not to use, but the context is clear enough for agent selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. However, the description adds no behavioral context beyond that (e.g., what 'entries' means, whether results are paginated, or what the output structure looks like). It merely restates the tool's name in a slightly expanded form.

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, front-loaded phrase with no filler words. It is appropriately short for a simple tool, but the extreme terseness borders on under-specification, which prevents a perfect 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?

With a simple single-parameter tool, strong annotations, and an output schema, the description is minimally viable. However, it lacks usage context and parameter semantics, leaving the tool only partially complete for an agent to reliably invoke.

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 sole parameter 'slug' has no schema description (0% coverage), and the description only vaguely references 'inside a doc' without explicitly stating that 'slug' identifies the document. The examples in the schema hint at values, but the description fails to compensate for the lack of parameter documentation.

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

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

The description 'Index of entries inside a doc' conveys that the tool returns an index (list) of entries for a document, implicitly distinguishing it from sibling tools like 'entry'. However, it lacks an explicit verb (e.g., 'list' or 'get'), making it more of a label than a clear action, so it doesn't earn a 5.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'entry', 'search_within', or 'search_index'. The description neither states explicit use cases nor contrasts with other tools, leaving the agent without direction on appropriate invocation.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context by specifying the results are scoped to the caller and listing returned fields. It also implies the default excludes inactive subscriptions, which is useful behavioral detail 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?

Two sentences, front-loaded with the core purpose, followed by a usage tip. Every word earns its place; no padding or redundancy.

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

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

For a simple list tool with one optional parameter, the description is complete. It covers what is returned, the default behavior, and usage scenarios. No output schema is needed since the return fields are enumerated. Annotations cover safety aspects.

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 the parameter 'include_inactive' already well-described in the schema. The description does not add extra meaning about parameters, but since the schema fully documents them, the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It distinguishes itself from siblings like subscribe/unsubscribe by focusing on listing, and even lists the exact fields returned, leaving no ambiguity.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more' and 'to find an id to cancel.' This provides clear context and implicit alternatives (subscribe/unsubscribe), making it obvious when this tool is appropriate.

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

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

Even though annotations are all false (readOnlyHint, destructiveHint, etc.), the description adds substantial behavioral context: rate-limited to 5 per identifier per day, free and doesn't count against quota, the team reads digests daily, and signal affects roadmap. It also tells users not to paste end-user prompts, disclosing content expectations. 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 about 100 words and every sentence serves a purpose: stating the action, when to use, exclusion criteria, content guidance, impact, rate limit, and quota. It is front-loaded with the core purpose and uses clear bullet-like punctuation. No fluff or redundant restating of tool name.

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 feedback submission tool with no output schema, the description covers all necessary context: what to report, how to structure it, what not to do, rate limits, and expected impact. It even addresses edge cases like uncertain tool provenance. No significant gaps remain for an agent to decide when and how to invoke 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?

The input schema already provides 100% parameter coverage with descriptions for 'type', 'context', and 'message'. The description adds extra semantic value by instructing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the expected content of 'message'. This goes beyond the schema's basic type/format 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 specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool as a feedback mechanism and distinguishes it from sibling tools by explicitly listing the feedback categories (bug, feature, data_gap, praise) and stating it is ONLY for Pipeworx-served tools.

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

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

The description provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: feedback for tools from other MCP servers should be filed elsewhere. This is exemplary alternatives/exclusion guidance.

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

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

The description adds substantial behavioral context beyond the read-only/idempotent annotations: it reveals caching (5min-1h), data provenance (CF analytics-engine), no-PII guarantee, and that the response is a simple (pack, tool, count) tuple. 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 compact and well-organized: a direct one-sentence summary of the tool's output, followed by a bulleted list of use cases, and a final technical note on data source, privacy, and caching. Every sentence contributes 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 simple read-only aggregator with one optional parameter and no output schema, the description covers the purpose, use cases, return content, caching behavior, and data privacy. It is fully self-sufficient for an agent to decide when to call and 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 has 100% coverage, including a clear description of the window parameter ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats the window options but adds no new parameter-specific meaning, so the schema-driven baseline of 3 is appropriate.

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

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

The description starts with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then details the exact outputs (top tools, top packs, total call volume) and the time windows, distinguishing it from sibling tools like discover_tools by focusing on aggregated real-time call trends rather than general discovery.

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 gives three concrete scenarios: discovering hot data sources, confirming canonical tools, and checking alignment with other agents. This provides clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Despite annotations already declaring readOnly/idempotent/destructive, the description adds significant context: Jaccard similarity threshold, partition placeholder filtering, fill-check with CLOB depth, and the realizable_edge_pp <= 0 warning. This far exceeds annotation hints and reveals critical edge-case 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 longer than average but carefully organized into SEMANTIC ANCHOR, PARTITION FILTER, and FILL CHECK sections. Every sentence conveys a distinct operational fact with no fluff, and it's 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 modes, filters, fill checks) and absence of an output schema, the description compensates by outlining response structures and key fields. It covers all critical edge cases and provides enough detail to invoke the tool correctly without needing additional docs.

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

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

Schema has 100% coverage with basic descriptions, but the description enriches both parameters with mode semantics, slug examples, and edge cases. It clarifies that parameters are optional but mutually exclusive, explains how each mode processes the input, and specifies response artifacts like partition_check.

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 phrase 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly identifying the tool's core function. It distinguishes between modes (event vs topic) and references alternative tools like polymarket_fill_risk, making its unique scope clear.

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 mode selection guidance: no args for trending_scan, event for single-event, topic for cross-event. It also names an alternative tool (polymarket_fill_risk) for custom sizing, giving clear when-to-use and when-not-to-use directions.

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 discloses extensive behavioral details beyond the annotations: caching behavior (1h KV level keyed on knobs), response structure with diagnostics to explain empty segments, tradeable-edge filters, the Fed signal unreliability note, and the 24h-move warning. It also emphasizes that concentrated_longshot is rare-by-design and explains why partitions might be skipped. This goes far beyond the readOnly/idempotent hints.

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

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

The description is front-loaded with a clear purpose and is organized into logical sections (model families, response structure, knobs), but it is quite lengthy and dense. While every sentence carries technical weight, the overall length may hinder quick scanning. It is not as concise as the TDQS 4.3 example.

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 (by_segment, fed_candidates, diagnostics) and the fields carried by each opportunity (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, 24h-move warning). It also explains why a segment may be empty (top-N stale, failed gates, knob filters), which is crucial for an agent to interpret results correctly. The coverage is comprehensive 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?

The input schema already provides highly detailed descriptions for all 9 parameters (100% coverage), so the baseline is 3. The tool description adds some high-level context about the 'tradeable-edge knobs' and the min_partition_leg_kelly behavior, but most of this is already present in the schema's parameter descriptions. The description does not significantly compensate beyond what the schema provides.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). However, it does not explicitly distinguish itself from sibling Polymarket tools like polymarket_arbitrage or polymarket_edge_tracker, so it falls short of the top score.

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 a clear use case ('Built for what should I bet on today') implying when to use the tool, but it does not explicitly state when not to use it or how it compares to alternative tools such as polymarket_arbitrage, polymarket_edge_tracker, or polymarket_kalshi_spread. No exclusions or alternative recommendations are 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 the tool safe (readOnly, idempotent), and the description goes far beyond that by revealing data source mechanics: snapshots are written only on a cache-miss, so gaps mean no scan occurred; history depth is limited by a 60-day TTL; decay numbers come from daily closes not intraday. It also explains the response structure, including what 'expired' and 'snapshot_dates' represent. This is exemplary behavioral transparency.

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

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

The description is long but every sentence carries content. It is structured into clear sections (purpose, args, response, limits) and is front-loaded with the core question it answers. Despite its length, it avoids fluff and delivers high information density, which justifies 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?

With no output schema and a moderately complex tool, the description compensates fully by defining the exact response shape (tracked, expired, snapshot_dates), the meaning of each field (trend, decay_pp_per_day), and the edge cases (cache misses, TTL limits). It leaves no important aspect unexplained, making it complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, with both parameters already having detailed descriptions (days with default and clamp, window with allowed values). The description reiterates the defaults but does not add significant extra semantic meaning beyond what the schema states, aside from explaining the concept of 'snapshot family' in the response section. Therefore, a baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers the question 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence, not just current edges.

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 strongly implies when to use this tool: when you need to know whether an edge is fresh or old and whether it is decaying, contrasting 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternatives or give a 'when not to use' clause, but the context is clear enough for an AI agent to differentiate from polymarket_edges.

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, so the bar is lower, but the description adds substantial context: it walks the order book ladder, explains partial-fill risks, identifies the main loss mode for arb bots, and enumerates return fields. No contradiction with annotations; in fact, it reinforces the read-only nature.

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

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

The description is front-loaded with the core purpose and clearly divides single-market and basket behaviors. It is long and dense, but every sentence carries meaningful detail about parameters, outputs, or risk rationale. It could be tightened slightly without losing value, but it is well structured and not padded.

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

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

Given the tool's complexity—two modes, four parameters, no output schema—the description is remarkably complete. It covers mode selection, parameter semantics, output fields, risk, and the specific trigger conditions for use. The absence of an output schema is compensated by a thorough enumeration of returned values.

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

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

Even though schema coverage is 100%, the description adds rich meaning beyond the schema. It explains the dual meaning of size_usd (spend vs target proceeds for single-market, settlement notional for basket), clarifies side defaults and auto behavior, and differentiates market vs event modes with URL/slug handling. This goes well beyond the bare schema descriptions.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific action on a defined resource. It also distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly positioning itself as the pre-trade validation step.

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?

Extremely clear usage context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket) and when each applies. However, it does not explicitly state when NOT to use the tool or name direct alternatives, so it falls just short of a 5.

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

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

The description discloses compatibility_warning conditions, temporal_alignment, and skipped_cross_type/subtype semantics, which go far beyond the readOnlyHint/openWorldHint annotations. It also warns about the rarity of real spreads, adding transparency 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 and well-structured with sections for modes, response, and safety fields, but its length is substantial for an agent to parse. Still, every sentence adds value, so it earns a high 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 no output schema, the description thoroughly explains the response fields (leg-by-leg prices, spread_pp, compatibility_warning, temporal_alignment, skipped counters) and edge cases, making it a complete reference for such a complex tool.

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

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

The schema covers all 3 params with descriptions, but the description adds meaning by explaining the two modes, how explicit tickers override topic-mapped sides, and provides examples in the schema. This goes beyond what the schema alone provides.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly stating the tool's function. It goes beyond a generic verb by detailing the two-venue comparison, and the sibling context (polymarket_arbitrage, polymarket_edges) makes it distinct.

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

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

It explicitly defines two operational modes ('TWO MODES') with pre-mapped shortcuts and custom pairings, and warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning, guiding when to trust the output. The mode descriptions provide clear usage context, though it does not explicitly compare to sibling tools.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context about scoping ('Scoped to your identifier') and the purpose of avoiding re-derivation. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with no redundancy. It front-loads the primary action, then provides use cases and scoping. Every sentence adds necessary 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 tool with strong annotations and schema coverage, the description covers purpose, usage, scoping, and related tools. It implies return values ('retrieve a value' and 'list all saved keys'), which is sufficient given the tool's simplicity.

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

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

The input schema fully documents the single 'key' parameter (100% coverage), but the description enriches it by explaining behavior when omitted ('list all saved keys') and providing context about how values are saved ('via remember'). This adds meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys'. It uses specific verbs (retrieve/list) and identifies the resource (saved values/keys), and distinguishes itself from siblings by explicitly referencing 'remember' and 'forget'.

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

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

The description provides clear use cases ('use to look up context the agent stored earlier') and mentions complementary tools ('Pair with remember to save, forget to delete'). However, it does not explicitly state when not to use this tool, so it falls short of a full 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 description explicitly describes a mutating behavior with mark_read:true ('flag returned events read'), while annotations declare readOnlyHint=true. This is a direct contradiction with the read-only hint, so per rules the score is 1.

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

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

Three well-organized sentences, front-loaded with the primary purpose. Each sentence provides distinct value (return format, filtering, mark_read behavior, alternative access), with no wasted words.

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

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

Given no output schema and 5 optional parameters, the description covers return payload contents, filtering semantics, mark_read state change, polling suitability, and a fallback endpoint. This is sufficient 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% with descriptions for all 5 parameters, and the description adds meaningful context beyond the schema: it explains the consequence of mark_read (next call only shows newer ones) and gives a concrete example for the type filter. This exceeds the baseline of 3.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with specific verb 'Pull' and resource 'fired events from your subscription feed'. It also details return contents (source, citation_uri, raw payload) and filtering options, distinguishing it from siblings like recent_changes.

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 contextual guidance: mentions polling suitability and offers an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools like recent_changes, so it stops short of full when/where-not guidance.

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

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

The description discloses significant behavior beyond annotations: it fans out to SEC EDGAR, GDELT, GNews, and USPTO; explains fallback logic (GNews on rate limits/5xx); notes the PatentsView API sunset causing soft-fails; and describes the return structure (changes[], total_changes, citation URIs). This complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is dense but well-structured: it leads with use-case examples, then explains sources and fallbacks, parameter behavior, return format, and ends with an alternative tool pointer. While slightly long, every sentence contributes useful information without redundancy, making it appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (multiple external sources, fallbacks, date parsing, return format) and no output schema, the description is remarkably complete. It covers all key aspects: inputs, output structure, source-specific behavior, failure modes, and explicit alternative routing. No significant gaps remain.

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

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

Schema coverage is 100% for all three parameters, so the baseline is 3. The description repeats parameter values and adds the context that `since` accepts ISO dates or relative shorthand (already in schema) and that `type` currently only supports "company". It does not add meaningful semantics beyond what the schema already documents, so a 3 is appropriate.

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

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

The description clearly states what the tool does: it provides a change feed for a company over a specified time window, aggregating filings, news, and patents. It uses specific verbs and resources ("change feed") and distinguishes itself from sibling tool entity_profile by explicitly saying to use that instead for static profiles.

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 extensive usage context: example queries ("What's new with X"), acceptable date formats, source fallback behavior (GDELT→GNews), and explicit guidance to use entity_profile for static profile needs. It also mentions the tool works in one parallel call and includes typical monitoring suggestions like "30d or 1m".

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 context beyond annotations: key-value scoping by identifier, persistence duration for authenticated vs anonymous sessions. Aligns with idempotentHint and destructiveHint, no contradictions.

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

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

Four sentences, front-loaded with the core action, and every sentence adds value—purpose, usage, storage details, and related tools. 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?

For a simple two-parameter tool with no output schema, the description covers purpose, usage triggers, storage semantics, persistence, and companion tools. Fully sufficient 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 covers 100% of parameters, and description adds examples of valid keys ('subject_property', 'target_ticker') and values. It doesn't fully explain edge cases but enriches the schema meaning.

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

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

The description clearly states the tool saves data for later reuse, with specific examples of what to keep. It distinguishes itself from sibling tools recall and forget by explicitly mentioning pairing with them.

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

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

It provides explicit when-to-use guidance with examples ('resolved ticker, target address') and tells the agent to pair with recall for retrieval and forget for deletion, covering 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, idempotentHint, and non-destructive behavior, so the description adds value by disclosing internal behavior: it cascades through several lookup endpoints and produces citation URIs (pipeworx://edgar/company/{cik} and pipeworx://rxnorm/{rxcui}). It also notes 'auto-disambiguated' for company lookups. However, it does not mention potential failure modes, such as no-match handling or ambiguous names.

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 a typical tool description, but it earns its length by covering two entity types, multiple output fields, and usage guidance in a compact form. It front-loads with example queries, which makes the purpose immediately clear. There is no redundant information or fluff.

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

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

There is no output schema, so the description must convey return values, which it does thoroughly: it lists the exact fields returned for each type, the source databases, and the citation URIs. It also explains the internal cascade behavior. The only gap is that it doesn't explain error behavior or output formatting, but given the moderate complexity, the description is sufficiently complete for an agent to understand how to use 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%: both parameters have detailed descriptions. The description adds extra context beyond the schema by specifying what each type returns (company yields ticker + CIK + company_name; drug yields RxCUI + ingredient + brand) and emphasizing that the value is a 'user-spoken NAME' that can be in various forms (ticker, CIK, brand, generic). This goes beyond the schema's structural definitions.

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: it resolves a user-spoken NAME to the canonical/official identifier (e.g., ticker, CIK, RxCUI). It provides specific examples of queries, lists the two supported entity types with their respective output fields and data sources, and explicitly positions it as the first stop when a name is known but an ID is needed. This distinguishes it from sibling tools like 'entity_profile' or 'compare_entities'.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that using it replaces 2-3 manual lookups, implying the alternative is manual multi-step lookups. While it doesn't name alternative tools, the directive 'Use FIRST' conveys priority over other tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds value beyond these by disclosing the probing mechanism (uses ai_visibility_check), the ranking behavior, and the output fields (score, confidence, signal density). This is useful behavioral context not available in annotations. It doesn't contradict annotations.

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

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

The description is three sentences long and every sentence contributes: purpose, process, use case, and output. It is front-loaded with the main action and ends with a concrete output summary. 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?

Even though there's no output schema, the description explicitly states what will be returned (ranked list with score, confidence, signal density per entity), covering the most important output aspects. It also explains the underlying dependency on ai_visibility_check. The entity count range is in the schema, and the description covers the tool's role in competitive audits, making it sufficiently complete for an agent to invoke confidently.

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

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly, including the special meaning of the first entity and optional models/_apiKey/context. The description largely restates the entity semantics ("your brand + N competitors") without adding new parameter-level insight. Thus the baseline 3 is appropriate; no extra compensation needed.

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 with a specific verb ("Compare") and resource ("AI visibility") across multiple entities. It distinguishes itself from the sibling ai_visibility_check by explicitly mentioning side-by-side comparison and ranking, and from compare_entities by focusing on AI presence. The phrase "Probes each entity ... with ai_visibility_check, ranks by score" further clarifies the unique behavior.

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

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

The description gives a clear use case: "Useful for competitive AI-marketing audits" and provides an illustrative example question. It implies when to use this tool over single-entity alternatives, though it doesn't explicitly name when-not-to-use conditions or alternatives. The context is strong enough for an agent to select this tool appropriately.

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

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

The description adds substantial behavioral context beyond the annotations: it explains the composite nature of the call, the partial failure behavior with sources_failed listing timeouts, and the latency characteristic of bundlephobia's first measurement on a new version (5-30s). This is exactly the kind of operational detail that an agent needs to set expectations and interpret results. The description is consistent with the readOnlyHint, openWorldHint, and idempotentHint annotations, with no contradictions.

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

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

The description is long but every sentence contributes meaningful information: purpose, use cases, return structure, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and uses a logical flow from what it does, to when to use it, to what it returns, to caveats. 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?

Without an output schema, the description fully enumerates the return shape (summary block with specific fields, per-advisory details, links, alternative versions). It also addresses the main edge cases: non-NPM ecosystems, partial failures, and slow first measurements. For a composite tool of this complexity, the description is remarkably complete and 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?

The input schema already provides 100% coverage for both parameters (package and version) with clear descriptions, so the baseline is 3. The description adds minimal extra parameter semantics; it only implies that the package is an npm package and that versions can be checked in the context of bundlephobia timing. Since the schema carries the full semantic weight, the description does not need to compensate.

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

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

The description states a clear, specific purpose: a composite check for 'should I add this npm package to my project' that fans out across deps.dev and bundlephobia. It explicitly enumerates what each source contributes (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), which distinguishes it from an abstract or vague 'scan' tool. It also differentiates from potential alternatives like deps.dev:version for other ecosystems.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives an exclusion criterion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which tells the agent exactly when not to use this tool and what to use instead. This is textbook when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds valuable context beyond annotations: it returns doc SETS, not content, and clarifies the exact boundary of lookup. This behavior is not redundant with the annotations and helps the agent anticipate the tool's output scope.

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 purpose, includes an illustrative example, and an explicit alternative. Every phrase earns its place; there is no fluff or repetition of schema details.

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

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

For a simple read-only tool with one parameter and an output schema, the description fully covers what the tool does, its limitations, and the alternative path. It is complete for an agent to select and invoke the tool correctly, especially given the annotations and output schema boundary.

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 covers 100% of the parameter (query) with its own description, but the description supplements it with concrete examples ('python' → Python 3.x) and explicitly states that the match is a substring of the doc-set name. This reinforces the expected input format and meaning beyond the schema description.

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

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

The description clearly states the tool finds documentation SETS whose name matches a substring, and explicitly contrasts with search_index to avoid confusion. It uses a specific verb ('find'), resource ('documentation sets'), and scope ('name matches a substring'), 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 explicitly states when to use this tool (to locate doc sets by name) and when NOT to use it ('does NOT look up a function/method/API name'), and names the alternative tool: 'use search_index (slug + query)'. This provides direct usage guidance and disambiguates sibling 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 confirm read-only/idempotent behavior; description adds that the search is by substring and returns specific entries, not full documents. It also warns that valid slugs come from docs/search_docs, adding practical behavioral context. 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?

Two sentences plus examples convey purpose, usage, and key parameter semantics without fluff. Every clause earns its place and the structure front-loads the core verb+object.

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 annotations and output schema, the description covers purpose, key parameters, and how to obtain valid slugs. Minor gap is the undefined 'limit' parameter and lack of specifics about result limits or ordering, but overall sufficient for the tool's complexity.

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

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

Schema already describes slug and query; description adds that query is a substring and shows example values for both. However, the 'limit' parameter is never mentioned in the description and has no schema description, leaving its purpose ambiguous despite the schema examples.

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

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

Description clearly states it searches within a documentation set for specific entries (methods/functions/APIs/properties) by substring, distinguishing it from general search. The phrase 'THIS is the content lookup' and the instruction to get valid slugs from docs/search_docs specifically differentiate it from sibling tools that list docs or perform broader searches.

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 context for when to use (content lookup within a known doc set) and points to docs/search_docs for valid slugs, but doesn't explicitly mention alternatives like search_within or when not to use. The examples help clarify the intended use case.

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 annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral context: it returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char windows, and has a 200K char cap with truncation flagging. These details go beyond the annotations to describe the tool's internal mechanics and edge-case 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 packed with information in just three sentences: purpose, usage guidance, and technical specifics. It is front-loaded with the core function, avoids fluff, and every sentence earns its place. The structure flows logically from what to when to how.

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 adequately hints at the return format ('top-N passages with character offsets and similarity scores'). It covers the input parameter constraints (200K cap), edge cases (truncation flag), and differentiates from siblings. For a tool of this complexity, the description is complete and 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 description coverage is 100%, so the baseline is 3. The description reinforces the text cap and provides example queries, but it does not add significant new meaning beyond what the schema already states for each parameter. The added context about 'text you already pulled' and 'natural-language query' is present in the schema too, so no extra compensation needed.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record,' clearly distinguishing this from sibling tools like ask_pipeworx which search external sources. It also specifies the output (top-N passages, character offsets, similarity scores) and usage context (large records too big for the prompt), leaving no ambiguity about what this tool does.

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

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

The description explicitly states when to use it: 'Use when the record is too big to cram into the prompt,' and pairs it with ask_pipeworx_grounded, explaining the intended workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear guidance on when it is appropriate and how it relates to an 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?

Beyond the annotations, the description discloses important behavioral details: requires a Pipeworx OAuth account (anonymous/BYO cannot persist), phone must be verified, SMS 10/day cap, and webhook auto-disabled after 10 consecutive failures. This adds significant context beyond what annotations provide.

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

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

The description is dense and information-rich, using a long single sentence with semicolon-separated details. Every clause adds necessary info, though it could be broken into clearer list form. It is appropriately sized given the tool's complexity.

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

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

The tool has high complexity with 3 nested params, 5 types, and 3 delivery channels, yet the description covers all key aspects: types, delivery behaviors, auth prerequisites, rate limits, and what is returned. No output schema exists, so the description carries the full burden, and it succeeds.

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 descriptions are already detailed, but the description adds value by interpreting specific params (e.g., items:['5.02'] = officer change, topic:'fed' for polymarket_edge). These enrich the schema's more formal examples.

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: 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the new subscription id. This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context on when to use (for creating subscriptions) and includes requirements like OAuth account and phone verification, but does not explicitly name alternatives or exclusion scenarios. It implies usage by enumerating types and delivery options.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds beyond this by explaining that results are drawn from a live catalog of thousands of tools, and that each example includes the exact tool + argument shape. It also notes the output is category-bucketed, which helps the agent anticipate response structure.

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

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

The description is densely packed with useful information but is somewhat long and meandering. It front-loads example queries and clearly states the purpose early. Every sentence contributes, but the structure could be tightened; however, the richness justifies the 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?

The tool is simple (one optional parameter, no required arguments). The description fully explains what the output looks like (category-bucketed examples with tool+argument shapes), when to use it, and the parameter behavior. With strong annotations and full schema coverage, this description is complete for an agent to confidently invoke 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% (the `topic` parameter is described in the schema). The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and explaining the effect of omitting the parameter (cross-category spread). It reinforces the schema meaning without redundancy.

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: it is the onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It distinguishes itself from sibling tools like ask_pipeworx (which likely answers questions) by positioning itself as a discovery/guidance 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 description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This gives clear when-to-use guidance and implicitly contrasts with more direct action tools. It also explains the optional topic parameter for focused use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe, idempotent read operation. The description adds the scoping detail that categories are 'inside a doc,' but does not elaborate on output format, pagination, or edge cases. This provides moderate value 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 a single concise sentence that conveys the core purpose without unnecessary detail. It is front-loaded and well-structured for quick parsing.

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

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

For a simple tool with one parameter and an output schema, the description is minimal but not fully complete. It lacks usage context, clarification of what 'categories' are, and any mention of when to use this over sibling tools. Given the output schema and annotations, it is adequate but leaves room for improvement.

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 no description for the 'slug' parameter and 0% coverage. The description's phrase 'inside a doc' hints that 'slug' identifies a document, but it does not explicitly state this relationship. This partial compensation is adequate but not thorough.

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 'List categories inside a doc' clearly identifies a specific action (list) and resource (categories within a document). It is specific enough to distinguish from sibling tools like search_within or index, though it does not explicitly name alternatives.

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

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

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

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

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

The description goes beyond annotations by explaining that the row is deactivated, not deleted, and that historical events remain accessible via recent_alerts. This clarifies the exact side effects, which is valuable given the destructiveHint is false and readOnlyHint is false.

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 concise sentences with no redundant information. The first sentence states the action, the second explains the behavior. Every word 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 simple one-parameter mutation tool with a fully described schema, the description is sufficient. It covers the operation, side effects, and the relationship to recent_alerts. It does not specify the return value, but that is often implicit for such operations.

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

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

Schema already covers the id parameter with a clear description. The tool description adds the crucial nuance that the id must belong to the caller ('Ownership is enforced'), which is not in the schema. This enriches parameter semantics.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Cancel a subscription by id.' It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation. The ownership note adds clarity about 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 implies when to use it (to cancel your own subscription) and explicitly mentions ownership enforcement, which signals not to use it for others' subscriptions. It does not explicitly contrast with alternative tools (e.g., list_subscriptions) but provides sufficient context for typical use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral detail: it returns a verdict with enumerated possible values, the actual value with a citation, and reasoning. It also explains the two processing paths (SEC EDGAR vs grounded pipeline), which is useful context beyond the annotations.

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

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

The description is dense but well-organized. It starts with trigger phrases, states the core purpose, then details routing, return values, and benefits. Each sentence adds substantive information, though it could be slightly tightened without losing value.

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

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

For a tool with no output schema, the description does a commendable job explaining the return values (verdict, actual value with citation, reasoning). It also covers the two routing paths and input examples. It doesn't explain edge cases like unsupported claims, but overall it's sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds extra semantics for tolerance_pct: it overrides the implied tolerance, recommends 1-2 for hallucination detection, and notes the default is implied by wording and capped at 5. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verb+resource ('validate claim') and provides numerous trigger phrases and examples. It distinguishes itself from sibling tools by focusing on fact-checking, not general Q&A or research.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance: company-financial claims go through SEC EDGAR, while all other claims fall through to the grounded pipeline. While it doesn't name alternative tools explicitly, the usage context is clear and actionable.

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