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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: it mentions routing across 5,706 tools, returning pipeworx:// citation URIs, working on every tier, and being a fast single call. This gives the agent a clear expectation of behavior and result format.

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

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

The description is longer than average, but every section earns its place: usage preference, domain scope, examples, default-entry guidance, and escalation alternatives. It is front-loaded with the most important routing instruction and uses clear signposting like 'START HERE' and 'Step up only when needed.'

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

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

For a generic question-answering tool with no output schema and a single free-form parameter, the description covers what domains it handles, what it returns, how it differs from key siblings, and that it works on every tier. It could mention latency or error behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the parameter descriptions explain that the sole input is a natural-language question with multiple accepted aliases. The description adds illustrative examples but no new semantic detail about the parameter beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description names a specific action — routing factual questions to verified sources and returning structured answers with citations — and clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It lists concrete domains and example queries, making it unmistakable what the tool is for.

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

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

It explicitly says to prefer this tool over web search, marks it as the default entry point, and gives precise step-up conditions for ask_pipeworx_grounded and deep_research. Example prompts and the note about news routing provide strong guidance for when to invoke it.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description goes further by disclosing that candidate routing improvements may be live under test, that none are active currently, and that it is a full working router with no fallback. This gives an agent a precise behavioral model 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 compact and front-loaded with the core identity, then details current status and usage. The long date and retirement detail slightly increases length but provides useful current-context information, so this is strong but not maximally concise.

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

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

For a universal router with no output schema, the description covers what the tool is, how it behaves, when to use it, and what to expect in terms of arguments and response shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with all parameter aliases documented. The description adds no parameter-specific semantics beyond noting that arguments are identical to ask_pipeworx, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx and a universal router that accepts natural language questions and routes to 5,706 tools. It explicitly distinguishes itself from the stable ask_pipeworx by noting it is the experimental edge, so an agent can tell them apart.

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 to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It does not explicitly list when-not-to-use scenarios or name grounded variants as alternatives, but the guidance is actionable and clear.

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

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

Annotations cover read-only, open-world, and idempotent traits, so the description's job is to add behavioral depth, and it does: success returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, failure returns explicit refusal reasons, extra LLM call cost is disclosed, and the grounding constraint is clearly explained. No contradiction with annotations; it reinforces 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?

Long but every sentence earns its place: front-loaded purpose, mechanism, return contract, usage conditions, and cost tradeoff. The density is justified by the tool's behavioral complexity and high-stakes context.

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

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

Despite lacking an output schema, the description fully specifies the return shape and all refusal_reason variants, which is the critical contextual information an agent needs. It also covers routing scope, cost, and when to avoid this tool, making it complete 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?

Schema coverage is 100% and the schema already documents the question parameter and all aliases. The description adds no new syntactic detail beyond mentioning natural-language input, so the baseline 3 applies; the schema carries the parameter-semantics burden.

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

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

States a specific verb ('answer') and resource ('mode') with a clear differentiator: hallucination-resistant extraction using only tool results. Explicitly distinguishes itself from ask_pipeworx while naming the shared routing mechanism, so an agent can tell this apart from siblings without opening schemas.

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: high-stakes reads, quoted/cited/acted-on answers, domains where invention is unacceptable (financial, legal, medical, public statements). It also names the cheaper alternative ask_pipeworx and states the preference for casual lookups, leaving no ambiguity about 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 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes well beyond them by disclosing the account requirement, paid tier for thorough depth, expected latency of 15-90 seconds, and the guarantee that findings are 'never invented' with explicit gaps[] for unanswered facets. It also discloses the citation guarantee: a citation_uri is present only when resources/read can actually serve it. No contradiction with annotations exists.

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

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

The description is long but dense, front-loading the critical account requirement and the preferred alternative before explaining the core mechanics. Every sentence adds information such as source types, parallel routing, return packet contents, gaps handling, citation fetchability, contradiction scans, and latency. It is not bloated, though it could be slightly tightened without losing context.

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

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

There is no output schema, so the description carries the full burden of explaining the return value, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites, pricing, latency, and scenario-based routing to siblings, making the description fully sufficient for an agent to select and invoke this tool.

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

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

Schema coverage is 100%, so the input schema already documents both question and depth. The description adds value by explaining that broad/multi-part questions are acceptable, that depth:'standard' re-angles unanswered gaps, and that depth:'thorough' additionally chases leads and requires a paid plan. This supplements the schema's enum descriptions without fully replacing them, justifying a score above the baseline.

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

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

The description opens with a clear verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' with explicit examples of source categories. It also distinguishes itself from siblings by stating 'this is NOT open-web search' and positioning itself for broad/multi-part questions, while naming ask_pipeworx as the alternative for single lookups and current news.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also gives when-not-to-use guidance for breaking or colloquial current news, and even provides an account-based fallback: if not signed in, use ask_pipeworx. This is model-level routing guidance, not just tool description.

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?

Despite annotations being all false (no safety hints), the description discloses substantial behavioral context: rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the anonymous filing workflow ('Filing without an account returns a claim_token'), how to follow up ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and expected impact ('The team reads digests daily'). No annotation contradiction exists.

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

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

