String Db

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

Annotations already declare readOnly/openWorld/idempotent hints. The description adds meaningful context: the free default model (Workers AI Llama-3.3-70b), the cost implication of using Anthropic ('you pay Anthropic directly'), and the return structure (per-model score/confidence/signals/raw_response + combined view). 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?

Three sentences, front-loaded with the core action, followed by operational details and use cases. Every sentence contributes new information; no filler or repetition.

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 4-parameter read-only tool with no output schema, the description covers return format, model options, cost behavior, and use cases. It is sufficiently complete for an agent to invoke confidently.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining that `_apiKey` triggers paid Anthropic calls (pass-through billing) and that the default model is free. This clarifies parameter behavior beyond the schema descriptions.

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

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

The description states a specific verb ('Probe'), resource ('one or more LLMs'), and measurable outcome ('score visibility (0-100) per model'), which clearly distinguishes it from sibling tools like scan_competitor_ai_presence. It also names concrete use cases (AI-marketing audits, pre-launch brand checks) that reinforce the purpose.

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 use-case context ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. optional model selection. It lacks explicit exclusions or comparison to alternatives, but the context is clear enough for selection.

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

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

Annotations already mark the tool as read-only, open-world, and non-destructive, and the description adds valuable behavioral context: it routes to a massive pool of tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. This goes beyond the annotations and informs the agent about routing and output characteristics, with no contradictions.

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

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

The description is a single dense paragraph but front-loads the most important directive (PREFER OVER WEB SEARCH) and structures the guidance as: what it does, when to use, alternatives, examples, and escalation path. It is longer than necessary, but every sentence contributes useful information; a slight trim could make it tighter, but it is well-organized.

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

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

For a complex tool with no output schema, the description provides a comprehensive picture: the type of questions it handles, the breadth of sources, the return format (structured answer with citations), performance characteristics (fast, every tier), and clear escalation paths. It also includes multiple concrete examples, making it effectively complete for an agent to decide when and how to invoke it.

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

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

The input schema provides 100% coverage: the 'question' parameter is fully described, and aliases are listed with a clear note. The description itself adds no parameter-level explanation beyond the schema, but it does provide natural-language examples that illustrate usage. This meets the baseline for high schema coverage, though it doesn't elevate beyond it.

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

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

The description opens with a clear directive: 'PREFER OVER WEB SEARCH' and explicitly states the tool's role: routing factual questions to 5,529 verified tools and returning structured answers with citations. It names the target domains and provides concrete examples, making the purpose unmistakable and distinct from sibling tools like ask_pipeworx_grounded and deep_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?

The description gives explicit when-to-use guidance ('START HERE for most questions', 'PREFER OVER WEB SEARCH'), and explicitly names alternatives for step-up scenarios: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also covers breaking-news cases and mentions web search as an alternative, fully satisfying the 'when to use vs alternatives' criterion.

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?

It goes beyond the readOnly/openWorld/idempotent annotations by disclosing experimental status, live candidate activation, the current absence of an active candidate, and that it falls back to a full working router. This gives agents a precise understanding of the tool's current behavior and risk profile.

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

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

The description is front-loaded with the most important facts and is information-dense, but it is slightly repetitive (e.g., repeating 'same arguments' and emphasizing 'full working router'). It remains concise and readable overall.

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

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

The description covers purpose, current status, usage, and fallback behavior, and it references identical response shape and arguments, which helps fill the absence of an output schema. However, it does not explicitly describe return format or error behavior, though the stable-tool reference mitigates this.

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

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

The input schema already covers 100% of parameters with descriptions for all aliases, so the baseline is met. The description adds that arguments are identical to ask_pipeworx but does not provide additional parameter-level detail beyond the schema.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It explicitly distinguishes it from the stable ask_pipeworx and describes the exact scope (same 5,529 tools, arguments, response shape).

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 says to use it exactly like ask_pipeworx when you want the newest routing, and mentions results are compared against the stable router. It provides clear context but does not explicitly state when not to use it or name alternative tools beyond the stable counterpart.

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 thoroughly discloses behavior beyond the annotations: it explains the two possible response shapes (success with answer/evidence/confidence vs. refusal with a specific refusal_reason). It also warns about the extra LLM call cost and lists refusal reason categories, which is rich behavioral context.

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

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

The description is well-structured, front-loaded with the key value proposition, and each sentence adds meaningful information: functionality, routing behavior, output format, refusal conditions, use cases, and cost tradeoff. It is dense but not bloated.

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

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

Given the complexity of this tool and the absence of an output schema, the description fully specifies what the agent can expect: successful result fields, refusal reasons, and the extra cost. It also preemptively answers common questions about when to choose this vs. the cheaper sibling, making the context complete for invocation.

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

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

The input schema already documents all parameters at 100% coverage (question and its aliases). The description does not add parameter-specific semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific, informative purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes this tool from the sibling ask_pipeworx by specifying that it extracts answers only from tool results, returns evidence and refusal reasons, and costs an extra LLM call.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives direct alternatives and exclusions: 'prefer ask_pipeworx for casual lookups.' This is clear usage guidance beyond mere capability.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description richly discloses runtime behavior: low-confidence matches short-circuit and suppress analysis, closed markets return a specific status, wide spreads carry tradeability flags, and resolution-rule risks (e.g., refund_50_50) are surfaced. It even explains fallback news sources and retry behavior. No contradiction with annotations exists; instead, it adds substantial operational detail.

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

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

The description is long, but it is heavily structured with clear headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and every section conveys necessary operational details. The front-loading is effective: the first sentence states the purpose, and later sections expand on edge cases. It could arguably be tightened, but the density is justified 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?

