Bcrp Pe

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

Annotations already indicate read-only, idempotent behavior. The description adds context about the free default model and BYO-key for Anthropic, and clarifies payment responsibility, which aids transparency beyond annotations.

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

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

The description is concise, with four sentences covering action, options, return, and use cases. It is front-loaded with the primary action and efficiently uses space.

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 schema covers all parameters and annotations provide behavioral hints, the description offers a fairly complete picture including use cases and return format. Lacking output schema, it still provides enough detail for an agent to understand the tool's output structure.

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

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

Schema coverage is 100%, so the schema fully describes parameters. The description reinforces that models include 'workers-ai' and 'anthropic' and that '_apiKey' is conditional, but adds little new semantic information.

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

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

The description clearly states it probes LLMs about an entity and scores visibility (0-100) per model, with a specific return format. It distinguishes the tool's purpose from many siblings, though it does not explicitly differentiate from the similar 'scan_competitor_ai_presence' 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 mentions use cases like AI-marketing audits and pre-launch brand checks, and explains the default model and optional Anthropic requirement. It does not provide explicit guidance on when not to use the tool or mention alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add behavioral context. It adds that the tool routes to many internal tools, fills arguments automatically, returns a structured answer with citation URIs, and is characterized as 'one fast call.' 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 fairly long, but nearly every sentence earns its place: prefer-over-search positioning, domain list, trigger phrases, examples, and sibling routing. It is front-loaded with the most important decision guidance, though a little tightening could remove redundancy between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it.'

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

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

For a read-only tool with one required string parameter and no output schema, the description supplies enough selection and invocation context: what domains it covers, what question forms trigger it, what it returns, and which sibling to use next. A slightly more explicit return-structure example would be nice, but the current text is sufficient for correct use.

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

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

