Statbel Be

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

Beyond the read-only/idempotent annotations, the description adds meaningful behavioral details: default model (Workers AI Llama-3.3-70b) is free, passing _apiKey incurs direct Anthropic costs, and the return structure includes score, confidence, signals, and raw_response plus a combined view.

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

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

The description is three sentences: it states the core function, explains the default/cost tradeoff, and lists concrete use cases. There is no redundancy or unnecessary detail.

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

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

Despite having no output schema, the description covers the key elements needed for an agent: what the tool does, how to extend it (adding Anthropic), what the response looks like, and when it is useful. It is self-sufficient for selection and 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?

All parameters are already well-documented in the schema (100% coverage), so the baseline is 3. The description adds value by clarifying the free default model and the cost implication of providing an Anthropic API key, which goes beyond the schema's description.

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

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

The description uses a specific verb ('probe') and resource ('one or more LLMs') and clearly states the output (visibility score 0-100 per model). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on per-model scoring and combining results.

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

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

Explicit use cases are provided: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not mention when not to use this tool or point to alternatives, 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?

The description adds useful behavioral context beyond the read-only/open-world annotations by disclosing that the tool routes to other tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not detail failure behavior or rate limits, but these are less critical given the strong annotation safety 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 routing guidance and uses lists and examples efficiently. It is somewhat repetitive—'Use whenever...' and 'START HERE' say similar things—and the final breaking-news sentence is niche, but the overall structure remains scannable.

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

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

For a broad, high-complexity tool with no output schema, the description covers what it does, when to use it, how to phrase the question, and what kind of output to expect (structured answer with citations). It does not specify the exact return format or fallback when the tool cannot answer, but these gaps are minor given the rich annotations.

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

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

The schema already documents the single required question parameter and its aliases at 100% coverage, so the baseline is 3. The description adds value by showing concrete question formulations and enumerating accepted request types, which helps the agent compose the natural-language argument.

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

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

The description clearly identifies the tool as a routing/answering service for factual questions, with a specific mechanism: it sends the question to one of 5,798 tools across verified sources and returns a cited structured answer. However, it does not distinguish ask_pipeworx from its sibling variants ask_pipeworx_beta and ask_pipeworx_grounded, so it lacks explicit sibling differentiation.

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

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

It opens with 'PREFER OVER WEB SEARCH', gives explicit trigger phrases like 'what is', 'look up', and 'get the latest', and states it should be used even when web search could answer. It also provides exclusions: non-factual, conversational, or questions Pipeworx cannot 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 readOnly/openWorld/idempotent, and the description adds meaningful behavioral context: candidate routing may be experimentally enabled live, no candidate is currently active, and it 'falls back to nothing' because it is a full working router rather than a degraded proxy. This goes well beyond the structured annotations.

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

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

The description is longer than average but each sentence adds needed context: beta status, live candidate behavior, current state, usage instruction, and the reassurance that this is a full router. The specific retirement date is a minor extra detail, but overall the structure is front-loaded and purposeful.

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

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

Given it is a universal router with no output schema, the description covers current behavior, usage equivalence, routing purpose, and response-shape consistency with ask_pipeworx. It lacks explicit examples or output format, but cross-referencing ask_pipeworx's response shape is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references 'same arguments' as ask_pipeworx and confirms the response shape, but it does not add parameter-level details beyond what the schema already documents for question and its aliases.

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, a universal router over 5,798 tools, and explicitly distinguishes it from the stable ask_pipeworx by noting it carries 'candidate routing improvements.' This gives a specific verb-plus-resource framing and differentiates it from sibling tools.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not explicitly state when to avoid it or name an alternative for stable/grounded use, so it stops short of full when-not coverage.

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

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

Goes far beyond the readOnlyHint/idempotentHint/openWorldHint annotations by disclosing the refusal contract: exact refusal_reason enum values ('not_in_source'|'no_tool_match'|'tool_error'|'data_truncated'|'llm_error') and the guarantee that answers are extracted ONLY from what the tool result contains. It also reveals the full success return shape and the extra-LLM-call cost, neither of which annotations convey. 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?

Dense but every sentence earns its place: purpose, routing mechanism, return contract, refusal contract, usage guidance, and cost trade-off are all present with zero filler. The detailed return/refusal shape must live in the description because no output schema exists. The most actionable facts (cost, when-not-to-use) are clearly flagged at the end without burying the purpose.

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

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

For a tool with no output schema, the description carries the full return contract — six success fields and five distinct refusal reasons — so nothing an agent needs to interpret the result is missing. The unusual routing complexity (5,798 tools across 1517 sources) is explained in one clause. Sibling differentiation, safety profile via annotations, and cost semantics are all covered.

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% — the `question` parameter is fully documented in the schema, including its five aliases (query, q, prompt, text, input), so the high-coverage baseline of 3 applies. The description adds usage-oriented context about which questions merit this mode but no new parameter-level syntax or formatting details. The schema is doing the work here, which is acceptable.

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

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

States a specific purpose — a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using ONLY tool-result content and refuses rather than fabricate. It explicitly distinguishes itself from sibling ask_pipeworx ('Same routing as ask_pipeworx') by adding the extraction step and the refusal contract. The verb+resource pairing is unambiguous: answer a question, grounded in fetched tool data.

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

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