With no output schema, the description must explain the return structure, and it does so thoroughly: `result.market`, `result.analysis`, `result.evidence`, resolver contract fields, parent event extraction, news fields, and safety statuses. It also specifies blocking behaviors and edge cases (closed markets, low-confidence matches), making the tool's behavior fully predictable for an agent. Given the complexity and absence of an output schema, this description is exceptionally 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?

While the input schema already describes all three parameters (100% coverage), the description adds essential meaning beyond the schema. It explains the flexible input formats for `market` (slug, URL, or question text), the practical difference between `depth` quick vs thorough with example source counts, and the `include_raw` trade-off in response size. This contextual enrichment goes far beyond the schema's baseline.

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

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

The description opens with a specific, action-oriented statement: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." This clearly identifies the tool's purpose (researching a single bet), the resource (Polymarket market), and the mechanism (fetching Pipeworx data). It also distinguishes itself from siblings focused on broader tasks like polymarket_edges or polymarket_arbitrage by emphasizing per-bet research and evidence synthesis.

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 use cases: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." This tells the agent when to invoke the tool. It does not explicitly name alternative tools or list when-not-to-use, but the context is clear enough to avoid misuse, especially with the blocking safety paths described later.

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 annotations by detailing data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, long-term debt; FAERS counts, FDA approvals, trials), fiscal-year handling, sorting by primary metric, and return of citation URIs. Annotations only state read-only/idempotent, so this context is highly valuable.

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

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

The description is dense and slightly long, but every sentence adds value—examples, precedence rule, per-type data details, sorting, output, and efficiency rationale. It is well-structured and front-loaded with usage examples, though it could be trimmed without losing critical info.

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

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

With no output schema, the description fully covers what data is returned for each entity type, how results are sorted, and that citation URIs are included. It also addresses edge cases like off-calendar fiscal years and quantifies efficiency, making it self-sufficient for an agent.

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

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

Schema covers both parameters with examples, but the description adds meaning by explaining what each type pulls (company vs drug) and gives concrete value examples. This enriches the schema's bare definitions with real-world usage 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?

Description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete trigger phrases like 'X vs Y' and 'which is bigger'. It clearly differentiates from sequential single-entity lookups by saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'.

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

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

Provides explicit when-to-use guidance: use for comparison queries and prefer over sequential lookups. It names the alternative approach (sequential single-pack lookups) but does not mention specific sibling tools like entity_profile, which would make it a 5.

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

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

Annotations declare readOnlyHint true, idempotentHint true, destructiveHint false, but the description goes far beyond: it discloses parallel decomposition across 5,529 tools, that it never invents answers (gaps[]), that citations are only present when resolvable, and that large records are semantically excerpted. It also sets timing expectations. No contradiction with annotations.

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

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

Though lengthy, the description is dense and every sentence earns its place: account requirements, alternatives, use cases, depth behavior, output packet contents, citation guarantees, and timing. It is front-loaded with the most critical constraint (account required) and the alternative tool, making it easy for an agent to pivot if needed.

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

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

With no output schema, the description carries the full burden of explaining return values. It specifies: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri availability. It also covers timing and excerpting behavior. Nothing important is left out.

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 substantial depth semantics not in the schema: quick=3 facets single-hop, standard=5 with gap recovery and contradictions[], thorough=8 paid with iterative lead-chasing. It also reinforces that question is natural language and can be broad/multi-part, which is meaningful 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' It distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and labeling itself 'Best for broad/multi-part questions over structured data.' It also contrasts against 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?

Provides direct when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also notes the account requirement and tells non-signed-in users to use ask_pipeworx instead. This is explicit and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it returns top-N relevant tools with names, descriptions, and full input schemas, and states that results are ready to call directly without a second schema lookup. This clarifies what the agent can expect from the tool's output.

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?

Every sentence earns its place: purpose, usage context, output details, and strategic guidance are packed into a compact paragraph. The description is front-loaded with the core verb+resource, then expands with relevant specifics. No filler or repetition.

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

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

For a discovery tool with no output schema, the description adequately covers what it does, when to use it, and what it returns (top-N results with names, descriptions, and full schemas). It also mentions curated examples and the fact that no second lookup is needed, which is essential for an agent deciding whether to invoke this tool. Given the rich annotations and comprehensive schema, this 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%: all parameters (query and its aliases, plus limit) are documented in the schema. The description doesn't add extra parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate. It does give example queries, but those are illustrative rather than parameter specifications.

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

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

The description opens with a specific verb+resource ('Find tools by describing the data or task') and lists concrete domains, making the tool's purpose immediately clear. It differentiates from siblings by positioning itself as the discovery/meta-tool among many specific tools, especially with 'Call this FIRST when you have many tools available.'

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear contextual guidance and implies when not to use it (when you already know the specific tool and need a direct answer).

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the description's main contribution is naming the databases (GO, KEGG, Pfam, Reactome) and specifying the input as a gene set. This is useful context but does not disclose additional behavioral nuances.

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 compact sentence with no filler, immediately front-loading the core purpose and giving representative database examples. Every word earns its place.

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

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

The output schema and rich annotations cover much of the behavioral surface, so the description need not explain return values. However, the lack of usage guidance and sparse parameter semantics leaves clear gaps for a specialized tool, making it minimally viable but not fully self-sufficient.

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

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

With zero schema description coverage, the description must compensate, but it only broadly implies that 'identifiers' form a gene set. It does not explain expected identifier formats (e.g., Ensembl IDs) or the role of the optional 'species' parameter. The schema examples provide some clues, but the description itself adds minimal parameter-level meaning.

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

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