Schema description coverage is 100%, so the schema already documents the single question param and its aliases. The description adds value beyond the schema by giving concrete example questions ('current US unemployment rate', 'Apple's latest 10-K', 'active clinical trials for GLP-1') that clarify the expected natural-language input.

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

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

The description names a specific verb ('routes'), a resource (factual questions over 5,767 tools across 1506 verified sources), and an output (structured answer with stable pipeworx:// citation URIs). It also distinguishes itself from web search with 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' so an agent can clearly tell what this 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 gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and says to use it even when web search could answer. The later routing paragraph explicitly names sibling tools for extra verification, ambiguity, deep reports, entity lookups, lists, claims, memory, and subscriptions, making alternatives and conditions explicit.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it discloses the beta nature, that candidate routing improvements may be enabled live, the current status ('No candidate is active right now'), and that the tool is a full working router with no fallback. This is exactly the kind of stateful, decision-relevant detail annotations cannot 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 moderately long but every sentence contributes useful information: beta status, sibling relationship, current test state, explicit usage instruction, and a clarification that it is fully functional. It is front-loaded with the core definition and avoids fluff. Could be tightened slightly, but remains efficient.

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

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

For a routing tool with no output schema, the description covers everything needed to invoke it correctly: what it does, how it relates to the stable version, when to use it, and the current operational status. The parameter count and alias details are fully handled by the schema, so there are no gaps in the ability to select and call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters as aliases for 'question'. The description references 'same arguments' but adds no new semantics about parameter meaning or usage beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that dispatches questions to 5,767 tools. It names the specific resource, the verb 'ask', and explicitly distinguishes it from the stable sibling by describing the test-candidate mechanism. This leaves no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, and states that currently no candidate is active so it matches ask_pipeworx exactly. This is strong directional context for choosing it over the sibling.

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

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

Annotations already mark it read-only/idempotent/open-world, so the burden is lowered; the description adds valuable context: refusal with specific reasons, evidence as a verbatim quote, and the extra LLM call cost. No contradiction with the annotations is present.

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

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

The description front-loads the purpose, then provides the output contract, usage guidance, and cost trade-off in compact sentences. The routing details and refusal-reason list are not padding; each sentence earns its place.

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

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

There is no output schema, and the description fully supplies the return contract for both success and refusal, lists the refusal reasons, and states exactly when the tool should be preferred. With the schema covering the required question parameter, the agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, and every parameter is either the question or an alias for it, so the schema already carries the semantic load. The description adds no parameter-level syntax or format details, 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 names a specific function: a hallucination-resistant answer mode for high-stakes reads that routes like ask_pipeworx but extracts only from the fetched tool result. It is clearly distinguishable from the sibling ask_pipeworx by its grounded/refusal behavior.

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

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

It explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and names the alternative ('prefer ask_pipeworx for casual lookups') with the cost trade-off. The agent can select the tool without inference.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds extensive behavioral context: market resolution, classification, fan-out, response shapes, resolver contract, parent event extraction, news fallback handling, safety (low-confidence short-circuit, closed markets), liquidity warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose and input methods. Some details could be streamlined, but given the tool's complexity, the length is justified and organized.

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

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

For a 3-parameter tool with no output schema, the description is exceptionally complete. It covers input formatting, full resolution flow, output shape (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and even resolution rule risk (cancellation settlements). Every critical aspect for correct invocation is addressed.

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?

With 100% schema description coverage, the description still adds significant value: it explains depth options ('quick = 2-3 evidence sources, thorough = full fan-out'), market input formats in detail, and include_raw recommendations (false recommended to keep responses under ~20KB, true for full payloads when post-processing). This goes beyond the schema's basic type 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 starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes itself from sibling tools like validate_claim or compare_entities by focusing on Polymarket bets with Pipeworx data integration.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and fan-out examples, offering clear context. While it does not explicitly state when not to use it, the guidance is strong enough for an agent to decide.

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 rich behavioral details: off-calendar fiscal year handling, sorting by primary metric, return of paired data with citation URIs, and specific data fields for each entity type. This goes well 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 paragraph that is slightly long but every sentence adds value. It front-loads the purpose and usage guidelines, followed by specific details. Minor wordiness could be trimmed, but overall efficient.

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

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

Despite no output schema, the description thoroughly explains the return format (paired data + citation URIs, sorted). It covers both entity types comprehensively, and with 2 well-documented parameters and clear annotations, the description is 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%, so baseline is 3. The description adds meaningful context beyond the schema, such as max/min items, example values, and behavior differences between 'company' and 'drug'. This justifies a score of 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 clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single call. It explicitly contrasts with sequential single-pack lookups and lists trigger phrases, making the purpose unmistakable.

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

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

The description explicitly states that this tool should be preferred over sequential lookups when comparing entities, and provides specific trigger phrases. It also clarifies the entity types and their data sources, offering clear when-to-use guidance.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) are reinforced and far exceeded: the description details the findings-packet shape (verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation), the gaps[] never-invented guarantee, hop field, resolvable citation_uri, contradictions[] on standard/thorough, semantic excerpting, and latency (15-60s, up to ~90s). Nothing contradicts 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 front-loaded with the critical auth/tier gate and dense with useful operational detail, but it runs to roughly 350 words with visible corruption and repetition — e.g. the duplicated 'For a single lookup use ask_pipeworx instead' and awkward artifacts like '(gap recovery); depth:"thorough" additionally chases...' that read as mangled concatenation. Every sentence carries information, but the structure would benefit from a tightening pass.

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

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

With no output schema present, the description carries the full burden of explaining return values — and it does: findings-packet fields, gaps[], contradictions[], hop, citation_uri, excerpting behavior, latency, and auth fallback are all covered. For a high-complexity research tool with three depth modes, nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema coverage is 100% (question and depth are both described), so baseline is 3. The description adds real supplement: the paid-plan gating for depth='thorough', latency expectations per depth, 'multi-step questions resolve in one call', and question-style guidance ('compare X and Y's regulatory + financial exposure') that the schema's enum values alone don't convey.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call — this is NOT open-web search', plus the decomposition/parallel-routing mechanism. It clearly differentiates from siblings by naming what it is not (not open-web search) and by contrasting with ask_pipeworx for single 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?

Gives explicit when-to-use and when-not-to-use: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx instead.' Tier gating (quick/standard free, thorough paid) is also stated up front, so an agent knows the access precondition before invoking.

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, idempotent, non-destructive. Description adds that it returns top-N tools with full input schemas and curated examples, ready to call without a second lookup. No contradictions, and adds meaningful context about output 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?

Two sentences with front-loaded main purpose. Every sentence adds value: first defines the action, second details output and usage positioning. No redundant text.

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

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

For a discovery tool without an output schema, the description fully covers return value (tool names, descriptions, schemas, examples) and usage context (first call for many options). No gaps.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. Description mentions query as natural language and aliases, but adds little beyond the schema's own parameter descriptions. The limit parameter's defaults are covered by 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 discovers tools by describing data/task, distinguishing it from siblings by positioning it as a first-call meta-tool. The verb 'discover tools' combined with domain examples makes the purpose specific and unambiguous.

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

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

Explicitly says to use when browsing or discovering tools, and advises calling it FIRST when many tools are available. Lacks explicit 'when not to use' guidance, but the context strongly implies it's a preliminary step, not for direct answers.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by detailing fan-out across sources, `sources_used`/`sources_failed`, empty-section semantics, private-company `resolved:false` behavior, and the USPTO API sunset soft-fail. It also clarifies that an empty FDA section is expected for certain companies, preventing misinterpretation of results.

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

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

The description is long but appropriately dense for a tool with many sources and output sections. It front-loads user intents and the key preference directive, then systematically lists return fields and failure semantics. Some redundancy with the schema exists, but every major section 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 to rely on, the description fully enumerates expected return sections and their meanings. It covers input formats, source availability, failure modes, and edge cases such as private companies and patent-source soft-fails, leaving an agent with almost no ambiguity about invocation or result interpretation.

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

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

Schema coverage is 100% and the schema already explains accepted value shapes, but the description adds concrete examples, zero-padding guidance, and edge-case behavior for private companies. It reinforces that `type` values are interchangeable and clarifies what resolution means when passing a name.

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

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

The description opens with concrete user phrasings and immediately defines the tool as a "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes itself from "chaining single-pack SEC/XBRL/news lookups," which is the relevant alternative even if no sibling tool is named.

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 "ALWAYS PREFER" this tool over chaining single-pack lookups when the user asks for a holistic view, which is a clear when-to-use directive. It does not, however, state when not to use it or name a specific sibling tool to fall back to for narrow queries, leaving some exclusion guidance implicit.

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

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

Annotations already convey destructiveHint=true and idempotentHint=true. Description adds minimal behavioral context beyond what annotations provide, but does not contradict 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?

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

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

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

Tool is simple with one parameter and no output schema. Description covers purpose, usage context, and sibling links, making it fully informative.

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 already describes the 'key' parameter. Description does not add additional 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?

Clearly states 'Delete a previously stored memory by key' with specific verb and resource, and distinguishes from sibling tools 'remember' and 'recall'.

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 provides when to use: when context is stale, task is done, or to clear sensitive data. References sibling tools but lacks explicit when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral details (fetching, extracting title/description/links, emitting standard format) that are not in annotations, enhancing transparency 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 concise (approx. 100 words) and front-loaded with the action and purpose. Every sentence adds value, with no redundant information.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers all necessary aspects: input, process, output format, and use cases. It is complete for an agent to understand 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 both parameters described. The description does not add additional meaning beyond what the schema provides (though it implies the url parameter's role in fetching). 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 specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly states the resource ('llms.txt file for any URL'). It distinguishes from sibling tools by being the only one focused on generating llms.txt files.

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 lists use cases (client site indexing, personal project drafting, competitor auditing), providing clear context on when to use. However, it does not mention when not to use or compare directly with alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds beyond that by explaining returned data (series names + rows), code encoding (frequency suffix), and example working codes, enhancing behavioral understanding 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?

Description is fairly long but well-structured: starts with main purpose, then code rules, examples, format details, and language info. Every sentence adds value; slightly verbose but necessary given complexity.

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

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

No output schema, but description states return includes series names and aligned rows. Provides examples, frequency mapping, and URL for more codes. Lacks info on error handling or rate limits but sufficient for core use.

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

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

Schema coverage is 100% with descriptions, but the description adds significant value by providing concrete examples, format rules (e.g., 'daily YYYY-M-D'), and real well-known codes. This far exceeds basic schema info.

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

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

Description clearly states it retrieves time-series data from BCRP API, specifies exact tool use with series codes, and distinguishes itself from sibling tools which are unrelated (e.g., ask_pipeworx, deep_research). Verb 'get' + resource 'series' is specific.

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 instructions for using series codes with dash-joining, frequency constraints, optional start/end formats, and language. Lacks explicit 'when not to use' or alternative tools, but context is clear given sibling list.

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, destructiveHint=false, covering safety. Description adds the list of returned fields but no additional behavioral context beyond the annotations.

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

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

Two concise sentences that front-load the purpose and provide usage context. No unnecessary words.

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

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

For a low-complexity tool with one optional parameter and comprehensive annotations, the description is complete enough. It specifies return fields and usage context, though it could briefly mention relationship to subscribe/unsubscribe siblings.

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 a description for the only parameter. The tool description does not add additional meaning beyond the schema, which is adequate for a boolean parameter.

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 verb ('List'), resource ('the caller's active subscriptions'), and specifies the returned fields. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing existing subscriptions.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for use, though lacks an explicit when-not-to-use statement.

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

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

The description discloses important behavioral traits beyond the annotations: rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, team reads digests daily, and the claim_token return behavior. This is exactly the kind of context agents need and is not provided elsewhere.

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, every sentence adds distinct value: scope, use cases, exclusions, privacy guidance, workflow, rate limits, and cost. The main purpose is front-loaded, and the structure flows logically from what → when → how → constraints.

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

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

Given there is no output schema, the description fully covers the claim_token response mechanism. It also addresses all key operational details (rate limits, quota, routing, team review cadence) that an agent would need to decide when and how to use the tool. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter nuance: it specifies message length expectations and the claim_token usage pattern ('pass it back later'). It also frames context as optional structured information. This exceeds mere schema repetition.

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 object: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this feedback tool from sibling tools like ask_pipeworx by focusing on bug/feature/praise reporting.

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

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

Explicit usage criteria are provided: use for bugs, feature/data gaps, or praise, with clear exclusions for non-Pipeworx MCP servers ('file it with that server instead'). It also explains the claim_token flow for later follow-up, leaving no ambiguity about when and how to invoke the tool.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destuctiveHint=false. Description adds valuable non-obvious details: derived from CF analytics-engine, no PII, cached 5min-1h. 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?

Concise multi-sentence description front-loads the main result, lists use cases, and adds behavioral notes without redundancy. 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?

Tool has one optional parameter, no output schema, and simple read-only purpose. Description covers purpose, use cases, behavioral traits, and parameter guidance adequately. No gaps for the complexity level.

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

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

Input schema already fully describes the single parameter (window enum with examples and semantics). Description adds no further parameter details beyond what the schema provides. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window, giving a specific verb+resource (trending on Pipeworx). It distinguishes itself from the large set of sibling tools by focusing on aggregate usage signals.

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 lists three concrete use cases (discovering hot data sources, confirming canonical tool, seeing alignment) and mentions caching behavior. Lacks explicit when-not-to-use guidance, but the positive use cases 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds detailed behavioral context: Jaccard similarity threshold, placeholder fraction filter, fill check against CLOB depth, all consistent 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?

Description is information-dense but well-structured with key terms in caps. Every sentence adds value, though slightly lengthy for a quick scan.

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

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

Despite no output schema, description details response structure (opportunities, partition_check, fill check) and covers edge cases like similarity filtering and placeholder handling.

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

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

Schema coverage is 100%, but description adds extensive meaning beyond schema: explains event slug format, URL acceptance, internal logic for topic search, and semantic anchoring.

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 purpose as finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by describing unique features and modes.

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 on when to use each mode: no args for trending_scan, event for specific market, topic for cross-event scanning. Also advises against trading when realizable_edge_pp ≤ 0 and directs to polymarket_fill_risk for custom sizing.

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 extensive behavioral context beyond annotations (readOnlyHint, etc.), including caching strategy (KV 1h), detailed model families, edge calculation with slippage, Kelly fractions, and diagnostics. 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 very detailed and comprehensive but overly long and dense. It front-loads the purpose but includes extensive technical details that could be streamlined for quicker parsing by an agent.

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

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

Given the complexity (9 parameters, no output schema, multiple segments), the description is remarkably complete. It explains response structure, edge calculation, filters, diagnostics, and caching, compensating for the lack of output schema.

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

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

All 9 parameters are fully described in the schema (100% coverage), and the description adds significant extra context for each, such as slippage_pp explaining zero fees but typical bid/ask costs, and min_kelly clarifying it filters small opportunities.

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 Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by specifying its unique role in surfacing discrepancies for betting decisions.

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 it's built for 'what should I bet on today' and explains that agents discover opportunities without paging hundreds of markets. However, it does not compare directly with siblings or provide explicit when-not-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations: history depth bounded by 60-day TTL, snapshots written on cache-miss (gaps), decay from daily closes not intraday. This aligns with readOnlyHint and idempotentHint.

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

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

The description is well-structured with sections for args, response fields, and limits. Although lengthy, every sentence adds value; some minor redundancy could be trimmed but it remains effective.

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

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

Despite no output schema, the description thoroughly explains return fields (tracked, expired, snapshot_dates) with internal details. It covers all necessary information for a complex tool with two parameters, ensuring completeness.

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 adds value by explaining default values and constraints (e.g., max 30 for days) and clarifying that window is a snapshot family, which enriches the schema definitions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question. It distinguishes from siblings by focusing on time-series analysis rather than raw 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 provides clear context on when to use the tool (to understand edge longevity and decay) and describes the response structure. While it doesn't explicitly state when not to use, the context implies alternatives like polymarket_edges for current snapshots.

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 confirm read-only, idempotent, and non-destructive behavior. Description adds critical behavioral details: walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), computes capture ratios, and identifies thin legs and forced directional risk. 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?

Well-structured with clear sections for single-market and basket modes, use cases, and risk warnings. Slightly verbose but every sentence adds value; no filler. Could be trimmed slightly without loss of 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?

Despite no output schema, the description comprehensively covers all returned fields, including verdict, fill details, profit, and risk indicators. It explains both modes thoroughly and anticipates failure modes (unhedged positional risk). Complete enough for an agent to understand when and how to 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 description coverage is 100% (all 4 parameters described). Description adds meaning beyond schema: explains size_usd as 'settlement notional' in basket mode, clarifies default side behavior ('auto' from partition sum), and gives usage context for parameters across modes. Some redundancy with schema but adds practical context.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against order-book depth, with two distinct modes (single-market and basket). It specifies return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a prerequisite 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?

Explicitly states when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and why (theoretical overround not capturable, partial fills create directional risk). Also clarifies the requirement to provide either 'market' or 'event'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description aligns with them. It goes far beyond annotations by disclosing the fees issue, the meaning of null temporal_alignment, compatibility_codes semantics, unclassified leg handling, and the caveat that spreads are gross, not net tradeable edge. This is exceptional transparency for a complex cross-venue matcher.

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 and dense, but it front-loads the core purpose and organizes content into recognizable sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes). There is some repetition, such as re-explaining temporal flags and the identical-matcher point, so it is not maximally tight, but every major section earns its place 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?

There is no output schema, so the description carries the full burden of explaining the response shape, safety fields, flag meanings, skipped-pair counters, and limitations. It covers leg prices, top_spreads_pp, compatibility_warning, compatibility_codes[], temporal_alignment, fees_note, and unclassified/skipped behavior. For a tool this complex, the description is remarkably 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%, so the baseline is 3. The description adds meaning by explaining the two modes, how both modes run the same token-overlap matcher, and that explicit parameters override the topic-mapped side. It could have stated mutual exclusivity or combination rules more explicitly, but it clearly enriches 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, which is specific and immediately understandable. It does not explicitly compare itself to sibling tools like polymarket_arbitrage, so it stops short of the top score, but the resource and function are unambiguous.

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

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

The description gives clear context for when to use the topic shortcuts versus explicit event pairings, and explicitly warns that pre-mapped topics are not automatically tradeable. It does not mention alternative sibling tools or state when not to use this tool, so it lacks explicit exclusions/alternatives but provides solid operational 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?

Description adds scoping and pairing context beyond annotations. Annotations already indicate readOnlyHint, idempotentHint, destructiveHint; description reinforces the safe, read-only nature and explains the coupling with remember/forget.

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 action and dual purpose. No wasted words; every sentence adds essential 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?

Given one optional parameter, full schema coverage, clear annotations, and no output schema, the description is complete. It covers both retrieval and listing, and pairs with sibling tools.

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

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

Schema coverage is 100% with a brief description. Tool description enhances by explaining the effect of omitting the key (list all keys) and adding scoping context, going beyond the schema's minimal 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 clearly states the tool's dual functionality: retrieving a specific saved value or listing all keys. It provides concrete use-case examples (ticker, address, notes) and distinguishes from sibling tools 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?

Explicitly describes when to use (look up previously stored context) and implies when to list keys (omit argument). Mentions scoping to an identifier. Lacks explicit 'when not to use' but provides sufficient 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 states setting mark_read:true flags events as read, implying mutation. However, annotations declare readOnlyHint=true, indicating no state modification. This is a direct contradiction, severely harming 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 three sentences, structured with a clear purpose first, followed by key features and alternatives. Every sentence adds meaningful information 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?

Despite no output schema, the description details return fields (source, citation_uri, payload) and covers all parameters. It also addresses polling behavior and provides an alternative REST endpoint, making it self-contained for agent usage.

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 adds value by giving examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explaining mark_read's effect, which goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying it returns recent alerts with source, citation_uri, and raw payload. It distinguishes from siblings like list_subscriptions by focusing on alert events.

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

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

The description explains polling works fine and points to a REST API alternative for scripts/dashboards. It provides guidance on using mark_read for state management but does not explicitly exclude other use cases or mention when to use alternative 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: fans out to multiple sources, fallback mechanism (GNews when GDELT rate-limited), soft-failure for USPTO, and output format (changes[] grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is well-structured and front-loaded with example queries. It packs significant detail efficiently, though could be slightly more concise without losing essential 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?

Despite no output schema, the description thoroughly explains output format (changes[] grouped by source, total_changes, URIs), fallback behaviors, and failure modes. Given the tool's complexity (multiple sources, fallbacks, soft-failure), the description is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds useful context beyond schema: 'since' accepts relative shorthand and recommends '30d' or '1m'; 'value' explains ticker or zero-padded CIK; 'type' limited to 'company'. This additional guidance justifies 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 clearly states the tool is a change feed for a company, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from sibling tool 'entity_profile' by saying 'Use entity_profile instead when you want the static profile...'.

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

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

The description provides explicit example queries ('What's new with X', 'latest on Y', etc.) and clearly states when to use an alternative ('Use entity_profile instead...'). It also gives guidance on the 'since' parameter ('Use "30d" or "1m" for typical monitoring').

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

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

Beyond annotations (idempotent, not read-only/destructive), description adds scoping by identifier, persistence differences (authenticated vs anonymous, 24-hour limit), and that it stores key-value pairs. 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?

Efficient, front-loaded sentences. Every sentence adds value, no wasted words. Properly structured with purpose, usage, persistence, and sibling references.

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 simple tool (2 params, no output schema), description fully covers purpose, usage, persistence, and relationships to siblings. No gaps.

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

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

Schema covers both parameters completely (100% coverage). Description reiterates 'key-value pair' but doesn't add significant meaning beyond what schema descriptions provide.

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

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

Clearly states the tool saves data for reuse across conversations/sessions. Distinguishes from siblings 'recall' and 'forget' by specifying it stores key-value pairs.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward...' and provides examples. Mentions pairing with recall and forget for retrieval/deletion, giving clear usage 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 adds substantial behavior beyond annotations: it mentions cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity behavior returning `figi_candidates`, explicit `unresolved` output, and multi-source labeling. This fully contextualizes the read-only/idempotent annotations.

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

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

The description is long and dense, but the length is justified by the complexity of supported types and edge cases. It is front-loaded with examples and usage directives, and later details are organized by entity type.

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 still explains what results are returned: resolved identifiers, unresolved fields, `figi_candidates`, and source provenance. It also covers fallback behavior and the tool's equivalence to multiple manual lookups, giving an agent enough context to invoke and interpret 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?

Although schema coverage is 100%, the description adds critical meaning: value must be the entity name only, not the full noun phrase; provides bond-issuer examples; clarifies how ISIN resolves to legal entity; and disambiguates company vs drug types. This goes well 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 names a specific verb ('resolve') and resource ('canonical/official identifiers') and illustrates it with concrete user queries. It clearly differentiates from siblings by stating that other tools require IDs while this tool supplies them from names.

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

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

It gives explicit direction: 'Use FIRST whenever you have a name but need an ID.' It also explains what should and should not be passed for `value`. However, it does not name sibling tools that might otherwise compete (e.g., entity_profile, compare_entities), so the when-not-to-use guidance is implicit rather than explicit.

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

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

Description reveals the internal mechanism: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized. This adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint) by explaining the composite multi-probe logic and output 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?

Description is four sentences with no fluff. First sentence captures purpose, second explains mechanism, third provides use case, fourth describes output. Perfectly front-loaded and structured.

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

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

Even without an output schema, the description fully informs the agent of the output format (ranked list with score, confidence, signal density). Combined with full schema coverage, the tool definition is complete for an 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 description coverage is 100% (all 4 parameters have descriptions). The description adds value by explaining that the first entity is treated as the 'subject' for narrative, which is not in the schema. This extra semantic detail justifies a score above baseline 3.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side', specifying a unique verb (compare) and resource (AI visibility). It distinguishes from sibling tool ai_visibility_check (single entity) by emphasizing multi-entity comparison.

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

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

Tool is positioned for competitive AI-marketing audits with an example question ('does Claude know about us as well as our competitors?'). Usage context is clear, though it does not explicitly list when not to use or enumerate 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds value by detailing partial failure behavior (bundlephobia timeout), return fields, and graceful degradation. Minor gap: no mention of caching or external calls beyond the description.

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?

Description is a single paragraph but front-loaded with purpose and key details. Every sentence adds value. Could be slightly more structured with bullets, but it remains concise and informative.

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

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

Despite no output schema, the description lists all return fields (summary block, advisory details, links, etc.) and explains partial failure. This is sufficient for a complex tool with good annotations.

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

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

Schema covers both parameters fully, so baseline is 3. Description adds semantics: scoped packages are accepted, default version is latest, and version format example. This provides context beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, combining deps.dev and bundlephobia data. It specifies the verb (scan/check), resource (npm package), and distinguishes from other tools by being a one-call composite.

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 guides when to use: 'when an agent asks 'is X safe / popular / small''. Also clarifies scope: 'NPM ecosystem only in v1' and states alternatives for other ecosystems. This helps the agent choose correctly.

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

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

The description adds substantial behavioral context beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K) with truncation flag. No contradiction with annotations (readOnly, idempotent, etc.).

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 packed with information, no wasted words. Front-loaded with the core purpose, then provides usage context and technical details. Excellent structure.

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

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

Despite no output schema, the description fully explains what is returned (passages with offsets, scores, truncation flag). Covers input constraints, embedding details, and pairing advice. Complete for a tool of this 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 covers all 3 parameters with descriptions (100% coverage). The description adds value by explaining what the tool returns (passages with character offsets and similarity scores), which compensates for the lack of an output schema. However, it doesn't add per-parameter details beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record with a specific verb and resource. It distinguishes from sibling tools by contrasting with ask_pipeworx_grounded, and emphasizes the use case when a record is too large for the prompt.

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

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

Explicitly says when to use ('too big to cram into the prompt') and provides a pairing suggestion with ask_pipeworx_grounded. While it doesn't list explicit alternatives or when-not-to-use, the context is clear enough for an agent to decide.

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 indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds critical behavioral details beyond annotations: OAuth requirement, persistence of subscriptions, delivery channel limitations (SMS cap, webhook auto-disable), and no contradiction is present.

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

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

The description is front-loaded with the main action and progressively details types and delivery. Every sentence adds value, though it is slightly verbose. Still efficient for the 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 (3 params, nested objects, multiple types, no output schema), the description covers all key aspects: purpose, auth, types, delivery options, limits, and behavioral consequences. It enables correct invocation without gaps.

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

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

Schema coverage is 100%, providing baseline 3. The description enriches parameters with concrete examples (e.g., sec_8k with items codes) and constraints (phone verification, daily cap), adding significant 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 begins with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation of subscriptions.

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

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

It explicitly states the requirement for a Pipeworx OAuth account and lists supported subscription types with examples. While it doesn't explicitly contrast with alternatives, the context is clear enough for an agent to choose this tool for creating subscriptions.

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 as safe. The description adds value by detailing the return format (category-bucketed example questions with exact tool+argument shape) and the optional topic parameter's effect. No contradictions with annotations.

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

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

The description is front-loaded with example queries and packs essential information into a few sentences. It is slightly verbose but every sentence adds value. No redundancy.

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

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

Given the tool is an onboarding entry point with one optional parameter and no output schema, the description is complete. It covers purpose, usage, and return format. It also references related meta-tools for further learning.

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 'topic' has 100% schema coverage. The description enhances understanding by listing example values (finance, pharma, etc.) and clarifying that omitting it gives a cross-category spread. This adds practical meaning beyond the schema definition.

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

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

The description clearly states the tool's purpose as an onboarding entry point for agents wanting to know what to ask Pipeworx. It provides example queries ('What can I ask?', 'give me ideas') and specifies it returns category-bucketed example questions with exact tool+argument shape. It distinguishes from siblings by positioning itself as the first tool to use when learning Pipeworx's capabilities, and by contrasting with 'discover_tools' and other meta-tools.

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

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

The description provides clear guidance: call with no arguments for full spread, or pass a 'topic' to focus. It explicitly recommends using this tool 'FIRST when you do not yet know what Pipeworx can do for you'. While it doesn't explicitly state when not to use it, the context is sufficient for an AI agent to make a reasonable choice.

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 significant context beyond annotations: it explains the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This complements the annotations (destructiveHint=false, idempotentHint=true) without contradiction.

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

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

The description is two sentences with no redundant information. The action is front-loaded, and every sentence adds value: first states the action and ownership, second clarifies the behavioral outcome.

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 mutation tool with one parameter and full annotations, the description covers purpose, behavior, ownership constraints, and side effects. No output schema is needed, and historical linkage is provided.

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 for the single parameter 'id', including a clear description. The tool description does not add additional parameter semantics, meeting the baseline for high schema coverage.

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

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

The description clearly states the verb 'Cancel a subscription' and identifies the resource by id. It distinguishes from siblings like 'subscribe' and 'recent_alerts' by explaining the outcome (deactivation vs deletion) and linking to historical availability.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. It implies not to use for others' subscriptions but does not enumerate alternatives beyond the mention of recent_alerts.

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 the annotations (readOnlyHint, idempotentHint) by clarifying important behavioral nuances: 'could_not_verify means the check did not happen... and must not be shown as one' and 'unsupported means we looked and cover no source for it.' It also details the two execution paths (structured SEC EDGAR vs. grounded pipeline), mentions pipeworx:// citations, and warns about verification_error{stage,detail}. This is rich, non-obvious context.

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

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

The description is fairly long but well-organized, starting with user phrasings to aid matching and ending with an 'IMPORTANT for callers' warning. It is dense with useful information (verdicts, error handling, routing, replacement of sequential calls), and each section earns its place, though some phrasing is slightly repetitive.

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

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

With no output schema, the description takes on the responsibility of explaining return values: it enumerates all six verdicts, mentions the grounded/structured actual value, citation, and reasoning. It also covers edge cases (could_not_verify vs. unsupported), the two routing paths, and the purpose of tolerance_pct. This is complete for a tool of this 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 schema already covers both parameters (claim and tolerance_pct) with detailed descriptions and examples. The tool description adds 'exact percent-delta math' and mentions tolerance implied by wording, but these are largely redundant with the schema's explanation of tolerance_pct. With 100% schema coverage, the description provides minimal added semantic value.

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 'natural-language claim verification against authoritative sources' and lists example user phrasings (e.g., 'fact check', 'verify the claim that...'). It distinguishes itself from sibling research tools by focusing on verifying specific factual claims rather than general research.

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

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

It provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing for company-financial vs. other claims and notes it 'Replaces 4–6 sequential calls.' However, it does not explicitly name sibling alternatives or when-not-to-use cases, so it lacks the full exclusion criteria for a 5.

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