Spdx License

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these: external cost implications (BYO key pays Anthropic directly), return payload structure (score, confidence, signals, raw_response), and the default model behavior. 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 three tightly packed sentences: core functionality, model selection/cost, and return format plus use cases. Every sentence earns its place, with no repetition of schema details.

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

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

Given no output schema, the description adequately explains the return format (per-model object + combined view) and covers key usage scenarios and parameter interactions. It is complete for a read-only probe tool with rich annotations and a simple parameter set.

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 enriches parameter meaning by explaining the relationship between models and _apiKey (only needed when anthropic is in models) and highlights the default model, which the schema alone does not convey.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLM knowledge of a business/brand/product/topic) plus the scoring output (0-100 visibility per model). This specificity distinguishes it from siblings like deep_research or search, which are not LLM-knowledge-score tools.

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

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

The description provides clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and model-selection guidance (default workers-ai, optional anthropic with _apiKey). It does not explicitly name alternative tools or negative use cases, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: it discloses the routing behavior across thousands of tools, returns stable citation URIs, notes 'one fast call', and explains the tool works on every tier. This enriches the agent's understanding of what the tool does internally, going beyond the safety hints.

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

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

The description is relatively long but every sentence earns its place: it starts with the most critical directive ('PREFER OVER WEB SEARCH'), provides concrete examples, and contrasts with siblings. A minor redundancy exists in listing many data domains, but it aids quick comprehension of scope. Overall it is well-structured and not wasteful for a complex default 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 is remarkably complete: it explains what the tool does, what it returns (structured answer with citations), when to use it, when to use alternatives, and even notes account tier availability. It leaves little room for the agent to misinvoke the tool, and the absence of an output schema is compensated by describing the return format.

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 all parameters, all six being aliases for 'question', each documented in the schema. The description reinforces the natural language nature but does not add new parameter-specific syntax or formatting details. The baseline of 3 applies because the schema already fully documents the parameters; the description's contribution is contextual rather than semantic.

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

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

The description is highly specific: it states the tool routes questions to 5,366 tools across 1,396 verified sources and returns structured answers with citation URIs. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by defining its role as the default entry point.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). It also gives concrete examples of trigger phrases and sample queries, leaving no ambiguity about when to use this tool.

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

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

Annotations already declare safe read-only, idempotent behavior. The description adds valuable context beyond annotations: it's a beta with candidate routing improvements enabled live when under test, currently no candidate is active so it matches ask_pipeworx exactly, and it's a full working router, not a fallback. This enriches the behavioral profile without contradicting annotations.

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

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

The description is a single paragraph but information-dense, front-loading the beta nature and equivalence to ask_pipeworx. Each sentence contributes: current candidate status, usage guidance, and explicit 'not a fallback' clarification. Slightly verbose but efficient for the context.

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

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

Given the tool's complexity and the rich annotation set, the description is complete: it explains the experimental state, current equality with stable, how results are used, and confirms the same response shape. No output schema exists, but the description compensates by referencing ask_pipeworx's response shape and stating it's a full working router.

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 six parameters being aliases for 'question' and clearly described. The description adds no additional parameter meaning beyond saying 'same arguments' as ask_pipeworx, which is already evident from the schema. Baseline 3 applies since schema handles the 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?

Description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,366 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by being the experimental edge with candidate routing improvements. The verb+resource scope is explicit.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. While it implies experimental risk and says it's a full working router, it does not explicitly state when NOT to use it (e.g., for production stability), leaving a minor gap.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the extra LLM call cost, the strict extraction from tool results only, and the full refusal reason enum. This adds significant behavioral context not present in annotations.

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

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

The description is dense but well-structured, covering purpose, process, return format, usage guidance, and cost tradeoff in a logical order. Every sentence adds value, though it is longer than strictly necessary.

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

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

Despite lacking an output schema, the description fully specifies the success and refusal return shapes, including the refusal_reason enum. It covers all critical aspects: what it does, when to use it, its cost, and its output contracts, making it complete 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% for the single 'question' parameter and its aliases, so the description need not explain parameter formats. It adds context about what happens to the question (routing and argument filling) but no extra semantic detail beyond the schema.

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

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

The description clearly states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the routing and extraction process, and distinguishes itself from sibling ask_pipeworx by emphasizing evidence-based answers and explicit refusals.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' It names the alternative and gives concrete high-stakes examples, making the when-to-use decision clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description goes far beyond that. It discloses the resolver confidence contract, low-confidence short-circuit behavior, closed-market handling, wide-spread tradeability flags, cancellation-rule risk, and news fallback fields. This is rich behavioral context that the agent needs to safely interpret results, and it fully complements the annotations without contradicting them.

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

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

The description is well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is front-loaded with the core purpose. It is very long and includes many specific examples, which is useful for a complex tool but prevents it from being truly concise. Every section adds value, but the overall length makes it somewhat verbose for an agent to process quickly.

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

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

There is no output schema, so the description must fully document what the tool returns and how it behaves. It covers all relevant aspects: response shapes, evidence keying, resolver confidence, parent-event extraction, news field fallbacks, safety short-circuits for low-confidence or closed markets, and cancellation-rule risk. For a tool of this complexity, the description is exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description echoes the schema's parameter descriptions (e.g., valid market formats, depth enum, include_raw default) and adds examples, but it does not meaningfully deepen the understanding of parameters beyond what the schema already provides. The fan-out and classifier details are behavioral rather than parameter semantics, so this dimension stays at the baseline.

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

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