Explicitly states when to use it — 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' — followed by concrete domains (financial verdicts, legal claims, medical lookups, public statements). It names the alternative directly ('prefer ask_pipeworx for casual lookups') and discloses the causal cost difference of one extra LLM call. This is the clearest possible when/when-not routing 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?

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context that annotations cannot convey: the resolver contract (match confidence, alternatives, suggestions), the parent_event extractor, news fallback fields (_fallback_attempted, retry_after_sec), safety short-circuits for low-confidence/closed markets, and detailed resolution-rule risk (cancellation_rule parsing). This far exceeds what structured 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 extremely long and dense, presented as a block of paragraphs with no bullet points or section breaks. While every sentence carries useful information, the lack of structure makes it hard to scan quickly. It would benefit from bullet-point formatting for classifiers, fan-out examples, and response shapes.

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 3 parameters and no output schema, the description is exceptionally complete. It covers return value shapes (result.market, result.analysis, result.evidence), edge cases (low-confidence, closed markets, wide spreads), error handling (GDELT 429 fallback), and even resolution-rule subtleties (flat-50¢ void settlements). No meaningful aspect of the tool's behavior is left unexplained.

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 schema coverage is 100%, the description enhances parameter understanding by explaining how the 'market' parameter accepts slugs, URLs, or question text and how the resolver interprets them. It also clarifies the 'depth' parameter's consequences (fan-out behavior) and the 'include_raw' parameter's size implications, adding meaning beyond the schema's basic enum and type definitions.

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

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

The opening sentence clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the specific resource (Polymarket bet) and the action (research via data pull), and the use cases ('should I bet on X', 'what does the data say about Y') effectively distinguish it from sibling tools like polymarket_arbitrage or polymarket_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 explicitly states when to use the tool ('Use for "should I bet on X"...'), provides concrete query formats, and gives numerous fan-out examples. However, it does not explicitly name alternative tools or state when NOT to use it, relying instead on implicit differentiation from 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?

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds crucial behavioral context: it details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), explains that off-calendar fiscal years are handled correctly, states that results are sorted by primary metric, and mentions the return format (paired data + citation URIs). 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 yet well-organized. It front-loads the core purpose and usage preference, then systematically covers data sources, metric details, sorting behavior, and return format. Every sentence adds distinct value, with no filler or repetition. The length 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?

Given the tool's moderate complexity (two entity types, 2–5 values, no output schema), the description is impressively complete. It covers usage triggers, when to prefer it, what data is pulled for each type, how results are sorted, and what the return includes (paired data + citation URIs). Annotations cover safety (read-only, idempotent), and the description fills in all functional context needed for correct invocation.

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

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

The schema already describes both parameters with 100% coverage, but the description adds significant semantic meaning: it explains what each type returns (financial metrics vs. adverse-event/trial counts), gives concrete examples for the values array (['AAPL','MSFT'], ['ozempic','mounjaro']), and clarifies that sorting makes 'largest' readable from the top. This goes well beyond the structured schema.

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

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

The description clearly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs and resources, and distinguishes from siblings by explicitly naming the alternative 'sequential single-pack lookups' which it replaces.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides trigger phrases ('X vs Y', 'rank these companies') and notes that it replaces 8–15 sequential lookups, effectively stating the advantage over 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 cover the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), and the description adds substantial behavior beyond them: account/pricing gates, latency windows (15-60s, ~90s for thorough), gaps[] 'never invented', contradictions[] for standard/thorough, the hop/citation_uri fetchability guarantee, and semantic excerpting 'not head-truncated'. No contradiction with annotations — a read-only, idempotent research tool that never fabricates findings is fully consistent with the annotated 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 runs well over 400 words and contains a visibly corrupted, repetitive middle section with broken fragments and recycled sibling-routing phrases ('For a single lookup use ask_pipeworx... use ask_pipeworx_grounded' appearing multiple times). The opening and closing sentences are strong and front-loaded, but the garbled passage undermines readability and a coherent version would be roughly half 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?

For a complex tool with no output schema, the description carries full return-format duty and does so comprehensively: findings packet fields (verbatim evidence, confidence, source, fetched_at, citation_uri), gaps[], contradictions[], depth behavior, auth, pricing, and latency are all covered. Nothing essential is missing; the deduction is for the garbled middle section, which could cause an agent to misparse the sibling-routing instructions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it reveals that depth:'thorough' 'needs a paid plan', that an account is required before the tool works at all, and it narrates the hop mechanics (second iteration re-angles gaps, thorough chases leads) that map onto the depth enum. The question parameter is already well covered by both schema and description, so no additional credit is needed there.

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: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call', and details the mechanism (decomposes into facets, routes to 5,798 tools IN PARALLEL, returns a findings packet). It also differentiates from siblings and open-web search with the explicit 'this is NOT open-web search' and by naming ask_pipeworx/ask_pipeworx_grounded as the tools for other use cases. The corrupted middle passage adds noise, but the opening purpose statement is 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?

Guidance is explicit and complete: 'Best for broad/multi-part questions over structured data' with concrete examples, plus named when-not-to-use alternatives — 'For a single lookup use ask_pipeworx', 'For narrow research across structured sources, use ask_pipeworx_grounded', and 'If you are not signed in, use ask_pipeworx instead'. The depth tiers also carry usage implications (thorough is paid). The garbled repetitions of the sibling routing fragments are noisy but do not obscure the coherent guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes 'each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations by describing the output and efficiency benefit.

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 sized, front-loaded with the core purpose in the first sentence, then provides when-to-use, output details, and a sequencing instruction. The long list of domains is slightly verbose but serves the discovery use case.

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?

As a meta-tool discovery tool, the description covers purpose, usage, output (top-N tools with schemas), and readiness to call. No output schema is provided but the description explains the return content sufficiently. Annotations cover safety, so completeness is adequate.

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

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

