Dbnomics

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

The description discloses key behavioral traits: default model is free, Anthropic requires user's own key (BYO), and the return structure includes per-model and combined views. These details complement the annotations (readOnlyHint, etc.) without contradiction, providing actionable guidance.

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

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

The description is concise (4-5 sentences), front-loads the core purpose and output, explains optional parameters, describes return structure, and lists use cases. Every sentence adds information without redundancy.

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

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

Given the tool's complexity (multi-model, optional auth), the description covers purpose, usage, model options, and return structure. It lacks explicit details on error handling or rate limits, but provides sufficient context for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the default model, the optional nature of models and apiKey, and providing examples for entity and context. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's action ('probe one or more LLMs'), the specific resource ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes itself from siblings by focusing on AI visibility scoring, a unique function among the listed siblings.

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

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

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to provide an API key for Anthropic. It implicitly differentiates from siblings by its focus, but does not explicitly state when not to use this tool or compare directly to alternatives.

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

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

The description adds behavioral context beyond the annotations: it mentions routing to 5,635 tools, returning structured answers with stable citation URIs, and states it works on every tier. Annotations already declare readOnlyHint and idempotentHint, and the description doesn't contradict them. It could mention potential error cases or rate limits, but the provided behavioral details are meaningful and helpful.

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

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

The description is verbose but well-structured: it starts with the most important guidance ('PREFER OVER WEB SEARCH'), then lists common use cases, provides examples, and contrasts with siblings. While long, each section serves a purpose and the information is front-loaded. It could be trimmed, but the organization aids comprehension. A score of 4 reflects good structure despite length.

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

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

Given the tool's complexity (a meta-routing tool with no output schema), the description covers the key aspects: what it does, when to use it, examples, and alternatives. It mentions the return format (structured answer with citation URIs) but doesn't detail potential edge cases or failure modes. For an agent deciding whether to invoke it, the description is sufficient, though some detail about output interpretation could improve completeness.

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

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

The schema documents all six parameters as aliases for 'question', and schema description coverage is 100%. The description does not add extra param semantics beyond the schema, but the schema itself is clear. The description includes examples, which indirectly illustrate usage, but it doesn't explain nuances like formatting constraints. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: it answers factual questions about real-world data by routing to a large set of verified sources, returning structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role obvious. The verb 'routes' and resource 'question to 5,635 tools' is specific and unambiguous.

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

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

The description gives explicit guidance on when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists example queries. It also specifies when NOT to use it by naming alternatives: 'for a hallucination-resistant single answer use ask_pipeworx_grounded' and 'for a broad/multi-part question use deep_research'. This level of routing guidance is exemplary.

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, openWorldHint=true and destructiveHint=false, covering the safety profile. The description adds genuinely useful context beyond those: the candidate-routing experiment lifecycle, the current no-active-candidate state with its retirement date (2026-07-26), the fact that it currently matches the stable router exactly, and that results are compared for merge decisions. No contradiction with annotations; the description complements them well.

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 opens with the most important fact ('Beta version of ask_pipeworx: identical universal router') before detailing state and usage. Each sentence earns its place — version status, current configuration, usage instruction, and fallback behavior. Slightly verbose but every clause is informative; nothing is 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 high-complexity router with no output schema, the description covers the essential ground: what it routes, how it differs from stable, its reliability status (a full working router, not a fallback stub), and returns via 'same response shape' as ask_pipeworx. Reference to the stable tool's response shape compensates for the absent output schema. Complete enough for an agent to call 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%, so the schema already documents all six parameters and their relationship (five are aliases for the single required 'question'). The description adds no parameter detail, but none is needed — the schema carries the full burden. Baseline 3 is appropriate since the description does not need to compensate.

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

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

The description identifies the resource ('universal router' over 5,635 tools) and clearly distinguishes it from the stable sibling ask_pipeworx by its beta status and experimental routing. It explicitly states its scope is identical to ask_pipeworx ('same 5,635 tools, same arguments, same response shape'), so an agent cannot confuse it with ask_pipeworx_grounded or the search/entity 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 names the alternative (ask_pipeworx) and gives the selecting condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also states the fallback ('Falls back to nothing — this IS a full working router'), ensuring the agent knows not to treat it as a stub or pre-requisite step. This is explicit when-to-use guidance with no ambiguity.

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 nondestructive. The description adds substantial behavioral context beyond those: the extraction rule (only from tool result), the explicit refusal mechanism with a full enum of refusal_reason values, the success return shape, and the cost overhead. This goes well beyond what annotations provide.

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

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

The description is longer than average but every sentence serves a distinct purpose: purpose, routing, extraction rule, return format, usage policy, and cost trade-off. It is well-structured with the purpose front-loaded. It could be trimmed slightly (e.g., the list of refusal reasons might be inferred from the enum in the schema if it existed), but the level of detail is justified for a high-stakes tool.

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

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