The description clearly identifies the tool as performing functional enrichment (GO, KEGG, Pfam, Reactome) for a gene set. It names the analysis type and target input, distinguishing it from sibling tools like homology or interactions.

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

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

No guidance is provided about when to use this tool versus alternatives, nor any exclusions or prerequisites. The user must infer usage from the tool name and 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 readOnly, idempotent, and non-destructive. The description adds significant context: fans out across multiple sources, returns specific fields, patents API sunset with soft-fail, GDELT→GNews fallback, and input format constraints. No contradiction with annotations.

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

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

The description is a single dense paragraph but is front-loaded with examples and packs many details. Every sentence contributes, though it could benefit from light formatting to improve scannability; the content is justified given the tool's complexity.

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

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

The tool is complex with no output schema, yet the description enumerates the exact return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their nuances (sort order, URIs, fallbacks). This fully covers what to expect, making the description complete for such a complex tool.

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

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

Schema coverage is 100% for both parameters, and the schema already includes detailed descriptions (ticker/CIK, names not supported, use resolve_entity). The description simply repeats this information without adding new semantic meaning beyond the schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call', with specific examples like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from sibling tools by contrasting with 'single-pack SEC/XBRL/news lookups' and mentioning resolve_entity for name-only queries.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', and indicates when not to use it: 'names not supported (use resolve_entity first)'. This provides clear when-to-use and alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the core behavioral profile is covered. The description adds minimal extra behavior beyond the obvious deletion action, such as specifics about idempotency or error handling. It does provide context about clearing sensitive data, but this is more of a motivational use case than a behavioral disclosure.

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

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

The description is three short sentences, front-loaded with the action, followed by specific usage guidance and sibling references. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple one-parameter delete tool with comprehensive annotations and a clear schema, the description covers purpose, usage conditions, and related tools. No output schema is present, so return values need not be explained. The tool is fully contextualized within the memory workflow.

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

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

Schema coverage is 100% for the single parameter 'key', which includes a description 'Memory key to delete' and an example. The tool description repeats that the deletion is 'by key' but does not add additional meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like recall (retrieve) and remember (store), with no ambiguity.

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

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

It explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, effectively identifying alternative tools for related operations.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the internal workflow: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also notes the output is a single text blob, adding behavioral context without contradicting the safe read-only profile.

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 tightly organized in three sentences: purpose first, then process, then use cases. Every sentence adds distinct value with no redundancy or filler, making it easy to scan.

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

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

For a tool with two well-documented parameters and strong annotation coverage, the description covers the core aspects: what it does, how it works, what the output looks like, and when to use it. It omits edge cases like URL validity or error behavior, but the simplicity of the tool and the safety annotations make the description reasonably 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?

The input schema already provides complete descriptions for both parameters (url and max_links), achieving 100% coverage. The description adds minimal parameter-specific detail (e.g., mentions 'key links' but not the max_links limit), so it meets the baseline without going 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 opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states the output format ('standard llms.txt markdown format') and distinguishes this tool from siblings by focusing on llms.txt generation, which none of the listed sibling tools explicitly do.

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 use cases under 'Useful for:' (client site indexing, own project drafting, competitor auditing), giving clear context for when to use this tool. It does not name alternative tools or state exclusions, but the use cases are specific enough to guide selection.

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

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

Annotations already declare read-only, idempotent, open world, and non-destructive. The description adds useful context: data source (STRING-DB), accepted identifier formats (gene symbols or accessions), and default species (9606=human). This goes beyond the annotations without contradicting them.

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

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

The entire description is a single sentence that packs all essential details: source, input types, default parameter, and output. It is front-loaded with the verb and has zero fluff.

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

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

With annotations covering safety (read-only, idempotent) and an output schema present, the description sufficiently covers the tool's purpose and input semantics. No critical information is missing for a simple query 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 0%, so the description compensates by explaining 'identifiers' as protein identifiers (gene symbols or accessions) and 'species' as an NCBI taxonomy species with a default of 9606. This adds semantic meaning beyond the bare property names and schema types.

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

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

The description uses a specific verb 'Retrieve' and names the resource 'STRING-DB homology mappings', along with input types (protein identifiers, species) and output nature (cross-species homolog relationships). This clearly distinguishes it from sibling tools like 'network' or 'enrichment'.

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 clear context: you use this tool when you have protein identifiers and a species and want cross-species homologs. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds no additional context about behavior, such as how network_type or required_score affect results, or any limitations like the number of partners returned. The description is too terse to disclose any behavioral traits beyond the basic purpose.

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, brief sentence with no wasted words, which is concise, but it is under-specified rather than appropriately structured. It lacks any elaboration or hierarchy to help the agent understand the tool's capabilities and limits.

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

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

The tool has moderate complexity with five parameters and an output schema, yet the description provides only a minimal statement of purpose. It does not orient the user on selection criteria, default behavior, or relationships to sibling tools, making it incomplete for effective and safe invocation.

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

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

The schema provides descriptions for limit, network_type, and required_score (60% coverage), but the description itself adds no meaning for parameters like identifiers or species. Examples in the schema illustrate the identifier format, but the description does not clarify parameter usage or constraints beyond what is already in the schema.

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

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

The description clearly identifies the tool's core function: returning interaction partners for a set of proteins. It names the resource (protein interactions) and the input (proteins), but lacks an explicit verb and does not differentiate from sibling tools like 'network'. This makes it clear but not fully 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?