Schema coverage is 100% with descriptions for query and limit, including aliases. The description's mention of 'describing the data or task' aligns with schema but doesn't add syntax or format details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes from sibling tools by framing itself as the discovery/meta tool ('Call this FIRST when you have many tools available'). The listed domains further concretize the scope.

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

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

Provides explicit use case: 'Use when you need to browse, search, look up, or discover what tools exist.' Also gives a sequencing instruction: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lacks explicit when-not-to-use or named alternatives, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral context: parallel fan-out across sources, soft-fail behavior for the USPTO sunset, 'sources_used/sources_failed' semantics, and the expected 'no data, not a bug' case for FDA products or empty sections. 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 nearly every clause carries valuable semantic or behavioral information. It is front-loaded with triggering phrases and the core purpose before enumerating sources and edge cases. Minor structure improvements could split it into sections, but it is not bloated with filler.

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

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

With no output schema, the description carries the full burden of explaining return sections, source-level failure semantics, input resolution, and edge cases. It explicitly covers cik/company_name, recent_filings URIs, fundamentals sorting, patents sunset, federal contracts, FDA products, hiring, news fallback, LEI, and source status fields. An agent has enough context to call this correctly and interpret results.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds meaning by explaining that `type` accepts 'company' or 'ticker' interchangeably with the same `value` shapes, that names resolve via SEC EDGAR, and that a private company returns resolved:false with a notes line. This goes beyond the raw schema without being redundant.

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 defines the tool as a 'full cross-source profile of a US public company in ONE parallel call' with explicit trigger examples like 'Tell me about X' and 'research Acme.' It distinguishes itself from 'chaining single-pack SEC/XBRL/news lookups,' though it does not explicitly name profile-adjacent siblings such as compare_entities or resolve_entity.

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 guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies behavior for private companies and accepted input forms. However, it does not state when NOT to use this tool or how it relates to comparison/resolution sibling tools.

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

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

Annotations already mark the tool as destructive (destructiveHint=true) and idempotent (idempotentHint=true). The description adds context that the memory was 'previously stored' and lists use cases, though it does not detail behavior for missing keys; the annotations cover idempotency.

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 with no filler, front-loaded with purpose, then usage conditions, then related tools. Every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description provides purpose, usage guidelines, and relationships to siblings. It is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100% with 'Memory key to delete' fully describing the key. The description's 'previously stored' adds marginal context, but overall the schema carries the meaning, so baseline 3 is appropriate.

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

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

The description opens with 'Delete a previously stored memory by key,' a specific verb ('Delete') and resource ('memory') that clearly distinguishes it from sibling memory tools like 'remember' and 'recall'.

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

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

Explicitly outlines when to use the tool: stale context, task completion, or clearing sensitive data. Also references siblings 'Pair with remember and recall' to position the tool within the memory workflow.

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

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

Annotations already confirm read-only/idempotent behavior. The description adds value by explaining the tool fetches the page, extracts key data, and outputs a markdown blob, plus that it's 'production-ready'. This goes beyond the safety profile and gives meaningful operational 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 composed of three focused sentences: what it does, what the output is, and when to use it. It is front-loaded with the core function and avoids unnecessary filler, though the 'useful for' list could be slightly trimmed without loss.

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

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

For a relatively simple tool with strong annotations and no output schema, the description covers the input (URL), the process (fetch/extract), the output format (text blob at site-root/llms.txt), and typical use cases. It lacks edge-case or limitation details, but is sufficiently complete for the tool's complexity.

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

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

The input schema already provides full descriptions for both parameters (url with example, max_links with default/maximum). The description does not add further parameter-specific details, but since schema coverage is 100%, 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 clearly identifies the tool's purpose: generating an llms.txt file for a URL. It specifies the verb (generate), resource (llms.txt), and the process (fetches page, extracts title/description/key links). It does not explicitly compare against sibling tools, but the function is distinct 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?

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. It does not mention exclusions or alternatives, but the guidance is 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, establishing a safe read operation. The description adds value by explicitly listing the returned fields (name, descriptions map, supportedLocales, defaultLocale, category id, update dates) and noting multilingual support, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the purpose, and then lists return fields. Every sentence provides essential information with no fluff or redundancy. It is concise 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?

Given the tool's simplicity (one parameter, strong annotations, no output schema), the description is fully adequate. It explains the resource, the input, and the return payload in enough detail for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds the practical hint that the id is 'e.g. the dataSourceId from a view', giving an agent useful context about where to obtain the UUID beyond the schema's generic 'Dataset (datasource) UUID'. This small addition raises the score.

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

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

The description clearly states the tool fetches multilingual metadata for one Statbel dataset by its UUID, specifying 'by its id' and referencing 'dataSourceId from a view'. This distinguishes it from sibling tools like list_datasets, which enumerates datasets, making the purpose specific and unambiguous.

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

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

The description implies usage when a specific dataset UUID is known, especially mentioning 'the dataSourceId from a view' as a source. It provides clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it. This aligns with 'clear context, no 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?

Annotations already declare read-only and idempotent behavior. The description adds value by listing the returned fields (name, locale, dataSourceId, dates) and the relationship to get_dataset via dataSourceId. 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?

Two sentences: first states purpose and input source, second explains return fields and next step. Every sentence carries useful information with no fluff, well front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description fully covers what the tool returns and how to use the result. It is complete enough for an agent to select and invoke it correctly.

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

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