For a complex tool with no output schema, the description fully specifies the success and failure return shapes, including all possible refusal_reason values. It also covers routing, usage policy, and cost. An agent can determine exactly when to call it, what to expect, and how to handle refusals. Nothing critical is missing.

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

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

Schema coverage is 100% — every parameter (question and five aliases) has a clear description indicating it is an alias. The tool description adds no additional meaning about the question parameter; it only implies natural-language input through the usage guidance. Since the schema fully documents the parameter, a baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description opens with a specific mode identifier ('Hallucination-resistant answer mode') and immediately clarifies its routing ('Same routing as ask_pipeworx') while distinguishing itself by the extraction behavior ('EXTRACTS the answer using ONLY what the tool result contains'). This differentiates it clearly from the sibling tool ask_pipeworx, telling an agent exactly what it does and how it differs.

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

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

The description gives explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on...') and when-not-to-use ('prefer ask_pipeworx for casual lookups'). It also names the alternative (ask_pipeworx) and provides the cost trade-off ('Costs one extra LLM call'). This is model usage guidance with no ambiguity left.

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 extensively details behaviors beyond annotations (readOnly, openWorld, idempotent, non-destructive). It explains market resolution with confidence levels, fan-out logic with examples, response shapes, safety short-circuits, cancellation rules, and fallback mechanisms. No contradictions with annotations; the description adds significant behavioral context.

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

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

The description is well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with core purpose. However, it is quite lengthy and includes detailed classifier lists and fan-out examples that could be summarized. Every sentence adds value, but some redundancy exists (e.g., repeating safety mechanisms). Still earns its length for a complex tool.

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

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

Given the complexity of the tool (multiple data sources, rich response, no output schema), the description is remarkably complete. It documents response fields (market, analysis, evidence), resolver contract with confidence and alternatives, parent event extraction, news fallback, safety checks, wide-spread handling, and cancellation rules. Covers all necessary context for an agent to use the tool appropriately.

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 3 parameters have descriptions in the schema (100% coverage). The description further clarifies the 'market' parameter input formats (slug, URL, text), explains the 'depth' enum values with their implications, and provides guidance on 'include_raw' (recommended false, use true for specific needs). This adds substantial meaning beyond schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and core actions (resolve, classify, fan-out, return evidence + comparison). The use cases ('should I bet on X', 'what does the data say about Y') help distinguish it from sibling tools like polymarket_edges or polymarket_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?

Explicit guidance on when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool provides limited results (low-confidence matches, closed markets, illiquid spreads) and how to interpret them. No explicit when-not-to-use, but the context and examples implicitly differentiate from sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds useful behavioral context: handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and replaces many sequential lookups. 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 relatively long but well-structured with examples and clear use cases. It front-loads the purpose and every sentence adds value, though it could be slightly 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?

Given the complexity of comparing two entity types with multiple metrics, the description covers key aspects: data sources, sorting, citations, and parallel execution. No output schema exists, but the description mentions return format. Lacks details on error handling or timeouts.

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

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

The schema covers both parameters with descriptions, but the description adds concrete examples (tickers for company, drug names) and explains what data is pulled for each type (SEC EDGAR 10-K data for companies, FAERS/FDA trials for drugs). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses explicit trigger phrases like 'compare X and Y' and 'which is bigger', and distinguishes from sibling tools by stating 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups'.

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

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

The description explicitly tells when to use this tool (comparing entities) and advises preference over sequential lookups. It implies when not to use by contrasting with single-entity lookups, but does not explicitly name alternatives like entity_profile.

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, etc., but the description goes far beyond: it explains decomposition into facets, parallel routing to 5,635 tools, the findings packet structure (verbatim evidence, confidence, source, gaps[], contradictions[]), the hop field, citation_uri fetchability condition, semantic excerpting, and latency expectations. It even notes when results are likely empty (breaking news). This is comprehensive behavior disclosure that a safe-read tool rarely has.

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 intentionally dense. It front-loads the most critical operational constraint (account requirement and fallback), then defines the tool's core value, then usage guidance, then depth nuances, then output and latency. Every sentence adds unique information; there is no fluff or redundancy. The structure is logical and scannable despite length.

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

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