The description provides no guidance on when to use this tool versus alternatives such as 'network', 'enrichment', or 'homology'. There is no mention of scenarios where this tool is preferred or when a sibling tool would be more appropriate.

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

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

Annotations already provide readOnlyHint and destructiveHint. The description adds that it returns specific fields (id, type, params, created_at, last_fired_at, fire_count) and that it is scoped to the caller's active subscriptions, which is useful beyond the annotations. 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?

Two sentences with no wasted words. The first states the action and return fields, the second provides usage guidance. Highly efficient and well-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?

For a simple read-only list tool with one optional parameter, the description covers the purpose, return fields, and usage context. Annotations handle safety, and the schema covers the parameter. Nothing essential is missing.

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

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

Schema description coverage is 100% and includes a clear description for 'include_inactive'. The tool description reinforces that only active subscriptions are listed by default, but does not add substantial new meaning beyond the schema.

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

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

The description clearly states the action ('List') and resource ('the caller's active subscriptions'), specifies return fields, and distinguishes it from mutation tools like subscribe/unsubscribe. It is 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?

It provides explicit use cases ('to review what you're monitoring before adding more or to find an id to cancel'), which makes the when clear. It does not explicitly name alternative tools, but the sibling context and implied alternatives are sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the output includes an image URL and tabular interaction data, which is useful, but lacks details about pagination, data structure, or any limitations.

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 six-word fragment, which is under-specified rather than concise. It lacks structure and does not form a complete sentence.

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 with annotations and an output schema, the description fails to convey the tool's core capabilities, making it impossible for an agent to know when to use it and what to expect.

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

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

Schema description coverage is 0%; the description does not explain the meaning of 'identifiers', 'species', 'network_type', or 'required_score'. The examples show ENSP IDs and a score threshold, but the description provides no parameter semantics.

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

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

The description 'Network image url + tabular interaction data' is a fragment that fails to state a clear verb or resource. It doesn't indicate what operation is performed on which entities; the schema's ENSP examples hint at protein interactions, but the description alone is ambiguous.

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

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

No usage guidance is provided; the description does not mention when to use this tool versus alternatives like 'interactions' or 'enrichment'.

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

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

Annotations are all false, so the description carries full burden. It discloses rate limits ('5 per identifier per day'), free usage (no quota impact), the claim_token mechanism for anonymous filing and later follow-up, and that the team reads digests daily. It also clarifies non-destructive intent without contradicting annotations. This is thorough behavioral disclosure.

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

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

Although longer than typical, every sentence earns its place. The description is front-loaded with purpose, then logically flows into usage scenarios, exclusions, claim_token mechanics, and operational details. No filler or redundancy; each clause provides actionable 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?

The tool has 4 params, a nested object, no output schema, and all annotations false. The description covers the full context: what the tool does, when to use it, what to report, how follow-up works, rate limits, and the distinction between Pipeworx and other servers. It leaves no significant gap for an agent to misuse the tool.

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

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

Schema coverage is 100%, but the description adds essential meaning beyond the schema: it explains how to use claim_token with the exact syntax `pipeworx_feedback({claim_token:"pwfb_…"})`, elaborates on message content ('don't paste the end-user's prompt'), and clarifies the type enum categories. This elevates parameter understanding beyond the schema alone.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from all sibling tools by being the only feedback tool, and explicitly scopes to tools served by this Pipeworx connection. No ambiguity.

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

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

Provides explicit when-to-use (bug, feature, data_gap, praise), when-not-to-use (other MCP servers), and alternative action ('file it with that server instead'). Also gives detailed usage instructions: identify Pipeworx tools by connection, describe issues in terms of Pipeworx tools, and use claim_token for follow-up. This is exemplary 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?

While annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds behavioral context: it is a 'self-aggregating signal' derived from 'CF analytics-engine', excludes PII, and is cached 5min-1h. This helps set expectations about data freshness and scope.

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

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

The description is moderately long but well-organized: a hook, a returns statement, bullet-like use cases, and data provenance/cache info. Each sentence adds value, though it could be tightened.

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

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

For a simple read-only tool with one optional parameter, the description covers return values, data source, privacy, and caching. No output schema exists, but the description's enumerations (top tools, top packs, total call volume) provide sufficient expectations. It is complete for its 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 single parameter 'window' is fully documented in the schema with default and guidance on short vs long windows. The description only repeats the window options, adding no new semantic information beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Returns' and identifies the resource: top tools, top packs, and total call volume over a window. It also frames the scope with 'What other AI agents are calling on Pipeworx right now', distinguishing it from sibling tools like discover_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 three explicit 'Useful for' scenarios, giving clear context for when to invoke the tool. It doesn't name alternative tools, but the scenarios imply appropriate usage.

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?

Discloses significant behavioral details beyond the readOnly/idempotent annotations: partition filter placeholder logic, fill check against live CLOB depth, and warnings that realizable_edge_pp ≤ 0 means the edge is not tradeable. Also explains semantic anchor and skipped_low_similarity. 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 dense and information-packed with no fluff, but it is a single large block lacking visual structure (bullets or headers). While every sentence earns its place, the block format can make it harder for an agent to scan key points quickly.

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 explains the response shape (opportunities[], partition_check, fill_check fields) and covers all edge cases. It also references a sibling tool for follow-up actions, making it complete for the tool's complexity.

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

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

Schema descriptions for event and topic are basic, but the tool description vastly enriches them with concrete slug examples, seed question examples, mode-specific behavior, and response structure. This is well above the baseline for 100% schema coverage.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and explicitly pointing users to polymarket_fill_risk for sizing.

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

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

Provides explicit usage modes with clear context: 'Call with NO args for a trending_scan', 'pass event for...', 'or topic for...'. It even recommends event mode for specific markets and explains when cross-event mode is superior, offering direct alternatives and exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses caching ('Cached 1h at the KV level'), the response structure (by_segment, fed_candidates, _diagnostics), and subtle behaviors like the 24h-move warning, per-sport α values, and placeholder-slug filters. It also explains why segments can be empty via filter_skips, giving agents deep insight into runtime behavior.

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

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

The description is lengthy but well-structured. It opens with purpose, then systematically covers model segments, response fields, tradeable-edge knobs, and caching. Each sentence carries unique information and the flow is logical. However, it is not concise; significant trimming could make it easier to parse. It earns a 4 for structure and density, not brevity.

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

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

With no output schema, the description fully specifies the response shape: by_segment with three segment names, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, market.volume, 24h-move warning), fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also explains why segments may be empty and how knobs affect output, making it nearly self-sufficient for a complex tool.

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

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

Schema coverage is 100%; every parameter is fully described in the input schema. The tool description mentions 'TRADEABLE-EDGE KNOBS' but the schema already explains min_liquidity, max_spread_pp, and min_partition_leg_kelly in detail, including their purpose and defaults. The description adds no new parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies the use case ('what should I bet on today') and distinguishes from siblings by detailing the three response segments and tradeable-edge knobs, making it clear this is an aggregate opportunity scanner.

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

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

The description provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives guidance on when to adjust knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). However, it never explicitly names alternatives or says when NOT to use this tool, so it misses the higher bar for explicit when/when-not.

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

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