Schema covers the id parameter fully (100% coverage). The description enhances it by noting the id is a UUID typically obtained from list_views, which is not in the schema's description, adding operational 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?

The description clearly states it retrieves metadata for one Statbel view by id, using a specific verb/resource. It distinguishes itself from siblings like list_views (which lists views) and get_dataset (which gets dataset descriptions) by specifying it returns view metadata.

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 explains the id comes from list_views, implying the tool is for fetching a single view's metadata after listing. It also directs users to get_dataset for language-specific dataset descriptions, providing a clear follow-up. Lacks an explicit 'when not to use' but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavior beyond this: substring matching across code and all-language descriptions, and a list of fields each dataset contains (name, descriptions map, category id, supportedLocales, last-update timestamps). 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 two sentences, front-loaded with the core purpose, and every sentence earns its place. The first sentence states the action and resource; the second explains the dataset structure and filtering. 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?

This is a simple list tool with two optional parameters, fully documented in the schema. The annotations cover the safety profile, and the description explains the filtering behavior and the fields in each returned dataset, effectively substituting for an output schema. This is 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 provides 100% coverage of the two parameters with clear descriptions. The description adds no additional parameter semantics beyond what the schema already states, so the baseline score of 3 is appropriate for high schema coverage.

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

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

The description opens with 'Browse/search Statbel datasets', clearly identifying the action and resource. It further details the dataset structure and filtering behavior, distinguishing it from sibling tools like get_dataset or list_views. This is a specific verb+resource with sibling differentiation.

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

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