The description is long but every sentence carries unique information. It is front-loaded with a clear purpose, then proceeds logically through use cases, exclusions, follow-up mechanics, and operational constraints. No redundant or vague phrasing; each clause earns its place in a well-structured sequence.

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 tool with no output schema, the description fully covers the interaction model: what to file, how to file anonymously, how to retrieve the status, rate limits, and cost. It also clarifies what not to do (report other servers' tools, paste user prompts). This is complete enough for an agent to correctly invoke and follow up on 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%, so the baseline is 3. The description adds extra semantic value for parameters: it explains the claim_token lifecycle beyond the schema ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and provides content guidance for message ('don't paste the end-user's prompt'). This goes beyond the schema's parameter descriptions, earning a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly distinguishes itself from other MCP servers: 'if the tool came from a different MCP server... file it with that server instead.' This makes the purpose unmistakable and differentiates it from sibling tools 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?

Usage guidance is explicit and covers when to use ('Use when a tool returns wrong/stale data...') and when not to use ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). It also tells users how to confirm scope ('Pipeworx tool names are the ones this connection lists') and what content to include ('Describe the issue in terms of Pipeworx tools/packs'). This is exemplary alternative-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?

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?

Goes well beyond the readOnly/idempotent annotations by exposing non-obvious runtime behavior: compatibility_warning and compatibility_codes can be non-empty even when pairs exist, unknown legs are never paired, skipped counters exist, temporal alignment is returned, and both modes interact with override semantics. This is exactly the kind of nuance an agent cannot infer from the schema or annotations.

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

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

The description is long but dense and logically ordered: purpose, modes, response shape, safety fields, and final caveat. Every sentence carries useful information for a tool with no output schema. Slight lack of bullet/structural formatting and the density of caveats prevent a 5.

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

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

With no output schema, the description carries the full burden and covers response fields, top_spreads_pp interpretation, compatibility codes, skipped categories, low-confidence pairs, and temporal alignment. It also warns about the frequency of real tradeable spreads. An agent has enough context to call the tool correctly in either mode.

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

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

Schema coverage is 100%, so the base expectation is a 3. The description adds meaningful higher-level semantics: topic mode auto-fetches matching events on both venues, explicit mode takes a kalshi_event_ticker plus a polymarket_event_slug, and explicit values override the topic-mapped side. It clarifies how the parameters work together rather than just repeating their schema declarations.

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

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

States it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with a clear verb and resource. The two input modes are described immediately, and the resource is distinct from Polymarket-only sibling tools by its first sentence. There is 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?

Clearly explains the two modes: topic shortcuts for rapid pre-mapped access and explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning and that 'pre-mapped ≠ tradeable.' It does not explicitly name alternatives or give a crisp 'when not to use this' rule, though the usage context is otherwise clear.

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

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

Annotations already 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 readOnly=true, idempotent=true, destructive=false. The description adds valuable context beyond that: it explains graceful degradation when upstream sources are unavailable, the cascading internal lookups, and that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted. There is no contradiction with annotations.

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

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

The description is verbose and dense, which is justified by the tool's complexity. However, it could be restructured for quicker scanning (e.g., bullet points for supported types). The information is valuable, but the length reduces conciseness.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, graceful degradation) and the absence of an output schema, the description provides substantial context: it explains the return behavior (identifiers labelled by source, unresolved listed explicitly) and the cascading internal logic. The only minor gap is no explicit description of the response structure's keys, but overall it is complete enough for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description significantly enriches both parameters: for 'type' it explains the full cross-source identity spine for 'company' and the RxCUI+brand resolution for 'drug'. For 'value', it provides concrete examples (ticker, CIK, ISIN, name) and even explains edge cases like ISIN-to-LEI mapping for non-US entities. This far exceeds the schema's minimal descriptions.

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

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

The description opens with concrete query examples and explicitly states that the tool resolves user-spoken names to canonical identifiers required by other tools. This clearly distinguishes it from siblings 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 contains the explicit directive 'Use FIRST whenever you have a name but need an ID', which provides clear usage guidance. It also explains that the tool replaces 2-3 manual lookups, reinforcing when it is appropriate. However, it does not explicitly mention cases when the tool should NOT be used or describe alternative tools for different scenarios.

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, and idempotentHint; the description adds critical behavioral nuance beyond those flags. It explains the exact meaning of 'could_not_verify' (verification did not happen, carries verification_error, must not be treated as evidence) versus 'unsupported' (no source found), describes the percent-delta calculation for financial claims, and discloses the return structure including verdict, value, citation, and reasoning.

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: it starts with invocation phrasing, then routing logic, then output/error semantics, and closes with efficiency rationale. While a bit verbose, nearly every sentence carries operational value for the agent; a minor trim could improve clarity without loss.

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

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

With only 2 params and no output schema, the description compensates fully by specifying both input forms, the two routing paths, the verdict vocabulary, the return payload (value + citation + reasoning), and the critical error semantics. It is entirely self-contained for the agent to select and invoke the tool correctly.

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

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

The schema already provides descriptions for both params (claim and tolerance_pct), but the description adds significant extra context: concrete examples for claim, and for tolerance_pct it explains the override behavior, hallucination-detection use case, and default cap of 5%. This goes beyond the schema's basic type and range info.

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

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

The description opens with multiple natural-language invocation examples ('Is it true that…', 'fact check'), then states it performs natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools by describing two specific routing paths (SEC EDGAR structured fast path for company financials, grounded pipeline for all other claims) and mentions it replaces a 4–6 step chain of other tools.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear routing rules for financial versus non-financial claims. It also positions the tool as a replacement for sequential calls, but does not explicitly name sibling tools to avoid or exclude use cases, so not a perfect 5.

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