The description clearly states the tool's core function: research a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools like polymarket_edges or arbitrage by focusing on comprehensive bet research. The purpose is specific, unambiguous, and action-oriented.

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

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

The description explicitly lists example use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly tells the agent when to invoke this tool. However, it does not explicitly state when not to use it or name alternative tools for other scenarios, so it lacks the 'when-not/alternatives' component needed for a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, sorting by primary metric, and return format (paired data + citation URIs). This is rich behavioral context that annotations do not 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 dense with information and front-loads trigger phrases and the key preference instruction. While not ultra-brief, every sentence contributes meaningful details about usage, data sources, or output behavior, justifying its 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 (two entity types, distinct data sources, no output schema), the description covers purpose, input semantics, behavior, sorting, and return format. It is self-contained and leaves no significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds valuable semantics: explains the type enum variants, gives concrete examples for values (tickers/CIKs vs drug names), and clarifies the data pulled for each type. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs and resources, and explicitly distinguishes itself from sequential single-pack lookups, making it unambiguous.

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

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

The description provides explicit triggers ('Compare X and Y', 'X vs Y', etc.) and instructs to ALWAYS PREFER this tool over sequential lookups when comparing entities. It does not name specific sibling tools, but the guidance is clear and actionable.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive; the description adds rich behavioral context: it returns gaps[] and never invents, includes contradictions[], semantically excerpts large records, tracks hop fields and citation URIs, and states expected latency. This goes well beyond the annotations and helps agents understand side effects and limitations.

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

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

The description is long (over 300 words) but appropriately sized for the tool's complexity. It is front-loaded with critical account requirements and the essential 'what it does', then covers usage guidance, alternatives, depth semantics, return packet details, and timing. Every sentence adds practical information; 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?

Despite no output schema, the description thoroughly explains the return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), the iterative behavior across depths, and timing expectations. It addresses both the tool's capabilities and its limitations (structured catalog only, not news-oriented). This is complete for the complexity involved.

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 significantly enhances parameter meaning. For 'depth', it explains the behavioral difference among quick/standard/thorough (facets, gap recovery, contradictions, timing). For 'question', it notes that 'Broad/multi-part is fine — decomposition is the point' and gives examples. This adds substantial value beyond the schema's enum 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 performs 'grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources' in one call, explicitly contrasting with open-web search. It uses a specific verb ('research') and resource, and differentiates from siblings like ask_pipeworx and search by clarifying scope and use case.

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: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account prerequisites and paid-tier requirements, making the when-to-use/not-use conditions very clear.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior. The description adds valuable detail on return shape (top-N tools with full schemas and curated examples) and the direct-call workflow (no second lookup). It does not disclose any limitations like query matching behavior, but the provided info exceeds the baseline.

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

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

The description is somewhat long but front-loads the core purpose, then lists supported domains, return behavior, and usage priority. Each sentence carries distinct value, though the domain list could be trimmed without loss of meaning.

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

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

Despite lacking an output schema, the description explains exactly what will be returned (tool names, descriptions, input schemas, curated examples) and the immediate usability of results. For a discovery tool with broad application, this is 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 coverage is 100%, so the baseline is 3. The description's mention of 'describing the data or task' adds little beyond the schema's natural language description. The aliases and defaults are already fully documented in the schema.

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

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

The description uses a specific verb ('Find') and resource ('tools'), immediately conveying this is a discovery/search tool. The inclusion of a broad domain list (SEC filings, FDA drugs, etc.) and the phrase 'Call this FIRST' clearly distinguishes it from the specific data tools in its sibling list.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This directly informs decision-making versus invoking a specific sibling 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses significant behavioral detail: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), returns a structured set of fields, includes a soft-fail for the patents API sunset, and details the return fields (e.g., 'LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'). This adds real context about failure modes and output composition.

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 ideal but every sentence carries value: user intents, the core promise, the fan-out list, the exact return fields, and the input constraint. It is front-loaded and logically ordered. A slight deduction for wordiness, but the content is dense and purposeful.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It enumerates all data sections (cik/company_name, recent_filings, fundamentals, patents, news, LEI), specifies sources, notes the patents sunset soft-fail, describes the news fallback chain, and states the input limitation (no names). An agent can invoke this tool confidently and understand what it will return.

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 reinforces the parameter semantics ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') but does not add meaning beyond what the schema already provides, as the schema already documents 'type' as company-only and 'value' as ticker/CIK with a note about names. No extra semantic depth is added.

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

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

The description opens with concrete user phrasings, then clearly states its core function: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the resource (US public company), the action (profile), and the cross-source nature. This distinguishes it from siblings like compare_entities or deep_research, which focus on comparison or deep multi-step research.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an exclusion: names not supported, instructing to 'use resolve_entity first if you only have a name.' This clearly defines when to use the tool and when to use an 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 destructiveHint=true and readOnlyHint=false, so the description adds context with 'clear sensitive data' and memory lifecycle pairing. It does not contradict annotations and provides some extra 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?

Two concise sentences, front-loaded with the action and usage. Every sentence adds value with no wasted words.

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

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