The description clearly implies the usage context: browse/search datasets with optional case-insensitive substring filtering. It gives explicit filter semantics but does not mention alternatives or when not to use this tool. This is clear context without exclusions, earning a 4 rather than 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, openWorldHint, idempotentHint true, and destructiveHint false. The description adds context about the return fields and scope (caller's subscriptions), which is useful. It does not contradict the annotations and provides moderate additional behavioral insight.

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

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

The description is two sentences, front-loaded with the purpose, followed by return fields and usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and when to use it. The sibling tools list further clarifies its role in the subscription workflow, making 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 description covers 100% of the single parameter (include_inactive) with a clear description. The tool description does not add any extra semantic meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on the review/list action. The mention of specific fields adds further clarity.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to select this tool. 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 readOnly, idempotent, and openWorld hints, so the bar for additional behavioral disclosure is lower. The description adds value by specifying the returned fields (id, name, locale, dataSourceId, publish dates) and the case-insensitive substring matching across languages. It could also mention pagination or rate limits, but given the annotation coverage, this is solid.

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

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

The description is three sentences long, front-loaded with the primary purpose, and every sentence contributes meaning. There is no filler or redundancy, and it remains compact while covering resource context, return fields, and filter semantics.

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 moderately simple read-only list tool with three optional parameters and no output schema, the description covers the essential context: what a view is, what data is returned, and how filtering works. It does not mention default limit or sort order, but the schema documents the limit default, and the absence of an output schema is mitigated by listing the return fields. Overall, adequately complete for the tool's complexity.

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

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

Schema description coverage is 100% and already explains all three parameters with examples. The description adds minimal new information beyond restating the query filter behavior and the locale values (which also appear in the schema). It does not need to compensate for a schema gap, so the baseline score 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 uses specific verb+resource: 'Browse/search Statbel saved statistical views.' It clearly distinguishes from siblings like get_view (which retrieves a specific view) by describing this as a listing/search tool. It also explains the resource concept (pre-built table over a dataset), 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 states the core usage (browse/search views) and mentions filter options, but does not explicitly name alternatives or when-not-to-use scenarios. The distinction from get_view and list_datasets is implied by context but not stated directly, so it falls short of explicit 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 only indicate non-read-only and non-idempotent, but the description adds substantial behavioral context: rate-limited to 5 per identifier per day, returns a claim_token when filing without an account, team reads digests daily, and free/doesn't count against quota. This goes far beyond what annotations provide and aids agent expectation-setting.

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 long, every sentence earns its place: purpose, scope exclusions, token flow, rate limits, and roadmap impact. The description is front-loaded with the core action and maintains focus without redundancy.

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

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

With no output schema, the description explains the return token and how to use it to read fixes. It covers the contextual object, message format, and rate limits, fully equipping an agent to invoke the tool correctly without ambiguous gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving a concrete example of claim_token usage (pipeworx_feedback({claim_token:'pwfb_…'})) and clarifying that 'message' should be specific and not paste the end-user's prompt. This slightly elevates beyond baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool as a feedback channel for Pipeworx tools and explicitly excludes tools from other MCP servers, distinguishing it from sibling tools like ask_pipeworx.

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

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

The description gives explicit when-to-use guidance (bug, feature, data_gap, praise), when-not-to-use (feedback for other servers), and even provides an alternative (file with that server instead). It also explains the claim_token workflow, making usage conditions crystal clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond this by adding that the signal is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on window. These details meaningfully set expectations about data freshness and privacy without contradicting annotations.

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

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

The description is three tight sentences: the first explains what it returns, the second lists concrete use cases, and the third covers data source/caching. No filler or repetition. The structure is front-loaded with the most important information and remains 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 read-only aggregation tool with one optional parameter and no output schema, the description covers return fields, window semantics, use cases, data provenance, privacy, and caching. This is sufficient for an agent to decide when to call it and what to expect, without needing additional detail.

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

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

Schema coverage is 100% and the single 'window' parameter has a clear enum. The description adds interpretive value by explaining that shorter windows surface what's hot right now while longer windows show steady-state demand. This enriches the raw schema without being redundant.

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 returns top tools, top packs, and total call volume for what other AI agents are calling on Pipeworx. It names the specific resource ('Pipeworx trending') and adds window options, making it distinct from siblings like discover_tools. The verb 'Returns' is direct and the scope is immediately understood.

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 concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. While it doesn't explicitly name alternative tools or say when not to use it, the 'Useful for' list gives clear situational guidance. The mention of 'self-aggregating signal' helps set expectations about what kind of insight it provides.

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, non-destructive. The description adds substantial behavioral context: it explains the fill check (comparing theoretical vs realizable edge at 1000 shares/leg), warns 'do not trade it' when realizable_edge_pp ≤ 0, mentions skipped_low_similarity and placeholder filters, and outlines the return structure. 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 exceptionally structured: it uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and prescriptive lines. It front-loads the core purpose and then layers behavior details. Every sentence adds value; no filler. The length is justified by the complexity of the tool and the lack of an output schema to convey return semantics.

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

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

Given there is no output schema, the description compensates by fully specifying the response: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{...}'. It covers edge cases (thin legs, placeholder fraction, low similarity), explains the three operating modes, and mentions related tools for follow-up actions. This is a complete picture for an agent to use it correctly.

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

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

While the input schema describes the two parameters (event, topic), the description enriches them significantly: it gives concrete examples of event slugs ('fed-decision-may-2026') and topic seed questions, explains what each mode does with the parameter, and clarifies the no-arg behavior that is not apparent from the schema. Schema coverage is 100% but the description goes far beyond.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools by detailing the unique techniques and modes (trending_scan, event, topic). References to 'polymarket_fill_risk' for custom sizing further differentiate it.

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

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

Explicit usage instructions are provided for each mode: 'Call with NO args for a trending_scan', 'pass `event` for...', 'pass `topic` for...'. It also gives examples of inputs, explains when one mode is preferred over another (e.g., 'event (recommended for a specific market)'), and explicitly names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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

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

The description far exceeds the annotations' coverage. It discloses the model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), the caveats (24h-move warning, Fed signal unreliability), diagnostic output (_diagnostics), filtering knobs, caching behavior, and slippage assumptions. This is a wealth of behavioral context beyond the readOnly/openWorld/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 well-structured with clear sections (model families, response top-level, tradeable-edge knobs, diagnostics). It is front-loaded with the core purpose and each sentence contributes substantive information. While it could be condensed, the complexity of the tool 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?

For a tool with 9 parameters, no output schema, and no nested objects, the description is exceptionally complete. It explains the output structure (by_segment, fed_candidates, _diagnostics), the meaning of each segment, the filtering knobs, and even the reasoning behind design choices (Fed data unreliability, placeholder filters). An agent would have a thorough understanding of what to expect and how to invoke the tool.

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

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

The input schema already covers all 9 parameters with detailed descriptions, defaults, and examples (100% coverage). The tool description adds even more semantic depth, such as explaining why min_partition_leg_kelly exists (parent-level kelly is always 0 for basket trades) and how slippage interacts with edge evaluation. 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 opening sentence clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The 'Built for what should I bet on today' phrase establishes the intended use case and distinguishes it from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement rather than generic arbitrage.

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 when to use it ('Built for what should I bet on today') and implies a benefit over alternatives ('without paging hundreds of markets'). It does not explicitly name alternative tools or provide when-not-to-use guidance, but the context is clear enough for an agent to select this tool for daily betting discovery.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: response structures, snapshot TTL limits, cache-miss gaps, and the fact that decay is computed from daily closes rather than intraday data.

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

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

The description is structured with RESPONSE and LIMITS sections, and every sentence carries useful information. It is verbose, but given the tool's complexity (response fields, TTL, edge cases), it is appropriately sized; slight tightening could make it more concise.

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

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

With no output schema, the description fully documents the returned tracked[], expired[], and snapshot_dates[] structures, including field meanings, trends, decay calculations, and limitations like TTL and missing snapshots. It is self-contained 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 for both parameters is 100%, so baseline is 3. The description adds only marginal semantic value by restating defaults and introducing 'snapshot family' for window; there is no additional syntax or 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 uses a specific verb ('persistence and decay telemetry') and resource ('daily polymarket_edges snapshots') and answers a concrete question ('how long has this edge existed and is it shrinking?'). It clearly distinguishes from the sibling polymarket_edges tool by focusing on historical tracking 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?

It provides clear context for when to use the tool (assessing edge durability) and gives an illustrative comparison (fresh vs 3-week-old wide edges). However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full 5.

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

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

Annotations already declare readOnlyHint and non-destructive, but the description adds substantial behavioral context: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict), and highlights risk of partial basket fills converting arb into directional exposure. It also clarifies required modes (market vs event) and default behaviors, going far beyond what annotations convey.

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

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

The description is long but well-structured with REQUIRES, SINGLE-MARKET, and BASKET sections, front-loading the core purpose and using caps for the critical usage directive. It is dense and every sentence contributes, though it approaches the upper bound of length for a tool description; still, complexity justifies the size.

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

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

With no output schema, the description carries full burden for return values and does so comprehensively: it lists all key outputs (theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk), covers edge cases like partial fills, and specifies default clamps for size_usd. It is complete for a complex financial tool with two distinct modes.

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, but the description enriches parameter meaning by explaining size_usd semantics per mode (spend vs target proceeds vs settlement notional), defaults, and the REQUIRES constraint for market/event. It clarifies side options for both modes and how default side is chosen in basket mode, adding value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by referencing order-book depth and explicitly tying its use to polymarket_arbitrage and polymarket_edges signals, making its unique role 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?

It provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books; partial fills cause unhedged positions) and distinguishes single-market vs basket modes as alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context beyond that: compatibility warning codes, gross vs net spreads, fee modeling limitations, unknown-leg exclusion, skipped comparison counters, and the pairing_unverified caveat. This is far richer than the 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Some redundancy exists, such as repeating temporal_alignment_unknown semantics, but nearly every sentence earns its place given the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, temporal alignment object, skipped counters, fees_note, and per-entry flags. Nothing critical is left unspecified for an agent to call this 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 baseline is 3. The description adds value by explaining how the topic param and the explicit ticker/slug params interact as two modes, and that explicit params override the topic-mapped side. It also embeds concrete example formats like 'KXFED-26OCT' and 'fed-decision-in-june-825', reinforcing parameter usage.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states what the tool does. It does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edges, but the cross-venue focus is 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 usage modes: topic-based shortcuts and explicit ticker/slug pairings, including which parameters to use and how they interact. It also warns that pre-mapped topics are not necessarily tradeable. However, it does not say when to prefer this tool over the sibling polymarket tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable scope context (scoped by anonymous IP, BYO key hash, or account ID) and the fact that values are previously saved via remember, which goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence earns its place: behavior, usage, and scope/related tools. There is no redundancy or filler.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, this description is fully complete. It covers what the tool does, when to use it, how it relates to remember/forget, and the scoping model, providing the agent everything needed for correct invocation.

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

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