Given the tool's complexity (2 params, no output schema), the description covers all necessary context: prerequisites (account, plan), when to use vs. alternatives, expected behavior and output format, limitations (gaps[], breaking news), and performance. An agent has everything needed to invoke it correctly and interpret results, especially since there is no output schema to reference.

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 enriches the 'depth' parameter by defining what each enum value means operationally (quick=3 single hop, standard=3 with gap recovery, thorough=6 with iterative chasing), and clarifies that 'question' is natural language and can be broad. It adds meaning far beyond the schema's basic descriptors.

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 precise purpose: 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources... in ONE call'. It explicitly contrasts with open-web search and distinguishes itself from ask_pipeworx via scope and method. The verb 'research', resource 'data sources', and the qualifier 'NOT open-web' make the purpose unambiguous and separable from siblings.

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

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

The description gives explicit usage direction: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also specifies account requirements and the fallback when not signed in. This is textbook when-to-use/when-not guidance.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds that returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' providing valuable behavioral detail beyond annotations.

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

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

The description is front-loaded with purpose and includes a comprehensive list of data domains, but is slightly long. Still, every sentence adds value, earning a 4.

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

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

For a discovery tool with no output schema, the description fully covers what the tool returns (tools with schemas and examples) and how to use it, making it complete and actionable.

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 mentions the query parameter and limit, and lists aliases for query, but adds little semantic depth beyond what the schema already provides.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates many specific data domains (SEC filings, FDA drugs, etc.), making the tool's purpose highly specific and distinguishing it from siblings like search or compare_entities.

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

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

Explicit instruction to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)' provides clear when-to-use guidance and implies not to use when you already know the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: fanning out across multiple sources, returning specific fields, patent API sunset with soft-fail, and news fallback (GDELT→GNews). No contradictions.

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

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

Description is comprehensive but slightly long. Starts with concrete examples, states preference, then lists outputs. Every sentence adds value, but could be slightly more concise without losing information.

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

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

Given the complexity of the tool (multiple data sources, fallbacks, soft-fail), the description is thorough. No output schema exists, but description details all returned fields. Mentions limitation about patents and parallel call nature. Complete for informed decision.

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

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

Schema coverage is 100%, but description adds meaning: for 'type' it explains 'Only company supported today; person/place coming soon'. For 'value' it explains ticker or zero-padded CIK, and explicitly states names not supported. This goes 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 clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call'. It uses specific verb+resource (e.g., 'Tell me about X') and lists all data sources and returned fields, distinguishing it from siblings like 'resolve_entity' which resolves names.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also clearly states when not to use: 'names not supported (use resolve_entity first if you only have a name)', providing direct alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description doesn't need to repeat that. It adds a genuinely useful behavioral detail: 'If a filter matches nothing, the response lists the dimension codes the dataset actually accepts.' This aids error handling and goes beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the core purpose and followed by a concise usage context and a relevant edge-case behavior. Every sentence earns its place with 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?

Given the tool's 6 parameters, nested objects, and presence of an output schema, the description is concise but sufficient. It covers the primary use case and a key behavioral nuance, while the schema and annotations fill in parameter and safety details. It doesn't cover pagination or observations, but those are clearly documented in the schema, 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 description coverage is 100%, with detailed explanations for each parameter, including the dimensions filter semantics and the observations flag. The description adds only conceptual context ('structured filters', 'provider+dataset') without introducing new parameter-level meaning. Thus, the baseline 3 is appropriate as the schema does the heavy lifting.

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 action ('browse series') with a clear resource ('series') and mechanism ('structured filters'). It further clarifies the use case of enumerating series by dimensions for a given provider and dataset, which distinguishes it from related tools like get_series (which likely retrieves a single series) and list_datasets/list_providers.

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 phrase 'Useful when you know the provider+dataset' explicitly indicates the prerequisite context for use. It does not name alternatives or state exclusions, but the implied contrast with tools that discover datasets/providers gives clear guidance. A minor gap is the lack of explicit 'when not to use' scenarios.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds value by clarifying why you would use it (clear sensitive data) and how it relates to sibling tools, 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?

Two concise sentences – the first states the action, the second gives usage guidance. No wasted words, front-loaded with purpose.

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

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

For a simple deletion tool with one parameter and no output schema, the description covers purpose, when to use, and relationships with siblings. Fully 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% and the schema describes the parameter ('Memory key to delete'). Description adds no additional parameter information, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' – a specific verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall' as paired tools.

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

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

Explicitly states three scenarios for use: stale context, task completion, clearing sensitive data. Implicitly contrasts with remember and recall as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds detail on the process (fetches page, extracts title/description/links, emits markdown) and output format, which supplements the annotations. No contradictions.

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

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

Three sentences: first states the core function, second explains the process, third provides use cases. No superfluous content. Information is front-loaded and efficiently presented.

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 two parameters and no output schema, the description fully covers the purpose, process, and output format. It explains how the output is used, making it complete for an agent to understand and invoke correctly.

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

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

Both parameters have full schema descriptions (100% coverage). The parameter descriptions are clear and concise. The tool description does not add new meaning beyond the schema, merely reiterates the purpose of the parameters. Thus, 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?