The description goes well beyond annotations. It discloses response structure (tracked vs. expired opportunities), computation methods (decay from daily closes, not intraday), and data availability quirks (snapshots written on cache-miss so gaps mean no scan). This adds substantial behavioral context not captured by the readOnly/idempotent hints.

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

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

The description is long but efficiently structured: purpose, args, response, limits. The opening sentence is sharp, and each section (RESPONSE, LIMITS) adds necessary details. The motivational aside about fresh vs. old edges is useful for decision-making. No filler.

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

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

Given no output schema, the description meticulously explains the full response shape, including fields, edge cases (expired opportunities, gaps), and calculation specifics. It also mentions TTL and snapshotting history bounds. This is comprehensive enough for an agent to understand what it will receive without an output schema.

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

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

Schema coverage is 100%, with both params (days, window) already described in the schema. The description repeats the defaults and examples but adds little new meaning—it merely contextualizes them as 'lookback' and 'snapshot family.' Baseline 3 is appropriate since the schema handles parameter documentation.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling tool polymarket_edges by focusing on historical persistence/decay rather than 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 the tool is valuable: distinguishing fresh vs. aged edges for trade decision-making. It also notes limitations (60-day TTL, snapshot gaps) that help an agent decide when to rely on it. However, it does not explicitly name alternatives or state when not to use this tool over other siblings.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond those annotations. It discloses what the tool does internally ('walks the ladder'), what outputs to expect (top_of_book, vwap_fill_price, slippage_pp, verdict), and highlights the key risk of partial basket fills becoming directional positions. No contradiction with annotations.

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

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

The description is long but every sentence carries necessary information. It is front-loaded with the core purpose, then clearly structured with REQUIRES, SINGLE-MARKET, and BASKET sections. The length is justified by the tool's complexity and dual modes; it avoids fluff and 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 has two distinct modes, no output schema, and only sparse parameter names, the description fully compensates by enumerating return fields, explaining verdicts, and detailing risk consequences. It covers inputs, outputs, constraints (size clamp), and failure modes (thin_legs, forced_directional_risk). There are no significant gaps in context.

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 description coverage is 100%, the description adds critical semantic context for each parameter. For size_usd it distinguishes between 'max spend on buys' and 'target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg)' in basket mode. It also clarifies default behavior of side in basket mode (auto from partition sum). This goes well 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 opens with a specific and concrete purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the tool's function (risk checking) and resource (CLOB order book) and distinguishes between single-market and basket modes. It also differentiates from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as tools it should precede.

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

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

The description gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial fills create unhedged risk), and distinguishes when to use single-market vs basket mode. This is exemplary usage guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description goes far beyond by detailing the response structure, compatibility_warning conditions, temporal alignment semantics, and skipped-counter meanings. The explicit warning that 'pre-mapped ≠ tradeable' is critical for correctly interpreting 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?

Though longer than typical descriptions, it is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds necessary operational or caveat information. The opening sentence is front-loaded, and the dense detail is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining the response. It covers the spread calculation, leg-by-leg prices, top_spreads_pp, compatibility warnings, temporal alignment, and skip counters, providing enough detail for an agent to correctly invoke and interpret 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?

The schema already provides 100% coverage for all three parameters. The description adds valuable context by explaining how `topic` map to events, how explicit tickers override the mapped side, and how the two modes interact—semantics not fully captured in the schema alone.

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

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

The description opens with a specific, clear definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by focusing on cross-venue comparison, and further clarifies its two modes (topic shortcuts and explicit pairings), making the purpose unambiguous.

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

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

The description provides strong context on when the tool is applicable, notably the caveat that real spreads are rare and most pre-mapped topics return compatibility_warning. It explains the tradeable condition (equivalent bet shapes) and the two modes, but it does not explicitly contrast with sibling tools like polymarket_arbitrage, leaving some inference to the agent.

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

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