Schema covers 100% of the single 'key' parameter with a clear description. The description reinforces the omit-to-list behavior and enriches semantics by giving concrete examples of key values (user's target ticker, address, prior research notes), helping the agent understand what kinds of keys to expect.

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

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

The description uses a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings by explicitly naming remember and forget as complementary operations, making the tool's role unambiguous.

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

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

The description states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references related tools (remember to save, forget to delete), providing a clear workflow. However, it lacks explicit 'do not use when' conditions, though this is minor given the context.

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

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

Annotations already establish the read-only, idempotent, non-destructive profile. The description adds valuable context beyond that: it warns that mark_read:true 'flag[s] returned events read' so the next call only shows newer ones, and it discloses the return structure (source, citation_uri, raw event payload). This is a helpful disclosure of a subtle state-changing side effect.

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 five sentences, all dense with functional information. It front-loads the primary purpose, then proceeds logically to return format, filtering, side-effect flag, and alternative access. No filler or redundancy.

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

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

For a tool with no output schema, this description covers the return payload, filtering options, a state-changing parameter, and an alternative access method. It gives the agent enough to invoke and interpret the tool correctly without additional documentation.

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

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

With 100% schema coverage, the baseline is 3, but the description adds meaningful detail: it gives a concrete example for type ('sec_8k'), specifies the format for since ('ISO timestamp'), and explains the behavioral consequence of mark_read. It does not elaborate on limit or unread_only, but the schema already covers those clearly.

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: 'Pull fired events from your subscription feed.' It further clarifies the scope ('most recent alerts the evaluator has written to your persisted feed') and lists the content of each alert, making it distinct from sibling tools like list_subscriptions or 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?

The description provides clear context for when to use the tool ('Filter by type and/or since', 'Polls work fine') and even mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly reference sibling tools or state when not to use this tool, so it stops short of full 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 readOnly/idempotent annotations, the description discloses multi-source fan-out, fallback logic, USPTO soft-fail due to a sunset API, and the return structure. This gives an accurate picture of expected behavior and potential data gaps.

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?

Front-loaded with high-signal query examples and packed with essential operational details. Every sentence serves a purpose, and the length is justified by the multi-source 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 supplies the return shape (changes[] grouped by source, total_changes count, pipeworx citation URIs). It covers parameter formats, source fallbacks, API sunset caveat, and sibling differentiation, making it 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?

The schema already covers all three parameters with 100% coverage, so the baseline is 3. The description adds extra value by giving concrete format examples for `since` (ISO date or relative shorthand) and recommending '30d' or '1m' for typical monitoring.

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

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

The description clearly identifies the tool as a change feed for a company over a specified time window, with explicit user-intent examples. It names the concrete data sources (SEC EDGAR, GDELT/GNews, USPTO) and differentiates it from entity_profile.

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

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

It explicitly states when to use the tool (time-boxed 'what's new' queries) and when not to (static profile queries), recommending entity_profile as the alternative. It also documents fallback behavior for GDELT to GNews under rate limiting or 5xx errors.

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

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

Annotations already convey idempotent, non-destructive write behavior. The description adds valuable context: key-value scoping by identifier, 24-hour retention for anonymous sessions vs persistent for authenticated users, and the lifecycle with recall/forget. This complements rather than contradicts the annotations.

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

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

The description is compact and front-loaded, starting with the action and then providing targeted guidance. Each of the five sentences adds distinct information: purpose, when to use, storage model, retention behavior, and companion tools. No filler or redundancy.

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

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

For a simple 2-parameter write tool with no output schema, the description is complete. It covers invocation context, persistence semantics, authentication implications, and related tools, leaving minimal ambiguity for the agent. The retention nuance is especially helpful.

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

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

Input schema covers 100% of parameters with descriptive examples for key (e.g., 'subject_property') and value (any text). The description reinforces the key-value nature but does not add additional syntax or formatting details beyond what the schema already provides, so 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 opens with a specific verb 'Save data' and identifies the resource as a key-value pair for later reuse across conversation or sessions. It distinguishes itself from siblings by explicitly naming recall and forget as the complementary tools, making its purpose unique among the memory-related 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 provides clear 'Use when' triggers (resolved ticker, target address, user preference, research subject) and explains the persistence difference between authenticated and anonymous sessions. It mentions pairing with recall and forget, but it does not explicitly state when not to use this tool, so it lacks a full exclusion clause.

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 the annotations. It discloses that the tool cascades through multiple internal lookup endpoints, that LEI/FIGI enrichment degrades gracefully (the EDGAR identifiers still return), that ambiguous matches produce figi_candidates, that unresolved identifiers are explicitly under `unresolved`, that each identifier is labelled with its source, and that the ISIN-to-LEI mapping covers non-US issuers. These are behavioral traits an agent could not infer from the readOnlyHint/idempotentHint 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 long but every sentence carries substantive information: examples, supported sources, handle with ambiguity, degradation behavior, and input conventions. No fluff. However, the structure is a single dense paragraph; breaking it into bullets or sub-sections would improve scanability, but given the complexity the length is justified. It's front-loaded with the 'use FIRST' directive.

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 that handles two distinct entity types and three kinds of identifiers, the description covers the what-it-does, when-to-use, how-it-handles edge cases (unresolved, ambiguity, low-availability), and exactly what input formats are accepted. There is no output schema, so the description compensates by describing the response patterns (figi_candidates, unresolved, source labels). This is as complete as an agent needs to correctly invoke the tool in varied scenarios.

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

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

The schema covers 100% of parameters (type enum, value description). The description adds actionable semantics beyond that: for a bond, it instructs to pass the issuer exactly as printed and explicitly warns not to include trailing security-class words, because the FIGI lookup matches instrument names. It also explains what the `type` values map to in terms of source systems. This level of detailed usage guidance is exactly what an agent needs to call the tool correctly.

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

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

The description opens with concrete user-phrase examples ('What's the ticker for…'), then states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers'. It names the resource explicitly (identifier lookup for company/drug) and distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID', making its purpose unmistakable. It also enumerates supported entity types, so an agent knows exactly what it covers.

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', which is a clear trigger condition. It also details that the tool replaces 2-3 manual lookups and explains the types. It does not directly reference sibling tools like compare_entities or entity_profile, nor state when to prefer them, but the 'FIRST' directive plus the description of what it resolves is sufficient guidance for most selection scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details beyond that: it states the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also implies multiple call behavior and potential cost/time, which is useful context not present in annotations.

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

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

The description is front-loaded with the primary action, then explains the mechanism, use case, and return format in four concise sentences. Every sentence contributes value: purpose, process, example usage, and output details. No wasted words.

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

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

Given no output schema, the description effectively explains the return structure ('ranked list with score, confidence, signal density per entity'). It also conveys the internal tool dependency and the competitive context. The parameter schema is fully documented, and annotations cover safety, so the description fills in the remaining gaps (return format and use case). It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-specific meaning beyond the schema. The schema already explains entities and the subject/competitor distinction. The description mentions 'your brand + N competitors' but that's already captured in the entities parameter description. No additional parameter semantics are provided.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes itself from sibling tools like ai_visibility_check by explicitly mentioning it probes each entity with that tool and ranks them, making the multi-entity comparison 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 identifies a clear use case ('competitive AI-marketing audits') and provides an example scenario. It implies the tool is for multi-entity comparison and internally uses ai_visibility_check, which implicitly signals that ai_visibility_check is for single entities. However, it lacks explicit when-not-to-use instructions or named alternatives like compare_entities, 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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds concrete behavioral disclosures: composite fan-out across external services, graceful degradation on partial failures, bundlephobia's first measurement latency (5-30s), and the sources_failed field. These disclose important runtime characteristics not inferrable from annotations.

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

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

The description is dense but every clause earns its place: value proposition, data sources, trigger phrases, output fields, ecosystem scope, and failure semantics. It is front-loaded with the core purpose in one sentence and structured logically from what to when to what-comes-back.

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

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

Given there is no output schema, the description covers return values (summary fields, advisories, links, alternative versions) and failure modes (sources_failed, timeout behavior). It also addresses ecosystem scope and partial degradation, making the tool's behavior fully comprehensible without needing additional 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?

The input schema already has 100% parameter description coverage, including that version defaults to latest. The description adds no new parameter-level semantics beyond the schema; it focuses on output fields and behavior, which is useful but does not go beyond structural definitions.

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

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

The description clearly identifies the tool as a composite dependency vetting check for npm packages, naming specific data sources (deps.dev, bundlephobia) and the exact question it answers ('should I add this npm package'). It distinguishes itself from siblings by positioning as a one-call composite specifically for npm package evaluation.

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

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

Explicit usage trigger is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also states ecosystem limitations and directs non-NPM ecosystems to deps.dev:version directly, giving clear when-to-use and when-not-to-use guidance.

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

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

The description discloses rich behavioral details beyond the annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with 500-char windows, enforces a 200K char cap with truncation flagging. These are valuable operational insights not present 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?

The description is a single dense paragraph that front-loads purpose, then usage, then technical details. Every sentence contributes value, with 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 tool with no output schema, the description adequately explains the return format (passages with offsets and scores), algorithmic details, and input limits. It also mentions pairing with a sibling tool, making it fully self-contained 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 coverage is 100%, so baseline is 3. The description adds context by explaining that 'text' is the already-pulled record, 'query' is natural language, and 'limit' controls the number of passages. It also ties parameters to the output (offsets and scores), enhancing understanding beyond 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 opens with 'Semantic search INSIDE a fetched record,' which clearly states the verb (search) and resource (a fetched record). It distinguishes from sibling tools by emphasizing 'INSIDE' and 'fetched,' and explicitly pairs with ask_pipeworx_grounded, clarifying its niche.

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 guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for a specific workflow. This clarifies 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?

Annotations already cover idempotency, but the description adds substantial behavioral detail: OAuth requirement, supported subscription types with concrete examples, delivery channel behaviors (feed always on, email, SMS with verification and rate cap, webhook with signing secret and auto-disable). This goes well beyond the annotations.

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

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

The description is longer than average due to the tool's complexity, but it is well-structured: core purpose first, then requirements, then supported types, then delivery options. Every sentence earns its place with examples and constraints, making it dense yet scannable.

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

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

With no output schema, the description explicitly states the return value and covers critical operational details: webhook secret returned only once, SMS verification and cap, authentication requirements, and even how to pull the feed without subscribing. This provides a complete picture for using the create tool effectively.

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

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

The input schema has 100% coverage and detailed parameter descriptions, but the description adds extra semantic value, such as explaining that sec_8k items ["5.02"] means officer change, and clarifying that the feed is always on. This supplements the schema with useful context not present in the structured data.

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

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

The description begins with a precise action: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly identifies the resource (subscription), the verb (create), and the return value (new subscription id). It also distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 (proactive monitoring) and prerequisites (OAuth account, verified phone for SMS). It indirectly references alternatives like recent_alerts for pulling the feed, but does not explicitly name alternative tools or state when not to use 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond annotations: it returns live catalog data (dynamic), requires no arguments by default, and yields example questions with exact call shapes. It doesn't mention rate limits or auth, but for a read-only onboarding tool this is sufficient.

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

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

The description is dense but well-structured: front-loaded with natural language queries, then return details, then usage instructions. Every sentence carries information, though the long list of categories and meta-tools makes it slightly longer than ideal. Still, 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 the tool's complexity and the presence of annotations, the description is fully complete: it explains what the tool returns (category-bucketed examples), how to call it (with/without 'topic'), when to use it, and how it relates to sibling meta-tools. No output schema exists, but the return shape is described adequately.

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% (only 'topic'), so baseline is 3. The description adds meaning by explaining default behavior ('Omit for a cross-category spread') and giving concrete examples ('finance', 'pharma', 'betting'), which enriches the schema's enum-like description.

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

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

The description states a specific verb+resource+scope: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It clearly distinguishes from siblings by positioning as the FIRST tool to use for discovery, and details the output: category-bucketed example questions with exact tool and argument shapes.

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

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

Explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' This names alternatives and establishes priority over sibling tools, making the usage context unambiguous.

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

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

The description adds key behavioral details beyond the annotations: the row is deactivated not deleted, and historical events stay available via recent_alerts. It also discloses ownership enforcement, which is an important access-control behavior. This goes beyond the basic readOnly/destructive hints.

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

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

The description is two sentences long, front-loaded with the main action. Each sentence contains distinct value: cancellation, ownership, and deactivation behavior. There is no redundant or filler content.

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

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

The description explains the outcome (deactivated), the ownership restriction, and the impact on historical data. It does not specify the return value or error handling, but for a simple cancellation tool with a single parameter, this is a minor omission.

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 describes the lone 'id' parameter as 'Subscription id (uuid) returned by subscribe,' providing full coverage. The description only repeats 'by id' without adding extra meaning, so it does not outperform the schema baseline.

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

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

The description begins with 'Cancel a subscription by id,' a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on the cancellation action, and further clarifies the semantics with ownership and soft-deletion details.

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

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

The description gives clear context on when to use this tool: to cancel a subscription while preserving historical events. It does not explicitly name alternatives, but the context implies using this when you want to stop alerts without deleting history, and it notes an important constraint (only your own subscriptions).

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description goes well beyond by disclosing the two execution paths, the verdict taxonomy, the inclusion of pipeworx:// citations, and the precise semantics of 'could_not_verify' (carries verification_error, must not be shown as evidence) and 'unsupported'. 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 earns its place: examples, usage trigger, path routing, return details, and caller-critical caveats. It opens with the most actionable content (what the tool does) and progressively layers detail, never repeating schema information. Structure is highly efficient for its 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?

Despite having no output schema, the description fully explains return values (verdict, actual value with citation, reasoning), enumerates all verdicts, distinguishes error states, and covers fallback behavior. It also explains efficiency benefits relative to prior multi-call flows. For a 2-parameter tool with complex behavior, 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 coverage is 100%, but the description adds valuable meaning: it gives concrete example claims, explains that tolerance_pct overrides the wording-implied tolerance, specifies the default cap (5), and suggests setting 1–2 for hallucination detection. This goes well beyond the schema's basic descriptions.

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

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

The description opens with explicit natural-language query examples and states 'natural-language claim verification against authoritative sources' — a specific verb+resource pairing. It clearly differentiates from sibling tools by describing a two-path architecture (SEC EDGAR/XBRL vs grounded pipeline) and explicitly notes it replaces 4–6 sequential calls, making its unique role 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?

Gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It then subdivides use cases (company-financial claims vs any other factual claim) and provides crucial exclusion guidance for the 'could_not_verify' outcome, telling callers not to treat it as evidence. This is clear when-and-when-not guidance.

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