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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the bar is lower. The description adds context: it routes to one of many tools, returns structured answers with stable citation URIs, makes one fast call, and works on every tier. It does not contradict the annotations and provides useful behavioral detail beyond the minimal 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 long but well-structured: it leads with the most important 'PREFER OVER WEB SEARCH', lists domains, explains behavior, provides examples, and then clarifies when to step up to alternatives. It is wordy in places (e.g., 'or anything requiring authoritative structured data with citations' could be trimmed), but every sentence serves a purpose and the structure is easy to scan.

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

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

For a tool of this complexity (a router over thousands of tools), the description is quite complete: it covers purpose, usage, output (citations), performance (one fast call), and differentiates from siblings. It does not mention error handling or edge cases, but given the annotations and examples, it is more than adequate for an agent to decide when to use it.

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

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

The schema has 100% coverage with a single 'question' parameter and its aliases, so the baseline is 3. The description does not teach syntax but rather explains the kind of questions to ask, which is more about usage context than parameter-specific semantics. The schema already documents aliases and examples, so the description adds no additional parameter-level meaning.

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

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

The description uses a specific verb ('routes', 'answers', 'returns') and clearly states the resource (verified data sources with citations). It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research and specifying when to use them instead. The scope is precise: broad factual queries about real-world data, with examples.

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 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' with examples, then provides conditional alternatives: 'for a hallucination-resistant single answer use ask_pipeworx_grounded' and 'for a broad/multi-part question... use deep_research'. This clearly defines when to use and when not to use, naming alternatives and conditions.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description discloses that it is a full working router with no fallback, that candidates may alter routing behavior when active, and that it currently matches ask_pipeworx exactly. This adds meaningful behavioral context about the experimental nature and the fact that it is not a stub, enhancing transparency.

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

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

The description is a compact three-sentence paragraph that front-loads the key point (beta of ask_pipeworx), then covers current state, usage, and nature. Every sentence contributes essential information without fluff, making it highly 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?

For a simple question-parameter tool with no output schema, the description is thorough: it explains the relationship to ask_pipeworx, mentions the identical response shape, current candidate status, and that it is a fully functional router. It provides enough context for an agent to use it correctly without gaps.

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

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

The schema already provides 100% coverage for all six parameters, all described as aliases for 'question'. The description does not add any additional parameter-specific information, which is acceptable given the schema's completeness. It does not need to repeat alias details, so a baseline score of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, identically routing to the same 5,564 tools with the same arguments and response shape. It distinguishes itself from siblings by explicitly naming ask_pipeworx and positioning itself as the experimental variant, which is a specific and unambiguous purpose.

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

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

It provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' This tells the agent when to select this tool over alternatives, and the context about candidate retirement and current exact match clarifies the current state. The note that results are compared against the stable router implies a testing role, offering clear when-to-use direction.

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, but the description adds valuable behavioral context: costs an extra LLM call, returns structured evidence and refusal reasons, and explains the extraction constraint. This goes far 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 three sentences with a clear flow: mechanism, return/refusal format, and usage guidance with cost tradeoff. Every sentence carries essential information and 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 tool with no output schema, the description thoroughly explains the return shape, refusal reasons, and the added cost. It also covers routing and source context, making the tool fully self-contained for an agent to decide when to invoke it.

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

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

Schema description coverage is 100% and all six parameters are aliases for the same 'question' string. The description adds no parameter-level nuance, but since the schema already fully documents the parameters, a baseline score of 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that routes through Pipeworx tools and extracts answers grounded in tool results. It explicitly distinguishes from ask_pipeworx by emphasizing high-stakes reads and the refusal mechanism, making sibling differentiation clear.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives a direct alternative: 'prefer ask_pipeworx for casual lookups.' This is a textbook example of usage vs alternative guidance.

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

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

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?

With annotations indicating readOnlyHint, this tool is not destructive and has no conflicts. The description is explicit about the tool's behavior, such as the 'depth' parameter and 'for a single lookup use ask_pipeworx' — so the description is transparent. It also states 'not open-web search' and 'decomposes your question into focused facets' as the main description.

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

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

The description is quite long and dense, packing many clauses. However, it's front-loaded with the most critical info (account requirement, alternative tool), and each sentence adds value. It's structured with semicolons and parentheses, but could be more concise. Given the tool's complexity, length is somewhat justified.

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

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

The description covers account requirements, alternative tools, scope, limitations (gaps for news topics), iteration behavior, time expectations, citation mechanism, and semantic excerpting. With only two parameters and no output schema, this is exhaustive. The tool is complex, and the description fully prepares the 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?