While annotations declare readOnlyHint, idempotentHint, and destructiveHint, the description adds important context: data is scoped to the user's identifier and omitting the key lists all keys. These behaviors are not captured in the annotations.

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

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

Two sentences, front-loaded with the primary action and clear examples. No filler or redundant information; every phrase adds value.

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

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

For a tool with one optional parameter and no output schema, the description fully covers behavior, scoping, and integration with related tools. The agent has enough information to select and invoke the tool correctly.

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

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

The schema covers the parameter with a description and the omit behavior. The description enriches this by providing concrete examples of keys (target ticker, address, research notes), helping the agent understand what values are meaningful.

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 two functions: retrieving a value saved via remember and listing all saved keys when the key argument is omitted. This explicitly distinguishes it from sibling tools like remember and forget by describing the complementary workflow.

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 context for when to use the tool ('Use to look up context the agent stored earlier') and mentions pairing with remember/forget. However, it does not explicitly state when not to use it or name alternatives beyond the paired 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?

The description discloses that mark_read:true persists a read flag affecting future calls, which is a useful side effect beyond the readOnlyHint annotation. It also describes the payload structure without contradicting annotations.

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

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

Four sentences, front-loaded with purpose, no filler. Every sentence adds value—purpose, payload, filtering, mark_read behavior, and alternative endpoint—all in a compact 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?

Covers return payload fields, filter semantics, mark_read persistence, polling suitability, and an alternative access method. Without an output schema, it gives enough information to use the tool effectively, though a fuller output field list could make it 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?

The schema already covers parameters well (100%), and the description adds an example filter value ('sec_8k') and explains the persistent effect of mark_read on subsequent calls, going 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 pulls fired events from the subscription feed, describes the return payload elements, and is differentiated from sibling tools like list_subscriptions and recent_changes.

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

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

It gives context for polling and mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools like list_subscriptions or recall.

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 detail beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It reveals the fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback logic (GDELT preferred, GNews when rate-limited or 5xx), and a known limitation (USPTO soft-fails until PatentsView API is reactivated). It also describes the return structure (changes[] grouped by source + total_changes + citation URIs), giving the agent a complete mental model of what happens.

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

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

The description is dense but every sentence earns its place. It opens with user-facing query examples, then explains sources, fallbacks, parameter formats, return object, and an alternative tool in a logical flow. Despite its length, there is no repetition or fluff; the structure front-loads the core purpose and then provides necessary operational details.

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

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

The tool has moderate complexity (multiple data sources, fallback logic, date-range input, no output schema). The description fully covers this: it states the input format, source behavior, fallback rules, output shape (changes[] grouped by source, total_changes count, citation URIs), and the alternative tool. Given the lack of an output schema, the description's explanation of the return value is essential and 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 value by elaborating the 'since' parameter: it accepts ISO dates ('2026-04-01') or relative shorthand ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. It also clarifies 'value' as ticker or zero-padded CIK with an example, enriching the schema definitions. This extra guidance justifies a score above baseline.

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

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