For a simple single-parameter delete tool with clear annotations and schema, the description covers purpose, usage, and safety context. No output schema exists, but for this operation it is not critical.

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 the parameter 'key' described as 'Memory key to delete.' The description adds minimal extra meaning beyond the schema, but the baseline of 3 applies due to complete schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' by explicitly addressing the delete operation.

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

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

Provides explicit use cases ('when context is stale, the task is done, or you want to clear sensitive data') and mentions complementary tools ('Pair with remember and recall'), offering clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable process details: it fetches the page, extracts specific fields, and emits a standard markdown blob. This clarifies the non-destructive, idempotent nature of the operation beyond the structured hints.

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

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

Three sentences, each serving a distinct role: function, process/output, and use cases. No redundant wording, front-loaded with the primary action.

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?

Without an output schema, the description's statement that the output is a 'single text blob ready to drop at site-root/llms.txt' plus the mention of 'standard llms.txt markdown format' fully informs the agent about the return value. The annotation hints (openWorld, idempotent) are complemented by the process explanation, making the description complete for a well-scoped 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?

Both parameters are fully documented in the schema (100% coverage), so the description doesn't need to add parameter details. It does mention the extraction of 'title/description/key links' which aligns with what the URL parameter fetches, but this is implicit rather than explicit parameter semantics.

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

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

The description opens with a specific verb and resource ('Generate a production-ready llms.txt file for any URL'), immediately distinguishing it from the broader research/visibility sibling tools. It also explains the output format, so the agent knows exactly what the tool produces.

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 'Useful for' section provides three explicit scenarios (client indexing, personal drafting, competitor auditing), which gives clear context for when to invoke. It doesn't explicitly name alternatives or exclusions, so it stops short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds that it returns metadata+descriptors and is scoped to a single ID, but it does not disclose behavior for invalid IDs, case sensitivity, or normalization of the input. This is a moderate addition 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 a single, well-structured sentence that leads with the action ('Get metadata + descriptors'), states the scope, and provides illustrative examples. Every element earns its place; there is no fluff or unnecessary details.

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

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

For a simple lookup tool with one parameter, strong annotations, and an output schema, the description is sufficient. It covers what the tool does, the scope, and the parameter format. The only minor gap is the lack of explicit reference to sibling tools for alternative needs, but that is not essential for a straightforward operation.

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 schema description coverage at 0%, the description must compensate. It does so by explaining that 'id' is an SPDX license ID and providing examples ('MIT', 'Apache-2.0', 'GPL-3.0-or-later'), which give concrete meaning to the otherwise bare string type. It does not cover edge cases like case sensitivity, but the examples establish the expected format.

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: 'Get metadata + descriptors for one SPDX license id'. It specifies the resource (SPDX license), the scope (one ID), and the type of data (metadata + descriptors). This distinguishes it from siblings like list_licenses (all licenses) and get_license_text (the full text), with the examples reinforcing the intended input format.

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

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

The description implies when to use it: when you need metadata/descriptors for a single, specific SPDX license ID. The phrase 'one SPDX license id' signals that this is not for listing or browsing. However, it does not explicitly name alternatives or exclusions (e.g., 'for full text, use get_license_text'), so it lacks explicit 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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds that it 'returns standard text + cross-references', which is useful context about the output. It does not contradict annotations, but it also doesn't disclose additional behavioral traits like error handling or rate limits. Given annotations cover the safety profile, the description adds modest value.

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

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

The description is a single, information-dense sentence. It is front-loaded with the main action and resource, and every part earns its place: 'full license text', 'single SPDX license id', and 'standard text + cross-references'. No unnecessary words or repetition.

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

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

For a simple tool with one parameter and an output schema present, the description is sufficiently complete. It clearly indicates the tool's function and what it returns, and the annotations cover safety semantics. It doesn't discuss validation or error cases, but given the tool's simplicity and the presence of an output schema, this is not a critical gap.

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 0% description coverage, but the description clarifies the 'id' parameter as an 'SPDX license id'. This gives semantic meaning beyond the bare type string, and the schema example 'GPL-3.0-or-later' reinforces the format. For a single parameter, this is sufficient compensation for the lack of schema 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: 'Get the full license text for a single SPDX license id'. It uses a specific verb ('Get'), identifies the resource (full license text), and narrows to a single SPDX license id. It also distinguishes from sibling 'get_license' by emphasizing 'full license text' and 'standard text + cross-references'.

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

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

The description implies usage when you need the full text of a license by providing a single SPDX license id. However, it does not explicitly state when to use this over the closely named sibling 'get_license' or list_licenses, nor does it exclude any scenarios. The guidance is implied but not directly contrasted with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and mutation traits. The description adds the filter dimensions but discloses no extra behavioral details such as pagination, ordering, or default behavior when no filters are applied. The value added is moderate.

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

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

The description is a single, front-loaded sentence that states the action and object first, then lists the variable filters. No wasted words or redundant repetition of schema/annotation 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?

For a simple list tool with an output schema and strong annotations, the description covers the essential purpose and filter semantics. It might mention the default behavior when no filters are provided, but the absence of that is not a significant gap given the tool's simplicity and the existence of an output schema.

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

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