Description clearly states the tool generates an llms.txt file for a URL, with specific actions (fetches, extracts, emits). It distinguishes itself from sibling tools, which are mostly search, analysis, or data retrieval tools. The purpose is unambiguous.

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

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

Description explicitly lists use cases: getting a client's site indexed, drafting llms.txt for own project, auditing competitor. It provides context for when to use the tool, though it doesn't explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by indicating that including observations returns data points, which is beyond annotation coverage. No contradictions.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the action and resource, then provides the identifier format and optional behavior efficiently.

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, the output schema exists, and annotations cover safety, the description is complete. It tells agents exactly what they need: what it fetches, how to identify it, and the key optional parameter.

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 all parameters with descriptions (100% coverage). The description only restates the observations parameter's function without adding new 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 clearly states the tool fetches a specific time series using the verb 'Fetch' and identifies the resource. It specifies the identifier components (provider, dataset, series_code), distinguishing it from sibling tools like 'find_series' which searches for series.

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 indicates usage when exact identifiers are known and mentions the optional observations parameter. However, it does not explicitly state when not to use or compare to alternatives like 'find_series', leaving some ambiguity for agents.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the description adds meaningful behavioral context: pagination via limit/offset, the return of code/name/dimension metadata, and the single-provider scoping. It does not contradict annotations.

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

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

Two sentences, with the first verb ('enumerate') front-loaded. The opening phrase 'DBnomics economic time-series aggregator' is slightly verbose but provides useful context. Every sentence contributes to purpose or usage, so it 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?

Given the schema and annotations, the description is complete for a list tool: it covers pagination, return contents, and integration with sibling tools. The output schema exists, so detailed return structure is not needed in the description. No significant gaps remain.

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

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

Schema description coverage is 100%, with all three parameters described and example values provided. The description does not significantly add meaning beyond the schema, merely reinforcing that provider is a DBnomics code, which is already in schema examples.

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

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

The description clearly states the tool enumerates datasets for a specific DBnomics provider code, using a specific verb and resource. It distinguishes from siblings by mentioning that returned codes are what get_series and find_series expect, and provides concrete provider 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?

The description provides clear context for when to use the tool (to list datasets for a provider) and even indicates downstream usage ('those codes are what get_series and find_series expect'). However, it lacks an explicit 'do not use when' or comparison with list_providers, so it's not fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context by stating the approximate count (80+) and what data is returned (codes and names), which aligns with annotations and adds value beyond them.

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

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

Two sentences with no wasted words. The first sentence states the core action and scope; the second provides usage guidance. Front-loaded and 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?

Given the tool has no parameters and an output schema exists, the description is complete. It covers the tool's output and how to use it with siblings. No gaps.

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

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

With zero parameters, the baseline is 4. The description does not need to add parameter details, but it does mention the output content (provider codes and names), which indirectly clarifies what the tool provides.

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

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

The description clearly states the action ('List all statistics providers'), specifies the resource ('DBnomics'), and notes the content (codes and names). It also hints at linkage with sibling tools, but the core purpose is distinct from tools like list_datasets or get_series.

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 to use provider codes with list_datasets and get_series, guiding the agent on downstream usage. It does not explicitly say when not to use, but the simplicity of the tool (no parameters) makes that unnecessary.

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, destructiveHint=false. Description adds value by listing exact return fields and default filtering for active subscriptions.

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

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

Two sentences with no waste. First sentence defines purpose and output; second gives usage guidance.

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

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

For a simple read-only list tool with one optional parameter, the description covers purpose, behavior, output fields, and usage. No output schema needed; annotations cover safety.

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

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

Schema description coverage is 100%. The one parameter is fully described in the schema; description does not add extra 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like subscribe/unsubscribe by explaining its usage.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Gives clear context for when to use.

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

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

While annotations only state readOnlyHint=false, the description goes well beyond structured data by disclosing important behavioral traits: rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, returns a claim_token for later retrieval, and that the team reads digests daily. It also explains the pattern of passing the token back to read status and changes. 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?

Though longer than typical descriptions, every sentence serves a purpose. It opens with a clear one-line purpose, then systematically covers use cases, exclusions, follow-up behavior, and rate limits. The information is front-loaded and logically organized, with 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?

Given the tool's complexity (4 params, nested objects, no output schema), the description is remarkably complete. It explains return behavior via claim_token, rate limits, free status, and connection scoping. The absence of an output schema is compensated because the description explicitly states what filing returns ('a `claim_token`') and how to use it later. No gaps remain for an agent to misuse the tool.

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

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