The description states a specific verb+resource+scope: 'change feed for a company in the last N days/weeks/months in ONE parallel call' with concrete examples ('What's new with X'). It also distinguishes from sibling 'entity_profile' by contrasting the dynamic change feed with the static profile, making the tool's 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?

Explicit guidance is given: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This names the alternative tool and specifies when to choose it. Query examples like 'updates on Acme' illustrate appropriate use cases, providing clear context for when to invoke this tool.

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

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

Annotations already mark idempotentHint=true and destructiveHint=false, but the description adds key behavioral traits: scoping 'by your identifier,' persistence differences between authenticated (persistent) and anonymous (24 hours), and the across-session nature. This goes 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?

Three sentences: the first states the action, the second gives usage context and examples, the third covers scoping, durability, and tool pairing. No filler or repetition.

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

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

The tool is simple (2 required string params, no output schema), and the description covers its purpose, when to use, persistence, and relationships to recall/forget. Annotations handle idempotence and safety. Nothing essential is missing.

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

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

The input schema already describes both key and value with examples and 100% coverage, so the baseline is 3. The description reinforces the key-value pattern and gives usage examples ('user preference') but doesn't add new parameter-level semantics beyond the schema.

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

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

The description uses the specific verb 'Save' with resource 'data the agent will need to reuse later,' and clarifies its role by naming paired siblings (recall, forget). It gives concrete examples like 'resolved ticker' and 'target address,' distinguishing it from read-only tools.

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

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

It explicitly states 'Use when you discover something worth carrying forward' and provides the exclusion/alternative by saying 'Pair with recall to retrieve later, forget to delete.' This gives clear when-to-use and relationships to 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds no additional behavioral context (e.g., matching behavior, ambiguity handling, or output specifics) beyond what annotations and schema already provide. No contradictions found.

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, efficient sentence that immediately conveys the core function. It is exceptionally concise and well-structured, with 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?

Given the tool's relative simplicity and the presence of an output schema and rich annotations, the description is minimally adequate. However, it lacks guidance on use cases or alternatives, and does not explain potential edge cases like multiple matches or failure modes, which would make it more 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?

The input schema covers most parameters with descriptions (limit and species), so the baseline is 3. The description adds meaning to the 'identifiers' parameter by calling them 'free-text identifiers,' which is helpful since that parameter lacks a schema description. However, it does not elaborate on limit or species.

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

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

The description clearly states the tool's function with a specific verb ('Map') and resource ('free-text identifiers') and specifies the output ('STRING identifiers'). It is clear and concise, but it does not explicitly distinguish itself from the sibling tool 'resolve_entity', which may serve a similar purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'resolve_entity' or other identifier-related tools. It lacks any explicit context for selection or exclusion criteria.

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

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

The description goes beyond annotations by revealing internal cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, the labeling of identifiers with source, and the explicit reporting of unresolved identifiers. This adds significant behavioral context not present in the readOnlyHint/openWorldHint 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 somewhat long but every sentence carries valuable information. It is front-loaded with user queries and a concise core statement, followed by structured details on types and fallback behavior. Slightly dense but justified 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?

With no output schema, the description compensates by explaining return formats (source-labeled identifiers, explicit unresolved list, RxCUI citation). It covers input variations, degradation, and internal behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for both params, and the description enriches them by detailing accepted formats for company (ticker, CIK, name) and drug (brand/generic), plus what each type returns (CIK, LEI, FIGI vs RxCUI). It adds examples and nuance beyond the schema descriptions, though the schema already provides baseline clarity.

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 resolves user-spoken names to canonical official identifiers, with concrete examples like 'ticker for…' and 'find the CIK for…'. It distinguishes from siblings by positioning it as the first tool to use when a name needs an ID, and the supported types are detailed.

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 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. The examples of user queries also clarify intended scenarios. It does not name alternative tools but the instruction to use it first is strong and unambiguous.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds behavioral detail by explaining the tool probes each entity, ranks results, and returns a list with score, confidence, and signal density. It does not contradict any annotation, and provides process transparency beyond the annotation flags.

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

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

The description is four sentences, front-loaded with the main verb 'Compare'. Each sentence adds distinct value: purpose, process, use case, and output structure. No filler or redundant information.

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

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

Given the tool has no output schema, the description explicitly states the return format (ranked list with score, confidence, signal density). It covers usage context and the delegation to ai_visibility_check. The complex parameters are fully documented in the schema, so the description is sufficiently 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 does not add much parameter-level meaning beyond the schema; it repeats the 'first entry as subject' idea already in the schema's entities description. No additional clarification of models/_apiKey/context is provided 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 compares AI visibility across multiple entities side-by-side, names the specific process (probes each entity with ai_visibility_check, ranks by score), and distinguishes it from the single-entity sibling ai_visibility_check. The phrase 'most/least recognized' clarifies the output.

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

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

The description provides a clear use case: competitive AI-marketing audits, exemplified with 'does Claude know about us as well as our competitors?'. By saying it probes each entity with ai_visibility_check, it implies that ai_visibility_check is for single-entity checks, though it doesn't explicitly name alternatives. This is clear guidance but lacks explicit when-not-to-use statements.

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 readOnly, openWorld, idempotent, non-destructive, and the description adds critical behavioral details: fan-out across two services, the 5-30s first measurement delay for bundlephobia, and that partial failures still return results with sources_failed. This goes beyond the annotations to set agent expectations about latency and failure handling.

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

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

The description is a single dense paragraph that front-loads the core purpose first, then immediately gives usage guidance, return contents, and limitations. Each sentence adds distinct value—no filler—while remaining compact given the tool's composite nature.

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 return values, and it enumerates the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) plus per-advisory detail and version alternatives. It also covers ecosystem scope, timing behavior, and failure semantics, making the tool fully understandable without further lookups.

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 documents both parameters with clear descriptions (package name, version defaulting to latest). Description reinforces the default behavior ('Defaults to the latest published version') and mentions scoped-package support ('@types/node') that's already in the schema, but doesn't add substantial new parameter semantics beyond the existing 100% coverage.

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

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

The description opens with a clear verb phrase: 'Composite "should I add this npm package to my project" check in ONE call' and immediately identifies the two data sources (deps.dev and bundlephobia). It explicitly scopes to NPM ecosystem in v1 and points to an alternative for other ecosystems, distinguishing it from general dependency 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?

Explicit use-case trigger: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion/alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' and explains when to expect the alternative. It also describes graceful degradation context, further guiding the agent on what to expect.

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

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

The description adds substantial behavioral context beyond the readOnlyHint, openWorldHint, and idempotentHint annotations. It discloses the embedding model (BGE-base-en), the retrieval method (cosine over 500-char overlapping windows), the 200K character cap with truncation flagging, and the presence of character offsets for verification. This goes far beyond what annotations provide.

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

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

The description is front-loaded with the core purpose, then efficiently covers use cases, pairing with siblings, and technical behaviors. Every sentence earns its place—no filler or redundancy. It is longer than a single sentence, but the density of useful information justifies the length.

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

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

Given the tool's moderate complexity, the description is complete: it covers inputs, outputs (passages with offsets and similarity scores), constraints (200K cap, truncation), algorithmic details, and integration with a sibling tool. No output schema exists, so the description appropriately explains return characteristics. The information is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents text, query, and limit thoroughly. The description mostly repeats or contextualizes these parameters (e.g., 'text you already pulled'), but does not add significant new semantic detail beyond what the schema provides. The baseline of 3 applies because the schema fully covers parameter meaning.

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

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

The description clearly states the tool performs semantic search inside an already-fetched record, with a specific verb ('search within'), explicit inputs (text + query), and outputs (top-N passages with offsets and similarity scores). It also distinguishes itself from sibling tools by positioning search_within as a context-saving alternative and referencing ask_pipeworx_grounded.

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

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

The description explicitly says to use this tool when a record is too large for the prompt, and explains how it saves context. It also names a sibling (ask_pipeworx_grounded) and describes the pairing relationship (fetch with the gateway, ground over relevant passages), giving clear guidance on when to use this tool versus 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?