The schema description coverage is low (33% – only 'deprecated' has a description). The description compensates by naming the conceptual filters: OSI-approved, FSF Free/Libre, and deprecated, which adds meaning to osiApproved and fsfLibre. It still leaves the exact boolean semantics implicit, but it is a clear improvement over 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 lists SPDX licenses, a specific verb+resource combination, and names the optional filters. It distinguishes itself from siblings like get_license and get_license_text by focusing on listing rather than retrieving individual licenses.

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

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

The description implies when to use the tool (when a list of licenses is needed) and describes the filter options, but it does not explicitly compare with alternatives or exclude other tools like get_license. There is no when-not-to-use guidance, so it stops short of a 4 or 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context by specifying that it returns the caller's subscriptions and listing the exact fields, including subscribe-specific data like last_fired_at and fire_count. No contradiction with annotations.

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

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

The description is two sentences with no filler. The first sentence states the action and returns; the second provides usage guidance. The most critical information is front-loaded, and every word contributes value. It is appropriately 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?

For a simple list tool with one optional parameter and strong annotations, the description covers everything needed: what it lists, what it returns, and when to use it. The output schema is absent, but the description explicitly lists return fields, compensating fully. Sibling tools subscribe/unsubscribe provide context for cancellation, and the description's usage line ties in well.

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 fully documents the only parameter include_inactive with a clear description ('Include cancelled subscriptions in the response (default false)'). Since schema coverage is 100%, the description does not need to add parameter details. The description does not mention the parameter, but this is acceptable given the schema's thoroughness, so the baseline 3 applies.

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

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

The description begins with a specific verb and resource: 'List the caller's active subscriptions.' It clearly enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count), which distinguishes it from sibling tools like subscribe/unsubscribe. This is a precise, non-tautological statement of purpose.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool, though it does not mention alternatives or exclusions. Since it gives concrete guidance without naming sibling tools, it earns a 4 rather than a 5.

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

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

The description goes beyond annotations by disclosing rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and how feedback is processed ('The team reads digests daily and signal directly affects roadmap'). These add behavioral context not present in the annotations, though the description doesn't specify response behavior.

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

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

The description is well-structured and front-loaded: purpose in the first sentence, usage guidance in the second, and concise context about rate limits and cost. Every sentence provides useful information with 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?

For a simple feedback tool with 3 parameters and no output schema, the description covers purpose, usage, content guidance, and rate limit—a complete picture. The schema handles the rest, so the description is sufficient for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by advising message content: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which helps the agent phrase the message better than the schema alone. The type enum is already documented in the schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also distinguishes itself from sibling tools by focusing on feedback submission rather than queries or actions, and enumerates specific categories (bug, feature, data_gap, praise).

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

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

The description explicitly states when to use the tool: 'Use 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).' It provides clear context but doesn't explicitly mention alternatives or when-not scenarios, which keeps it slightly below a 5.

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

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

Adds substantial context beyond annotations: data source (CF analytics-engine), no PII, output structure (pack, tool, count), and caching behavior (5min-1h). Annotations already indicate read-only and non-destructive, but this description enriches the safety and behavior profile.

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

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

Front-loaded with a clear one-sentence purpose, then concise supporting details. Each sentence adds value: use cases, data derivation, privacy, caching. No wasted words 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?

The tool is simple (one optional parameter) and the description covers purpose, return values, use cases, privacy, and caching. No output schema exists, but the description clearly states what is returned, making it complete for the agent.

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

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

Schema coverage is 100%; the window parameter is fully described with enum values and meaning (shorter vs longer windows). The description mentions the window options but adds no new semantics beyond the schema, so a 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 what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resource, and it distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on aggregate AI agent call trends.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs), providing clear context for when to use. However, it does not explicitly mention when not to use or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds deep behavioral detail: thresholds (3pp partition deviation, 0.30 Jaccard, 20% placeholder fraction), the fill-check logic with realizable_edge_pp, and a warning that a positive theoretical edge with non-positive realizable edge should not be traded. 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 with uppercase headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Every sentence delivers useful information, and given there is no output schema, the detail is necessary. It is not overly verbose for the complexity it covers, though it could be slightly tightened.

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

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

The description covers all execution modes, edge cases (placeholder filters, low-similarity pairs), response fields, and fill-check behavior. Since there is no output schema, it compensates by detailing the return format. It also references the relevant sibling tool for sizing, making it self-contained for informed decision-making.

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

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

Although the input schema describes both parameters, the description enriches them with practical examples (event slug like 'fed-decision-may-2026', topic like 'Fed rate decision'), explains the mode-specific algorithms, and details the response structures. This adds substantial meaning beyond the schema's minimal descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then outlines distinct modes (trending_scan, event, topic) and even distinguishes its cross-event capability from single-event scanning. This clearly sets it apart from sibling tools like polymarket_edges and polymarket_fill_risk, which is mentioned as a separate sizing tool.

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

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

The description explicitly tells when to call with no args (trending_scan), when to pass `event`, and when to pass `topic`, including concrete examples. It also directs users to polymarket_fill_risk for custom sizing and provides do-not-trade guidance when the fill check shows non-realizable edge, covering both when-to-use and when-not-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?

Annotations already mark this read-only/idempotent, and the description adds extensive behavioral detail: seven model families, output segments, per-leg Kelly behavior, slippage assumptions, diagnostics for empty results, and a 1-hour KV cache keyed on knobs. This far exceeds annotation coverage and gives agents a precise model of runtime behavior.

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

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