The description adds rich context to parameters: 'depth' is fully explained with 'quick=3 (single hop), standard=3 (default; adds a gap-recovery hop...), thorough=6 (paid; adds a full iterative hop...)'. The 'question' parameter is implied ('Broad/multi-part is fine — decomposition is the point'). Schema coverage is 100% so baseline is 3, but the description adds beyond that.

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: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call — this is NOT open-web search.' The purpose is specific and distinguishes from siblings like ask_pipeworx and deep_research.

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

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

excellent — describes when to use deep_research vs ask_pipeworx, and provides clear alternatives. The description gives explicit 'use ask_pipeworx' as a fallback and contrasts the use cases.

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, idempotentHint, and non-destructive behavior. The description adds substantial context: parallel fan-out across multiple sources, specific return fields, the 'LATEST 10-K' filtering, the USPTO API sunset soft-fail, and the GDELT→GNews fallback. 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 rich but efficient, with example queries front-loaded and a well-ordered breakdown of outputs, sources, and fallbacks. It is slightly longer than strictly necessary, and the input-format caveat duplicates the schema, but every other sentence carries useful information.

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

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

Despite lacking an output schema, the description enumerates all return components (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), mentions limits ('up to 5'), and explains failure modes (patent API sunset soft-fail, news fallback). This is thorough for a read-only research tool.

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

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

The schema already fully documents both parameters with descriptions and examples (ticker/CIK format, names not supported, use resolve_entity). The description repeats this information almost verbatim, adding little new meaning beyond the schema. Baseline 3 is appropriate due to 100% schema coverage.

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

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

The description starts with concrete example queries and states a specific action: 'full cross-source profile of a US public company'. It distinguishes itself from siblings like compare_entities and resolve_entity by emphasizing the holistic single-call scope and explicitly discouraging chained single-pack lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names an alternative tool for a specific case: 'use resolve_entity first if you only have a name', making the decision boundary 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 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?

Beyond the readOnlyHint and other annotations, the description discloses compatibility_warning logic, temporal_alignment implications, and skipped_cross_type/subtype counters. It also warns that 'pre-mapped ≠ tradeable', providing critical behavioral context 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence adds necessary context for a complex tool, though it could be slightly more concise in places.

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 absence of an output schema, the description fully explains the response structure, safety fields, and edge-case behavior. It is comprehensive enough for an agent to understand when and how to 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%, but the description adds the mode concept and explains how kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. This enriches the schema's basic descriptions with practical usage semantics.

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

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

The description explicitly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', which clearly identifies the tool's function and differentiates it from siblings like polymarket_arbitrage. It is specific with a verb+resource and explains the core output.

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

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

The description thoroughly explains two modes (topic shortcuts vs explicit ticker/slug) and cautions that most pre-mapped topics return compatibility_warning, guiding when the tool is reliable. It provides clear context but does not explicitly name alternative tools or when to use them instead.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: graceful degradation ('LEI/FIGI enrichment degrades gracefully'), source labeling, explicit unresolved identifiers, and details on cascading internal lookups. No contradictions with annotations.

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

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

The description is long but every sentence adds value. It starts with concrete examples, then usage advice, then detailed supported-type descriptions. While slightly verbose, the length is justified by the tool's complexity (multiple data sources, graceful degradation). A minor split or bullet-pointing could improve scanability, but it remains highly informative.

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

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

Given no output schema, the description explains what is returned (identifiers with source labels, unresolved list). It covers graceful failure, input alternatives for company (ticker, CIK, ISIN), and resolves the 'drug' type to RxCUI with citation. For a tool that cascades across multiple lookups, the description provides complete contextual understanding 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?

Input schema has 100% description coverage, but the description adds essential context beyond the schema. For the 'value' parameter, it explains that for 'company' it accepts ticker, CIK, ISIN, or company name, and for 'drug' it accepts brand or generic name. It further describes how an ISIN resolves to the legal entity via GLEIF. This depth greatly aids correct invocation.

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

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

The description clearly states the tool resolves names to canonical/official identifiers needed by other tools. It specifies supported entity types ('company', 'drug') with concrete examples like 'what's the ticker for...' / 'find the CIK for...'. This distinguishes it from sibling tools like compare_entities or entity_profile, which operate on already-resolved IDs.

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 advises 'Use FIRST whenever you have a name but need an ID', positioning it as a prerequisite step. It provides natural-language triggers and explains that one call replaces 2-3 manual lookups. It does not explicitly state when not to use it (e.g., for detailed entity profile, use entity_profile instead), but the context is clear enough from the sibling list.

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

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

Annotations already declare readOnlyHint, 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.