The description goes well beyond annotations by disclosing authentication requirements, phone verification, SMS caps, feed persistence, webhook signing and auto-disable behavior, and the return of a subscription id. These are critical behavioral details not covered by readOnlyHint/openWorldHint/idempotentHint/destructiveHint. No contradictions with annotations.

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

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

The description is dense but well-structured. It front-loads the core purpose and then systematically covers requirements, types, and delivery channels. Every sentence contributes useful information, though the length is substantial. The structure could be slightly improved with clearer bullet points or separation.

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

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

For a tool with nested parameters and no output schema, the description is remarkably complete. It covers prerequisites, type-specific parameter formats, delivery options, return behavior, and security details. It leaves no significant gaps for an AI agent to infer.

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 the schema has 100% parameter coverage, the description adds valuable examples (e.g., items:['5.02'] = officer change) and clarifies delivery constraints (SMS cap, webhook signing secret). This provides additional meaning beyond the schema, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and notes it returns the new subscription id. This specific verb+resource phrasing distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

The description provides clear context for when to use the tool (setting up monitoring subscriptions) and notes that an OAuth account is required, implying anonymous users cannot persist subscriptions. It does not explicitly mention alternatives, but it does reference pulling alerts via recent_alerts or the registry feed, which gives some context. A slight exclusion mention would improve this.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond the annotations: the response format (category-bucketed example questions), that the catalog is live and large, and the behavior of omitting vs. passing topic. It does not contradict the annotations and enriches the agent's understanding of side-effect-free, open-ended querying.

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 user phrasings, then explains the response, usage, and priority. Every sentence contributes information, but the opening list of paraphrases is somewhat verbose and could be condensed. Overall it is efficient for the complexity it covers.

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

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

For a simple tool with one optional parameter and no output schema, the description is thorough: it explains what the tool returns (category-bucketed examples with tool shapes), how to call it (with/without topic), and when to use it. The annotations cover safety, so no behavioral gaps remain. The description fully compensates for the lack of an 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?

The schema description covers 100% of the parameter meaning: the 'topic' field lists valid focus areas and says omitting gives a cross-category spread. The tool description repeats 'call with no arguments for the full spread, or pass topic' and gives examples, but adds no new information beyond the schema. This matches 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 is highly specific: it names the exact entry-point verb ('onboarding entry point') and resource (Pipeworx capabilities). It clearly differentiates from siblings by stating it returns category-bucketed example questions with tool+argument shapes, and explicitly positions it as the tool to use before knowing what to ask. The listed user phrasings also make intent unmistakable.

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

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

The description gives explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do') and mentions alternatives (meta-tools like ask_pipeworx, entity_profile). However, it does not explicitly state when NOT to use it or compare against similar tools like discover_tools, so it falls just short of a 5.

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

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

The description goes beyond annotations by explaining the deactivation behavior ('The row is deactivated (not deleted) so its historical events stay available via recent_alerts') and the ownership enforcement ('you can only cancel your own subscriptions'). This transparently discloses side effects and access constraints, which is valuable given the tool is a write operation.

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 only three sentences, each with a distinct, high-value point: the core action, the ownership rule, and the non-destructive deactivation behavior. It is front-loaded with the verb and resource, containing zero filler.

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

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

For a simple single-parameter mutation tool with no output schema, the description adequately covers what the tool does, the key precondition (ownership), and the result (deactivation not deletion). It even points to 'recent_alerts' for follow-up context, making it complete for an AI agent to use confidently.

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

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

The schema already fully describes the only parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description repeats that the action is by id but adds no new parameter-specific meaning beyond what the schema states. With 100% schema coverage, the baseline of 3 applies.

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

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

The description states a clear action: 'Cancel a subscription by id.' It names the specific resource (subscription) and the verb (cancel), and the title 'Unsubscribe from Alerts' reinforces the purpose. It also distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description clearly implies when to use the tool (to cancel a subscription) and adds a key constraint: ownership is enforced ('you can only cancel your own subscriptions'). It also mentions that the row is deactivated rather than deleted, and points to 'recent_alerts' for historical availability, which gives situational context. However, it does not explicitly contrast with alternatives like 'list_subscriptions' or 'subscribe'.

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

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

The description discloses significant behavioral traits beyond the annotations: it explains the verdict types, the distinct meaning of 'could_not_verify' vs. 'unsupported', and the warning that 'could_not_verify' must not be treated as evidence. It also reveals the dual-pipeline routing (structured SEC XBRL vs. grounded pipeline). These details add real context not available from annotations alone.

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 well-structured: it opens with example phrasings, then states purpose and usage, explains internal routing, lists return values, and includes an important caveat in a clear 'IMPORTANT' callout. Each sentence earns its place, though a few examples could be trimmed. It remains readable and scannable for a complex tool.

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

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

The tool has no output schema, so the description carries the full burden of explaining return values. It thoroughly covers the verdict enum, the actual value with citation, reasoning, and the verification_error field. It also explains edge-case semantics (could_not_verify vs. unsupported) and the two pipeline paths, making the description complete for the tool's complexity.

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

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

The input schema already provides full 100% coverage for both 'claim' and 'tolerance_pct', including examples and the behavior of tolerance_pct. The tool description references 'exact percent-delta math' but does not add additional parameter-level semantics beyond what the schema already covers. Given the high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with explicit verb 'fact check' and 'verify'. It distinguishes itself from sibling search tools by focusing on true/false judgment and returns a verdict. The examples ('Is it true that...', 'fact check') make the intent unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear when-to-use guidance. It also explains the internal routing for financial vs. other claims, and mentions it replaces multiple sequential calls. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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