The schema already documents all 4 parameters with 100% coverage, providing a baseline of 3. However, the description adds meaningful guidance beyond the schema: it clarifies the purpose of `context` as optional structured context, advises 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt', and specifies that the `claim_token` should be passed 'with no other arguments'. This enriches parameter usage beyond the schema descriptions.

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

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

The description opens with a specific, action-oriented purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by identifying it as the feedback channel for Pipeworx tools, while all other siblings are data/research tools. The verb+resource combination ('Tell the Pipeworx team') leaves no ambiguity about what the tool does.

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

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

The description explicitly provides when-to-use scenarios ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and exclusions ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). It also gives guidance on how to phrase feedback and how to use the claim_token for follow-ups.

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

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

The description adds significant behavioral context beyond the annotations: the data source (CF analytics-engine), absence of PII, caching behavior (5min-1h depending on window), and the differential behavior of window options (shorter windows show hot content, longer show steady-state). This complements the annotations (readOnlyHint, idempotentHint) effectively.

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

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

The description is concise with no filler. It front-loads the core purpose, then provides usage guidelines and behavioral details in a single paragraph. Every sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers what the tool returns, the data source, caching, and the effect of the parameter. Annotations cover safety. No additional information is necessary.

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

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

The input schema already documents the only parameter (window) with an enum and description. The description adds valuable semantics: explaining that shorter windows surface 'what's hot right now' and longer windows show 'steady-state demand.' This goes beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: 'What other AI agents are calling on Pipeworx right now.' It specifies that it returns top tools, top packs, and total call volume over a recent window. The three enumerated use cases further clarify the purpose and help distinguish it from sibling tools like discover_tools or search.

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

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

The description provides three explicit and concrete use cases for when to use this tool: discovering hot data sources, confirming canonical choices, and aligning use cases. However, it lacks guidance on when not to use it or explicit alternatives, which prevents a perfect score.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, which the description does not contradict. The description adds detailed behavioral context: the fill check, Jaccard similarity threshold, placeholder filtering, and the fact that the tool returns signals but may advise against trading. It goes well beyond annotations.

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

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

The description is relatively long but well-structured with sections (FILL CHECK, SEMANTIC ANCHOR, etc.). Every sentence adds value, though some redundancy exists (e.g., explaining partition_check twice). Could be slightly more concise, but overall efficient for the complexity.

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

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

For a complex arbitrage tool with multiple modes and no output schema, the description is remarkably complete. It explains input options, internal logic (Jaccard, partition filter, fill check), response fields (opportunities[] with gap_pp, suggested_trade, etc.), and even when not to trade. Sibling tools exist but this description is self-contained.

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

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

Schema description coverage is 100% for both parameters. The description adds substantial meaning: it gives concrete examples of event slugs and topic seeds, explains what each mode does, and clarifies that no args triggers a default trending scan. This goes significantly beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and the name/title explicitly indicate the domain (Polymarket) and function (arbitrage). No confusion with sibling tools.

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

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