The description is heavily overloaded: it spends many sentences detailing model families and historical gate relaxations that are not necessary for selecting and invoking the tool. While it is front-loaded with the core purpose and has clear section markers, it violates the spirit of conciseness and would benefit from trimming.

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?

Because there is no output schema, the description fully compensates by detailing the response shape (by_segment, fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, 24h move). It also documents caching and knob-driven behavior, which is more than enough for a safe read-only call.

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 each parameter already has rich descriptions. The tool description adds cross-parameter context that is not in the schema, such as how min_liquidity/max_spread_pp are 'tradeable-edge' filters, why min_kelly does not apply to partition overround (per-leg Kelly explanation), and how slippage_pp interacts with edge ranking.

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?

Opens with a specific verb+resource+comparison: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly differentiates it from siblings like polymarket_arbitrage by framing the source of edge as model disagreement, not just price gaps.

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 the intended use case ('Built for "what should I bet on today"'), and provides practical caveats (Fed bets excluded due to unreliable signal, 'rare-by-design' longshots, empty-segment diagnostics). It does not explicitly name alternative tools for when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral context: response structure, snapshot TTL limits, cache-miss snapshotting, the signed edge_pp_net convention, and the daily-close basis for decay. This exceeds annotation coverage and clarifies edge cases.

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

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

The description is long but efficiently organized into sections: purpose, args, response, limits. Each sentence carries distinct information, and the use of ALL-CAPS section headers front-loads the key details. The length is justified by the tool's complexity.

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

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

There is no output schema, but the description fully documents the return value (tracked[], expired[], snapshot_dates[]) including field semantics and edge cases. Limits and data-availability quirks (TTL, gaps) are disclosed, making the description self-sufficient for understanding the tool's behavior.

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

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

Schema coverage is 100%, with both parameters described in detail (defaults and clamps). The description repeats the parameter defaults and adds the 'snapshot family' interpretation of window, but this is also in the schema. No major new semantics are added beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb phrase 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and states the core question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools like polymarket_edges, which likely provides current edge data rather than historical persistence analysis.

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

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

The description explains when to use the tool via the contrast between 'a fresh wide edge and a 3-week-old wide edge' and notes 'the median lifespan is your competition clock.' It implicitly positions itself against polymarket_edges by stating it is built from those snapshots, though it doesn't explicitly name a preferred alternative. Clear context with no exclusions warrants a 4.

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, and idempotentHint, but the description adds rich behavioral detail: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, verdicts like clean|degraded|cannot_fill), and discloses the risk of partial basket fills ('the dominant loss mode'). This goes far beyond the annotations, with 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 long but extremely well-structured with clear SINGLE-MARKET and BASKET sections, lists of output fields, and a final usage directive. Every sentence adds operational value; there is zero fluff or repetition.

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

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

Given the tool's complexity (two modes, many outputs, no output schema), the description covers inputs, outputs, usage context, and risk warnings comprehensively. It even names specific risk indicators (thin_legs, forced_directional_risk) and ties into sibling tools for a complete operational picture.

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?

Despite 100% schema coverage, the description substantially deepens parameter meaning. It explains 'market' triggers single-market mode, 'event' triggers basket mode, clarifies side defaults and interpretations (e.g., basket sell_yes = capture overround, sell if partition sum > 1), and defines size_usd differently for single-market (spend vs proceeds) vs basket (settlement notional). This is far beyond the schema's basic descriptions.

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

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

The description clearly states the tool's core function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings by explicitly naming 'polymarket_arbitrage' and 'polymarket_edges' as related but different tools, and by describing its two modes (single-market and basket/partition).

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

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

It provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, and partial basket fills convert an arb into unhedged directional position), giving clear context for when to use this tool versus alternatives.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description extensively discloses behavior: it explains the two modes, response structure (leg prices, spread, top_spreads_pp), safety fields (compatibility_warning with specific conditions), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also warns that pre-mapped topics are often not tradeable, which is non-obvious behavior. 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 information-dense and well-structured using labels like 'TWO MODES:', 'RESPONSE:', 'SAFETY FIELDS:'. Every sentence adds value, and the length is justified by the tool's complexity. However, it is a dense paragraph that could be slightly overwhelming; a bit more whitespace would improve scannability, so it does not earn a 5.

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

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

With no output schema, the description compensates by thoroughly explaining the response: leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped_cross_type counters. It also covers parameter usage modes and caveats. This is complete for a tool of this complexity, given the rich annotations.

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

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

The schema already covers all three parameters with descriptions (100% coverage), so baseline is 3. The description adds a two-mode conceptual framework and clarifies how explicit parameters override topic-mapped sides, which provides meaning beyond the schema. It does not introduce new per-parameter details but reinforces the interaction semantics, justifying a slightly above-baseline score.

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

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

The description opens with a precise verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from siblings like polymarket_arbitrage by focusing on the same question across two venues. It also clearly explains two modes (topic shortcuts and explicit identifiers), leaving no ambiguity about the tool's function.

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

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

The description gives clear context for when to use the tool: for cross-venue spread analysis, with two explicit modes explained. It also provides when-not guidance through the compatibility_warning, noting that non-equivalent bet shapes or temporal misalignment make spreads meaningless. However, it does not explicitly name alternative tools (e.g., polymarket_arbitrage), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is known. The description adds useful context about scoping ('Scoped to your identifier') and the dual behavior of listing all keys when the key argument is omitted, which goes beyond the annotations.

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

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

The description is three sentences long and well-structured: the first sentence states the core behavior, the second gives usage context, and the third adds scoping and tool relationships. It is concise without being overly terse, though some examples could be trimmed without loss.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers behavior, scoping, and usage context adequately. It could mention what happens when a key is not found, but this is a minor gap given the tool's simplicity and strong annotation support.

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

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

The schema already provides 100% coverage for the single 'key' parameter with its description ('Memory key to retrieve (omit to list all keys)'). The tool description largely restates this and adds example key names, but does not significantly deepen parameter 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 uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (values saved via remember / saved keys). It also distinguishes from sibling tools by mentioning 'remember' (save) and 'forget' (delete), so the agent knows exactly what this tool does relative to others.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and gives concrete examples (target ticker, address, research notes). It also provides guidance on the relationship with remember and forget, which clarifies 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 significant context beyond the annotations: it details the event payload (source, citation_uri, raw event payload), explains the effect of mark_read ('flag returned events read so the next call only shows newer ones'), and mentions polling behavior. These are important behavioral traits not conveyed by the readOnlyHint or idempotentHint annotations alone.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence earns its place. It covers the return payload, filtering options, mark_read behavior, and a mirror endpoint without any fluff or repetition.

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

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

For a tool with five parameters, no output schema, and strong annotations, the description is complete. It tells the agent what will be returned, how filtering works, how mark_read affects state, and even provides an alternative access method. There are no critical gaps in understanding how to use it.

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

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

The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds valuable extra meaning: it gives a concrete example for type ('sec_8k') and clarifies the consequence of mark_read on subsequent calls ('so the next call only shows newer ones'). This goes beyond the schema's basic 'Flag the returned events read' explanation.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), and distinguishes itself from siblings like recent_changes and list_subscriptions by focusing on the alert feed. It also mentions what each event carries, making the purpose unmistakable.

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

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

The description provides clear usage context: it's for reading recent alerts, supports filtering by type and since, and notes that 'Polls work fine.' It also mentions an alternative for scripts/dashboards (the direct GET endpoint). However, it doesn't explicitly state when not to use this tool or name specific sibling alternatives, so it falls slightly short of a 5.

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

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

Annotations already mark it readOnly/openWorld/idempotent, but the description adds substantial behavioral detail: parallel fan-out, fallback to GNews under rate limits/5xx, PatentsView soft-fail due to API sunset, and the return shape with grouped changes and citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph, but every clause earns its place: trigger phrases, source behavior, fallback logic, parameter syntax, output structure, and sibling pointer. It is front-loaded with user intent and contains no filler.

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

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