The description provides explicit guidance: no args for trending scan, event for specific market slug, topic for cross-event scanning. It explains when to use each mode, warns about the fill check condition (do not trade if realizable_edge_pp ≤ 0), and mentions alternative for custom sizing (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 extensively discloses behavioral traits beyond annotations: caching, model families, edge calculation, filtering logic, and diagnostics. It also explains why fed_candidates are excluded. 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 verbose but every sentence adds value, with clear structure: purpose, model families, filters, response fields. It is front-loaded with the core task but could benefit from tighter editing.

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 high schema coverage and no output schema, the description fully covers response structure, edge details, caching, and diagnostics. It anticipates user questions (e.g., why Fed bets are excluded) and is complete for an agent to use correctly.

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

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

Schema coverage is 100%, and the description adds meaningful context for parameters like slippage_pp (mentioning bid/ask costs) and min_partition_leg_kelly (explaining relationship to min_kelly). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes from sibling tools by detailing its unique approach and output structure.

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 (discover opportunities without paging) and details configurable knobs. However, it does not explicitly state when not to use it or compare to alternatives, though siblings like polymarket_arbitrage exist.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: it explains the response structure (tracked, expired, snapshot_dates), the meaning of trend and decay_pp_per_day, data freshness (snapshot written on cache-miss), and TTL constraints (60-day snapshot TTL).

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

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

The description is well-structured, front-loading the core purpose, then breaking down the response into labeled sections (RESPONSE, LIMITS). Every sentence serves a purpose, and the length is appropriate for the tool's complexity.

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

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

Given the absence of an output schema, the description thoroughly explains the return values (tracked, expired, snapshot_dates) including field meanings and limitations (e.g., decay from daily closes, not intraday). No critical information is missing.

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

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

The input schema has 100% coverage with clear descriptions for both parameters (days and window). The description repeats the defaults and adds minor context (clamp range for days), but does not provide significant additional meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical persistence.

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 context on when to use the tool (e.g., comparing fresh vs. old edges) and includes limits on data depth and snapshot gaps. However, it does not explicitly state when not to use it or name alternatives among siblings.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it 'walks the ladder,' returns specific fields like 'top_of_book, vwap_fill_price, slippage_pp,' and provides a 'verdict (clean|degraded|cannot_fill).' It also explains the risk of partial fills converting arbs into directional positions, beyond what annotations convey. No contradiction.

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

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

The description is lengthy but well-organized into sections for single-market and basket modes. It front-loads the core purpose and requirement (REQUIRES one of market or event). Every sentence adds value, explaining parameters, return values, and risks. No fluff.

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

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

With 4 parameters, no output schema, and no nested objects, the description covers all necessary context: it explains both modes, all parameters, return fields (enumerates them), and potential risks. Given the tool's complexity (two modes, risk warnings), this is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning: it explains the default logic for 'side' (auto from partition sum), interprets 'size_usd' differently for single-market vs basket modes, clarifies that 'market' and 'event' are mutually exclusive, and notes the clamp range 10–1,000,000. This goes well beyond the schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the verb 'check' accurately reflects the tool's purpose. This differentiates it from sibling tools like polymarket_arbitrage and 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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about consequences like 'theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position,' providing 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds substantial context: the two modes, compatibility_warning conditions, temporal alignment constraints, and skipped cross type/subtype counters. 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 comprehensive but somewhat lengthy. It is well-structured with sections for modes, response format, and safety fields, front-loading key information. Every sentence adds value, though some redundancy could be trimmed.

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

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

Given the complexity (3 parameters, no output schema), the description is highly complete. It explains all return fields (leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, skipped counters), enabling the agent to understand and use the tool effectively.

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

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

Schema coverage is 100% with all three parameters described. The description enriches by listing exact topic values, explaining override behavior, and providing example values. While the schema already covers basics, the description adds clear usage context.

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

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

The description clearly states the tool computes the spread between Kalshi and Polymarket for the same resolving question, with two modes (topic shortcuts and explicit tickers). It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit when-to-use guidance for both modes, warns that most pre-mapped topics are not tradeable, and explains how to interpret compatibility_warning and temporal_alignment fields to avoid misleading spreads.

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. The description adds useful context about scoping (anonymous IP, BYO key hash, or account ID), which is beyond annotations. No contradiction.

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

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

The description is concise, with three well-structured sentences that front-load the purpose. Every sentence adds value: purpose, usage examples, scoping, and pairing with siblings. No unnecessary words.

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

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

For a simple tool with one optional parameter and no output schema, the description explains what it does, when to use it, how scoping works, and how it relates to sibling tools. It is fully adequate for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description reiterates the behavior (omit to list all keys) but does not add significant new semantics beyond the schema. 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 the tool retrieves a value previously saved via remember or lists all saved keys when omitting the key argument. It specifies the resource (saved memory) and verb (retrieve/list), and distinguishes from siblings like remember and forget.

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

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

The description provides explicit guidance on when to use this tool: to look up context stored earlier without re-deriving it. It also mentions pairing with remember and forget, implying alternatives, and notes scoping to the agent's identifier.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the mark_read behavior and feed persistence, which are not covered by annotations. No contradictions.

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

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

The description is concise, well-structured, and front-loaded with the main purpose. Every sentence adds value without redundancy.

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

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

For a read-only list tool with no output schema, the description adequately explains return fields, parameter usage, and behavior. All parameter types and effects are covered.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds minor context (e.g., mark_read flags returned events as read) but does not significantly expand beyond the schema.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed' and specifies the contents (source, citation_uri, raw event payload). It distinguishes from sibling tools by focusing on recent alerts from the user's feed.

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

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

The description provides clear usage context: it works for polling and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or list alternatives among siblings.

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

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

The description details the multi-source fan-out behavior, fallback mechanisms (GDELT→GNews), and edge cases (USPTO soft-fail). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description complements these without contradiction.

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

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

The description is informative and structured, starting with purpose and examples. While it is somewhat long, every sentence adds necessary detail. It is well-organized with clear sections.

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

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

Given the tool's complexity (3 params, multi-source fetch, no output schema), the description sufficiently explains return format (changes grouped by source, total_changes, citation URIs) and limitations. It could mention rate limits or pagination, but overall 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% with parameter descriptions. The description adds value beyond the schema by providing examples for 'since' shorthand (e.g., '30d', '1y') and clarifying that 'value' accepts ticker or CIK. It also notes 'type' is limited to 'company'.

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 provides a change feed for a company within a time window, using specific verbs like 'what's new' and 'latest on'. It distinguishes itself from the sibling 'entity_profile' tool by stating when to use each.

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 tells when to use this tool (recent changes) and when not to (use 'entity_profile' for static profile regardless of window). It also provides example queries that clarify usage scenarios.

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

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

The description adds behavioral details beyond annotations: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours,' 'scoped by your identifier,' and linking to recall/forget. Annotations already indicate idempotentHint=true and destructiveHint=false, which the description reinforces without contradiction.

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

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

The description is three sentences, front-loading the core purpose and immediately followed by usage guidance and storage details. Every sentence adds information without 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?

Given the tool's simplicity (2 required string params, no output schema), the description covers all essential aspects: purpose, usage context, storage behavior, persistence, and companion tools. No gaps remain for effective use.

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

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

The schema covers both parameters with descriptions (100% coverage). The description adds value by providing example key formats ('subject_property, target_ticker') and value types ('findings, addresses, preferences, notes'), which aids in understanding proper usage beyond the schema's brief descriptions.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific verb 'Save' and resource 'data' (key-value memory). It distinguishes from siblings like 'subscribe' by specifying key-value pair scoped by identifier and cross-session reuse, differentiating it from other tools.

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

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

The description explicitly says when to use ('when you discover something worth carrying forward') and provides alternatives: 'Pair with recall to retrieve later, forget to delete.' It also clarifies the benefit ('so you don't have to look it up again'), giving clear context for choosing this tool over others.

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, openWorldHint, and destructiveHint=false. The description adds significant context: internal cascading across multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, labelling of each identifier with source, and explicit reporting of unresolved identifiers. 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 well-structured and every sentence adds value. It opens with example queries, then states purpose, then details supported types and behavior. Slightly verbose but not wasteful; the density is justified given the tool's complexity.

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

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

The description is comprehensive for the tool's complexity: covers input formats, output identifiers, sources, unresolved handling, fallbacks, and internal cascading. No output schema exists, but the description explains what to expect. Context is complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds rich semantics beyond schema: explains accepted formats for 'value' (ticker, CIK, ISIN, company name for company; brand/generic for drug), and clarifies how ISIN resolves to legal entity via GLEIF mapping. This adds meaning beyond the bare 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 resolves user-spoken names to canonical/official identifiers, with specific verb 'resolve' and resource 'name to ID'. It distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID' and lists supported types (company, drug) with detailed outputs.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' This implies preference over alternatives and sets context. However, it does not explicitly name alternatives or state when not to use, but the examples and the 'use first' directive give strong practical guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the probing process, ranking, and output fields (ranked list with score, confidence, signal density). No contradictions.

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

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

Three sentences, each earning its place: main action, use case, output summary. No wasted words, front-loaded with purpose.

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

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

With no output schema, the description still explains the return type (ranked list with score, confidence, signal density). All key aspects covered: purpose, parameters, usage, outputs.

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 meaning: entities[0] is treated as 'subject' for narrative, models default to workers-ai, _apiKey is conditional. This enriches understanding beyond the schema.

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

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

The description clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use it or mention alternatives beyond 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?

The description adds significant behavioral context beyond annotations: explains partial failures, the 5-30s first measurement for bundlephobia, and the sources_failed list. It also confirms the idempotent, read-only nature, consistent with annotations.

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

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

The description is dense but well-structured: purpose first, then details, usage guidance, limitations, and edge cases. Every sentence adds value. No redundant information.

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

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

Even without an output schema, the description lists all return fields (summary block, advisories, links, alternatives). It covers inputs, behavior, partial failures, and timestamp expectations, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example of scoped packages (`@types/node`) and clarifying that omitting version defaults to latest. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by being specific to npm dependencies in v1.

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 this tool: when an agent asks about safety, popularity, size, or cost of adding a package. It also notes the NPM-only scope and mentions fallback tools for other ecosystems.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds context about searching across all providers and return format, but no additional behavioral traits 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?

Description is a single concise sentence that conveys the core purpose. Could be slightly more structured but is efficient.

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

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

With low complexity, full schema coverage, and output schema present, the description sufficiently covers what the tool does and returns.

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 clear parameter descriptions. The tool description adds no new meaning beyond the schema.

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

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

Description clearly states it performs full-text search across all providers and returns series with codes and labels. However, it does not differentiate from sibling tools like 'search_within' or 'find_series'.

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

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

No explicit guidance on when to use this tool versus alternatives. Sibling tools exist but no mention of their distinctions.

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

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

Annotations already indicate safe (readOnly, idempotent, openWorld, not destructive). Description adds valuable behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' No contradiction.

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

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

A single, well-structured paragraph that front-loads the purpose and concisely covers usage, behavior, and limitations. Every sentence adds value.

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

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

No output schema, but description explains return format (passages with offsets and scores). Covers limitations (200K char cap, truncation flag). Complete for a tool with such clear annotations and schema.

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

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

Schema coverage is 100%. Description adds examples ('e.g. a SEC 10-K body, an article, a long tool result'), example queries ('supply-chain risk', 'fiscal year 2024 revenue'), and default for limit (5).

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 'Semantic search INSIDE a fetched record' and specifies inputs (text + natural-language query) and outputs (top-N passages with character offsets and similarity scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'Pair with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations indicate readOnlyHint=false and idempotentHint=true, which are consistent with creation. The description adds OAuth requirement, delivery caps (10/day for SMS), and webhook signing details beyond annotations.

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

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

The description is thorough but slightly verbose. It front-loads the main purpose and then organizes types and delivery details logically.

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 all parameters, delivery options, prerequisites, and even webhook signing. No output schema, but return value (subscription id) is mentioned.

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 description adds rich details for each parameter (e.g., type-specific params, delivery channel constraints) that greatly aids understanding.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It differentiates from sibling tools like unsubscribe and list_subscriptions by specifying creation behavior.

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

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

It explicitly requires a Pipeworx OAuth account and lists supported types with examples, providing context for use. However, it lacks explicit guidance on when not to use or comparisons with alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant context by explaining it draws examples from a live catalog of thousands of tools and returns exact tool+argument shapes. No contradictions with annotations.

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

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

The description is front-loaded with core purpose, then efficiently elaborates on output, parameter usage, and when to invoke. Every sentence serves a purpose without redundancy, balancing completeness with conciseness.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and its role as an onboarding tool, the description provides all necessary information: what it returns, how to use it, and its context relative to other tools. The output format is implied clearly enough for an agent to understand the result structure.

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

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

The input schema covers the single optional parameter with 100% description coverage. The description adds value by listing example topic values (finance, pharma, etc.) and explaining the behavior difference between omitting and providing the topic argument, which goes beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point for agents new to Pipeworx, listing multiple user intents and explicitly describing its output (category-bucketed example questions with tool+argument shapes). It effectively distinguishes from siblings like ask_pipeworx or discover_tools by positioning itself as a first-use guide.

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 tool explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without the topic argument. Although it doesn't list specific alternatives or when-not-to-use, the guidance is clear and practical for the intended use case.

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

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

Adds behavioral context beyond annotations: cancellation is a mutation (consistent with readOnlyHint=false), deactivation not deletion (consistent with destructiveHint=false), and preserves historical events via recent_alerts. Provides ownership enforcement detail.

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

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

Four concise sentences, each adds unique value: action, ownership constraint, deactivation vs deletion, historical preservation. No fluff 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?

Covers input (id), behavior (cancellation, ownership, deactivation), and consequence (history available via recent_alerts). Lacks handling of edge cases (e.g., invalid id), but sufficient for a simple tool with clear annotations.

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

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

Only one parameter 'id' with schema description already covering it ('Subscription id (uuid) returned by subscribe'). Description does not add new parameter details beyond the schema, so 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?

Clearly states 'Cancel a subscription by id', using a specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Specifies ownership enforcement ('only cancel your own subscriptions') and notes the row is deactivated not deleted, providing clear context on when to use and what happens. Does not explicitly mention alternatives but sufficient guidance.

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

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

Beyond the read-only/idempotent annotations, the description reveals critical behavior: the SEC EDGAR fast path vs. grounded pipeline, the full set of verdicts, and the crucial distinction that could_not_verify means the check did not happen and must not be treated as evidence. It also explains unsupported as 'we looked and cover no source' — nuanced context a caller needs.

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

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

The description is dense but every sentence contributes: query patterns, use case, dual routing, return contract, error semantics, and efficiency note. It front-loads the purpose and ends with a comparative benefit. 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?

With no output schema, the description fully specifies the return payload (verdict, actual value, citation, reasoning) and explains the two failure modes (could_not_verify, unsupported). It also covers the tolerance override and routing rules, making the tool 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 the baseline is 3. The description adds value by giving a concrete example for claim ('Apple's FY2024 revenue was $400 billion') and explaining tolerance_pct's default behavior ('implied by wording, capped at 5') and its use for hallucination detection. This is practical guidance 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 concrete natural-language query patterns ('Is it true that…', 'fact check') and states it performs 'natural-language claim verification against authoritative sources', returning a verdict. This clearly identifies the verb (verify) and resource (claims), and distinguishes it from sibling tools that search or retrieve information without issuing a judgment.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives guidance for two claim types (company-financial vs. other) and notes it 'Replaces 4–6 sequential calls', indicating when it is the efficient choice. The description does not name alternatives but the when-to-use instruction is unambiguous.

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