Despite no output schema, the description specifies the return structure (changes[], total_changes, pipeworx:// citation URIs) and covers source failure modes, parameter formats, and when to use an alternative. This gives an agent a complete mental model for correct invocation.

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

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

Schema descriptions cover all three parameters, but the description enriches them with concrete shorthand examples ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for typical monitoring, and clarifies value as ticker or zero-padded CIK with examples. This goes well beyond the schema.

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

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

The description opens with concrete user phrasings ('What's new with X'/'latest on Y') then defines a precise action: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts with the sibling entity_profile, so purpose is unmistakable and differentiated.

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 states exactly when to use this tool (recent changes, updates, news in a time window) and gives an explicit alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also explains source selection behavior (GDELT preferred, GNews fallback), clarifying operational context.

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

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

Annotations already indicate idempotentHint=true, but the description adds valuable context: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain memory for 24 hours, and data is stored as key-value pairs. This goes beyond the structured hints, though it does not state overwrite behavior explicitly.

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

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

The description is four sentences, front-loaded with the primary purpose, and uses concrete examples to convey usage. Every sentence earns its place: save purpose, when to use, storage details, and sibling pairing. 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?

This is a simple two-parameter storage tool with annotations and no output schema. The description covers purpose, usage context, persistence behavior, and complementary tools. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with both key and value described in detail (e.g., 'Memory key (e.g., "subject_property")' and 'Value to store (any text — findings, addresses, preferences, notes)'). The description adds little beyond saying 'stored as a key-value pair,' which is already implied by the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes itself from sibling tools by explicitly pairing with 'recall to retrieve later, forget to delete,' making its role as a memory store unambiguous.

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

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

The description provides explicit when-to-use context: 'Use when you discover something worth carrying forward...' and gives concrete examples (ticker, address, preference). It also names alternatives (recall, forget) and explains the pairing, which effectively guides tool selection.

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

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

Annotations already show readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: it cascades through several lookup endpoints, auto-disambiguates company inputs, and returns citation URIs. This goes beyond the structured fields and helps the agent understand internal behavior and output richness.

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 information-dense and front-loaded with example queries, but it is somewhat long and contains some explanatory phrases (e.g., 'using resolve_entity replaces 2-3 manual lookups') that could be omittable. It is well-structured with a SUPPORTED TYPES section, but not maximally 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?

The tool has two entity types and no output schema, so the description fully explains return values for both types (ticker + CIK + company_name, RxCUI + ingredient + brand), input formats, and disambiguation. It covers purpose, usage, and behavior comprehensively, leaving no critical gaps.

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

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

Schema coverage is 100% with clear property descriptions. The description adds examples ('AAPL', '0000320193', 'ozempic'), explains accepted input formats, and notes auto-disambiguation for companies. This enhances the schema without redundancy.

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 identifiers required by other tools, with a specific verb ('resolve') and resource ('entity'). It distinguishes itself from siblings by explaining the output (ticker, CIK, RxCUI) and the use case ('Use FIRST whenever you have a name but need an ID').

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 'Use FIRST whenever you have a name but need an ID', giving a clear when-to-use condition. It does not name alternative tools or provide when-not-to-use scenarios, though it implies other tools require these identifiers. This is strong but lacks explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral details: it invokes ai_visibility_check per entity, ranks results, and returns score/confidence/signal density. It also notes the first entity is treated as the subject, providing context beyond the schema.

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

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

Two sentences, front-loaded with the primary action, and every sentence earns its place. No filler or repetition of schema details.

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

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

Despite no output schema, the description specifies the return format (ranked list with score, confidence, signal density per entity). It also covers the tool's purpose, usage scenario, and key behavioral trait (probing with ai_visibility_check). Annotations handle safety, and schema handles parameters, making this 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 the baseline is 3. The description adds value by clarifying the 'entities' parameter semantics: 'First entry treated as the 'subject' for narrative; rest are competitors.' This goes beyond the schema's generic array description and helps correct usage.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' with specific actions—probes each entity via ai_visibility_check, ranks by score, surfaces most/least recognized. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI-visibility context.

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: 'Useful for competitive AI-marketing audits' with an example question. It implies the tool is for multi-entity comparison and that ai_visibility_check is the underlying single-entity probe, though it does not explicitly name alternatives or state when not to use. The guidance is strong but could explicitly contrast with 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?

The description adds significant behavioral context beyond the annotations: it mentions partial failures degrade gracefully, that bundlephobia's first measurement can take 5-30s, and that sources_failed will list timeouts. It also discloses the composite fan-out nature, which is not captured by readOnly/idempotent hints.

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

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

Though longer than many descriptions, every sentence earns its place: the opening defines the composite purpose, the second gives usage triggers, the third details return content, the fourth scopes the ecosystem, and the fifth addresses latency and failure handling. The structure is front-loaded with the core purpose and then flows 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?

Given the tool's complexity (composite of two services) and lack of an output schema, the description is remarkably complete. It specifies what is returned (summary block fields, per-advisory detail, links, alternative versions), the supported ecosystem, and graceful degradation behavior, leaving little ambiguity 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?

The input schema has 100% parameter description coverage (package, version with defaults and scoped package note), so the baseline is 3. The tool description reinforces that 'package' is an npm package and that version defaults to latest, but does not add substantial new semantics beyond the schema.

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

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

The description opens with 'Composite "should I add this npm package to my project" check in ONE call', clearly identifying the tool's purpose as a single-call comprehensive scan of an npm package. It distinguishes from siblings like get_license by combining multiple sources (deps.dev, bundlephobia) and explicitly states it's a composite check.

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

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

The description gives explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which helps an agent decide when not to use this tool.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable behavioral context: substring matching, case-insensitivity, and the two fields searched, which go beyond the structured metadata. No contradictions detected.

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, front-loaded sentence conveys all key information with no wasted words. Every element earns its place.

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

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

For a simple tool with one parameter, rich annotations, and an output schema, the description adequately covers what the tool does and how it behaves. No additional information is needed for correct invocation.

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

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

With 0% schema description coverage, the description compensates by explaining the 'query' parameter is used for substring matching across SPDX IDs and license names. This adds meaning beyond the raw schema, though it could be more explicit about matching rules.

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

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

The description states a specific verb ('search') and resource ('SPDX id and full license name') with clear scope (substring, case-insensitive). It distinguishes the tool from siblings like 'get_license' and 'search_within' by defining the exact fields searched.

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?

Usage context is implied: use this tool to find licenses by partial ID or name. However, no explicit comparison to alternatives like 'search_within' or 'list_licenses' is provided, so the agent must infer when this tool is preferred.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses substantial behavioral details: embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, a 200K character cap, and truncation with a flag. It also reveals that returned passages include character offsets and similarity scores, enriching the agent's understanding of expected behavior.

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

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

The description is well-structured and front-loaded with the core purpose, then expands into usage context, pairing, and technical details. Every sentence adds value, and the length is justified by the tool's complexity. 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?

Given the tool's moderate complexity and the absence of an output schema, the description is remarkably complete. It explains inputs, outputs, use case, limits, and technical behavior. The agent has enough context to select and invoke the tool correctly without needing additional clarification.

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

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

Schema coverage is 100%, and the schema already provides good descriptions for text, query, and limit. The description adds nuance by clarifying that the text is something 'you already pulled' (e.g., a SEC 10-K body), reinforces the natural-language nature of the query, and mentions the output format with offsets/scores, which indirectly clarifies the purpose of the parameters. This goes beyond the baseline but does not dramatically change parameter 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 identifies the tool as semantic search inside an already-fetched record, specifying inputs (text + query) and outputs (top-N passages with offsets and scores). It distinguishes itself from the sibling 'search' tool and 'ask_pipeworx_grounded' by emphasizing the pre-fetched text requirement and passage-level retrieval.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt...' and provides a concrete pairing with ask_pipeworx_grounded, explaining the workflow of fetching first and then grounding over relevant passages. This gives clear context and an alternative to consider.

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-write, open-world, idempotent, and non-destructive. The description adds behavioral details: authentication requirement (anonymous/BYO can't persist), delivery channel constraints (SMS verification, 10/day cap), and the always-on feed. Does not contradict annotations, but does not describe webhook behavior in the main text (only in schema).

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?

One dense paragraph front-loaded with purpose and return value. While efficient, it packs many details (types, auth, delivery) into a run-on structure and omits webhook, which would have been another channel. Reasonably concise despite this.

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 purpose, return, auth, types, delivery channels (except webhook), and feed access. However, with no output schema, it only states the subscription id is returned and does not describe full response structure (e.g., webhook secret, subscription metadata). The omission of webhook from the main delivery enumeration is a notable gap. Overall, solid but incomplete for a complex tool.

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

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

Input schema covers 100% of parameters with descriptions. The description enriches semantics with concrete examples (sec_8k with items:["5.02"], polymarket_edge topic:"fed", fred_series series_id:"UNRATE") and SMS/email constraints, but omits webhook details that the schema 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?

Description states 'Create a proactive monitoring subscription to a live-data event stream' clearly identifying the action and resource, and distinguishes from sibling tools like list_subscriptions and unsubscribe. Also notes the return value (subscription id).

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 clear context: requires OAuth account, lists supported subscription types with examples, and explains delivery channels (feed, email, SMS) with constraints. Does not explicitly name alternatives like list_subscriptions, but the usage context is strong. Missing explicit 'when not to use' or alternative tool references.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds behavioral context: it draws from the 'live catalog of thousands of tools,' returns category-bucketed examples with tool+argument shape, and explains how the optional topic narrows results. This enriches beyond annotations, though it does not detail return formatting or rate limits.

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 front-loaded with natural-language trigger questions and structured into what/why/how sections. The category list and meta-tool examples are valuable for an onboarding tool; some redundancy with the schema's enum list could be trimmed, but overall it earns its 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?

With no output schema, the description fully explains return values: category buckets, tool+argument shape, and live catalog. It also covers both call modes (no args vs topic) and positions itself among siblings as the initial discovery step. This is complete for a tool of this complexity.

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

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

Schema coverage is 100% for the single optional `topic` parameter, including valid values and the omit-for-full-spread behavior. The tool description repeats the same guidance (e.g., 'finance', 'pharma', 'betting') without adding new meaning, so it meets but does not exceed the baseline.

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

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

The description clearly states this is the onboarding entry point for an agent to discover what questions Pipeworx can answer, and specifies the exact output: category-bucketed example questions with tool+argument shape. This distinguishes it from siblings by positioning it as the 'Use this FIRST' discovery tool rather than a specific query/meta-tool.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit vs pass `topic`. However, it does not explicitly name alternatives to avoid, such as discover_tools, so it misses the full '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?

The description adds key behavioral details beyond annotations: ownership enforcement and soft-delete semantics (deactivated not deleted) that preserve historical events. This aligns with destructiveHint=false and adds context about permissions and side effects.

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 total, with the main action front-loaded in the first sentence and essential behavioral context in the second. 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?

For a simple single-parameter tool with complete schema and annotations, the description covers the action, permission scope, and data lifecycle, making it contextually complete for an agent to select and invoke correctly.

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

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

The input schema already fully documents the id parameter at 100% coverage, and the description repeats the same information without adding new semantics, so it remains at baseline.

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

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

The description uses the specific verb 'Cancel' with the resource 'subscription' and identifier 'id', clearly distinguishing it from sibling tools like subscribe and list_subscriptions. The action 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?

The description explains that ownership is enforced, indicating when you can use it (your own subscriptions only), and clarifies the deactivation behavior relative to recent_alerts. However, it does not explicitly name alternative tools like subscribe or list_subscriptions for broader context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description adds value by explaining the internal routing (SEC EDGAR vs. grounded pipeline), the percent-delta math, and the specific verdict types returned. It also mentions the pipeworx:// citation and reasoning output, which goes beyond the annotations.

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

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

The description is informative and well-structured, starting with trigger phrases and then explaining the routing pipeline and return values. It is somewhat long, but each sentence adds relevant detail, and the front-loaded trigger phrases make it scannable.

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

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

Given there is no output schema, the description adequately covers the return value (verdict, actual value, citation, reasoning). It also explains the tool's scope, limitations (unsupported claims), and the efficiency benefit. However, it could be slightly more explicit about edge cases like the exact behavior when no source is found, but the 'unsupported' verdict covers this.

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

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

The input schema already covers both parameters with detailed descriptions (claim examples, tolerance_pct semantics). The description adds a small amount of extra context by mentioning 'tolerance implied by wording' and 'exact percent-delta math,' but the schema carries most of the burden, 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's purpose: natural-language claim verification against authoritative sources, with explicit trigger phrases and examples. It distinguishes itself from sibling tools like ask_pipeworx and search by focusing on fact-checking and verdict generation.

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: whenever the agent needs to check if a user's statement is factually correct. It also differentiates between financial claims (using SEC EDGAR fast path) and other claims (grounded pipeline), giving clear routing logic and noting it replaces 4-6 sequential calls.

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