Statec Lu

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

Annotations already cover read-only, idempotent, and non-destructive traits. The description adds meaningful behavioral context: the default free model, the BYO API key for Anthropic with direct cost to the user, and the returned per-model structure. It stops short of disclosing potential stochasticity of LLM scores or any rate limits, but given annotations, the added detail is sufficient.

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

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

Three sentences, front-loaded with the core purpose, then key configuration details, then use cases. Every sentence adds essential information with no redundancy or filler. Ideal length for a tool with this complexity.

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

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

Given there is no output schema, the description covers return values well (per-model {score, confidence, signals, raw_response} + combined view). It addresses the main operational nuance (free vs paid Anthropic calls). Minor gaps include no mention of error handling or whether the tool makes live calls each time, but for a read-only probing tool the description is adequately 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?

With 100% schema coverage, the baseline is 3. The description adds value by explaining that passing `_apiKey` enables probing Anthropic and that the user pays directly, plus naming the default model (Workers AI Llama-3.3-70b). This goes beyond the schema's terse parameter descriptions to clarify cost and model selection behavior.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research by focusing on visibility scoring across LLMs. It also states the default model and output shape, removing ambiguity.

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies the free vs BYO-key workflow. It does not explicitly name alternatives or exclusion cases, but the use cases are clear enough to guide when to invoke this tool over siblings like scan_competitor_ai_presence.

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, assuring safe read behavior. The description adds useful context beyond annotations: it routes to 5,439 tools, fills arguments, returns stable citation URIs, and works on every tier. While it doesn't mention rate limits or potential delays, the 'one fast call' statement and existing annotations provide adequate transparency.

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

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

The description is more verbose than typical but densely packed with actionable guidance. It front-loads the key directive ('PREFER OVER WEB SEARCH'), then provides categorized domains, trigger phrases, examples, and escalation paths. Each section serves a distinct purpose, though some redundancy exists in the examples and domain lists.

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, rich annotations, and lack of output schema, the description is remarkably complete. It explains what the tool does, when to use it, how it differs from alternatives, what output to expect (structured with stable citation URIs), and provides concrete examples. No critical gaps remain for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% and all 6 parameters are documented as aliases for 'question'. The description reinforces the natural-language expectation with examples but does not add substantive semantic detail beyond the schema. The schema already clearly defines the question field and accepts multiple aliases, so the description adds marginal value.

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: answering factual questions by routing to 5,439 tools across verified sources and returning structured answers with citations. It uses specific verbs like 'routes' and 'returns', and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases. It also gives clear alternatives ('Step up only when needed') for when to use ask_pipeworx_grounded and deep_research, making the decision hierarchy unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context about live experimental routing, the current inactive candidate state, and the 'full working router' fallback, enhancing behavioral transparency without contradicting 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 four dense sentences, front-loaded with the core beta relationship and usage caveats. Every sentence contributes necessary context, though it is slightly longer than strictly required.

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 full parameter schema, rich annotations, and the explicit statement that the response shape and arguments match ask_pipeworx, the description is complete enough for an agent to select and invoke the tool correctly. The experimental context and current equivalence are also clearly conveyed.

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

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

Schema description coverage is 100%: the schema clearly documents the 'question' parameter and all five aliases. The description only says 'same arguments,' which adds no new semantic detail, so the baseline score of 3 is appropriate because the schema carries the full parameter burden.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, explains it is a universal router over the same 5,439 tools, and distinguishes it from the stable sibling by highlighting candidate routing improvements. It is specific and immediately differentiates this tool from ask_pipeworx and other siblings.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also notes that currently no candidate is active, so behavior matches ask_pipeworx exactly, giving clear when-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds significant behavioral context: it discloses the extra LLM call cost, the refusal_reason enum values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the constraint that only tool result content is used. 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 longer than a minimal one but tightly packed with useful information: return structure, refusal reasons, usage guidance, and cost tradeoff. It is front-loaded with the core purpose and remains structured without waste.

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

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

Even without an output schema, the description fully explains the return shape including all success fields and refusal_reason values. It covers use cases, alternatives, cost, and behavioral guarantees, making it complete for a high-stakes question-answering tool.

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

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

Schema description coverage is 100%, and the schema already documents the 'question' parameter and its aliases (q, text, input, query, prompt). The description does not add parameter-level detail, but the baseline of 3 applies because the schema carries the full burden.

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 purpose: a hallucination-resistant answer mode that extracts answers only from tool results and returns evidence or explicit refusal. It distinguishes itself from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but with added grounding and a recommendation to prefer ask_pipeworx for casual lookups.

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

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

Explicitly provides when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use ('prefer ask_pipeworx for casual lookups') due to the extra LLM call. It names the alternative ask_pipeworx directly.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing operational behaviors: resolver match confidence levels, blocking short-circuit paths for low-confidence/closed markets, fallback handling for GDELT 429s with _fallback_attempted fields, wide-spread flags, and cancellation-rule parsing with ev_impact. These are critical for an agent to use the tool safely and interpret results correctly.

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

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

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose. It is dense with valuable information; however, it could be trimmed slightly by reducing the number of fan-out examples and some repeated cautions about low-confidence matches.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly. It describes result.market, result.analysis, result.evidence, resolver contracts, parent_event fields, news fallback behavior, and safety statuses. It also covers edge cases like closed markets, wide spreads, and cancellation rules, making it complete enough for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds examples of fan-out for different bet types, but it does not add significant meaning about the parameters themselves beyond what the schema already documents. The market parameter's accepted forms are already fully described 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bets) and the action (research by pulling data). However, it does not explicitly name sibling alternatives for comparison, so it falls short of the strictest 'distinguishes from siblings' bar.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also offers detailed fan-out examples and warns agents to check cancellation rules before sizing sports bets. However, it does not state when not to use the tool or mention alternatives like polymarket_edges or validate_claim.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context beyond annotations: it pulls from SEC EDGAR/XBRL for companies, FAERS/FDA counts for drugs, handles off-calendar fiscal years, sorts results by primary metric, and returns pipeworx:// citation URIs.

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

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

The description is dense but every sentence earns its place: trigger phrases, when-to-prefer, per-type data sources, fiscal-year handling, sorting, output format, and efficiency. There is no filler or redundancy; it's front-loaded with the most actionable information.

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

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

Even without an output schema, the description tells the agent what to expect: paired data, pipeworx:// citation URIs, and sorted results. It also covers entity type limits, data source specifics, and the parallel-call advantage, making the tool fully usable without additional context.

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

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

While schema coverage is 100%, the description substantially enriches parameter meaning. It explains type-dependent behavior ('type="company" pulls LATEST 10-K revenue...' vs 'type="drug" pulls FAERS...'), provides value format examples, and clarifies the 2–5 entity constraint. This goes well beyond the terse schema descriptions.

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

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

The description opens with explicit natural-language triggers like "Compare X and Y" / "X vs Y" and clearly states "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." This gives a specific verb+resource and distinguishes it from single-entity lookups like entity_profile.

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

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

The description provides clear when-to-use guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also gives concrete examples of matching user queries. It does not explicitly name a sibling tool or enumerate when-not-to-use, but the preference rule is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable detail about the output (ordered dimensions with valid codes) and the wildcard behavior for empty key positions, going beyond annotation declarations. 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?

Three sentences, front-loaded with the core purpose, followed by a practical usage note and a concrete example. Every sentence contributes meaningful information without redundancy.

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

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

Given a simple one-parameter tool with rich annotations, the description fully covers when and how to use it. It explains the key concept (dimension_order, wildcards) necessary for effective use and is complete in context.

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

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

The input schema already documents dataflow_id as a STATEC dataflow id from list_dataflows, giving 100% coverage. The description adds an example invocation but no new parameter semantics beyond what the schema provides, 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 retrieves the structure (dimensions and valid codes) of a STATEC dataset. It explicitly positions it as a precursor to get_data, which distinguishes it from sibling tools like get_data and list_dataflows.

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

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

Description explicitly instructs to use this tool BEFORE get_data, providing clear temporal context and a specific purpose (building the dot-separated SDMX key). This is strong practical guidance with no ambiguity.

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

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

Annotations already declare the tool as read-only and idempotent, and the description adds rich behavioral detail: returns gaps[] for unanswered facets, never invents facts, performs semantic excerpting, includes hop fields and citation_uri, returns contradictions[] for standard/thorough, and notes timing expectations. No contradiction with annotations.

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

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

The description is long but well-structured, covering account prerequisites, core functionality, use cases, depth semantics, output fields, and performance. Every sentence adds essential information, and the flow is logical. Minor redundancy appears in the depth explanation, but overall it earns its length for a complex tool.

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

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

This is a complete description for a tool with only 2 parameters and no output schema. It precisely describes the returned findings packet (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop fields, and time expectations. It also covers limitations (structured data only) and alternatives, so the agent can make informed decisions without needing additional context.

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

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

Schema coverage is 100% for the two parameters, so the baseline is 3. The description adds valuable context beyond the schema by explaining depth modes (quick/standard/thorough) in terms of facets, gap recovery, contradiction scans, and the paid requirement for thorough. It also clarifies that broad/multi-part questions are appropriate for the question parameter.

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 1412 structured data sources in one call, decomposes questions into facets, and routes to 5,439 tools in parallel. It explicitly distinguishes itself from open-web search and mentions alternatives like ask_pipeworx for single lookups and current news, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also notes account requirements and that free tier can use ask_pipeworx as fallback.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, full input schemas, curated examples, and 'ready to call directly, no second schema lookup needed.' This goes beyond annotations.

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

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

The description is moderately sized with three sentences, each serving a distinct purpose: purpose/usage, return behavior, and when to call. It is front-loaded and efficient, though slightly long due to the domain list.

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 sufficiently explains what the tool returns (top-N tools with names, descriptions, schemas, examples) and when to use it. It covers essential aspects for an agent to invoke the tool correctly, though it could mention limit defaults beyond the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description emphasizes the 'query' parameter as a natural language description and lists example uses, but does not add much beyond the schema's own parameter documentation.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (browse, search, look up, discover), distinguishing it from sibling data-retrieval tools.

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

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

Explicit usage guidance is provided: '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.' This clearly communicates when to use the tool and its priority.

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 covered. The description adds critical behavioral context beyond annotations: it fans out across multiple sources in one parallel call, returns specific data fields, and discloses that the USPTO PatentsView API is sunsetting and 'soft-fails until reactivated.' This level of disclosure goes 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?

The description is dense but every clause adds useful information. Example queries are slightly redundant but serve as natural-language triggers. The single-paragraph structure could be improved with bullet points for readability, but it remains appropriately sized for the tool's complexity. No filler 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?

There is no output schema, so the description must explain return values—and it does: cik, company_name, recent_filings with URIs, fundamentals (LATEST 10-K Revenues, NetIncomeLoss, Cash), patents, news mentions, LEI. It also covers source details, fallback behavior, and accepted input formats. This is fully complete for a complex tool with no output schema.

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

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

Schema coverage is 100%, but the description adds meaningful semantics beyond the schema: it gives concrete examples ('AAPL', '0000320193'), clarifies the zero-padding requirement for CIKs, and explicitly warns that names are not supported. It also explains the enum constraint for type ('Only company supported today'), which reinforces the schema but also adds context about future plans.

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

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

The description states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and lists concrete example queries. This makes the tool's purpose unambiguous 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?

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This is exactly the kind of alternative/fallback guidance needed.

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

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

The annotations already indicate destructiveHint=true and idempotentHint=true, and the description's 'Delete' aligns with these. It adds some context about clearing sensitive data, but does not disclose additional behavioral traits (e.g., permanence, error handling) beyond what annotations provide. 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 concise sentences with the action front-loaded. It provides purpose, usage, and tool relationships with zero filler. Every sentence earns its place.

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

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

For a simple one-parameter destructive tool with no output schema, the description covers purpose, usage, and relationship to sibling tools. It leverages annotations for idempotency and destructiveness, making it sufficient. It does not mention error cases, but those are less critical given the tool's simplicity and idempotentHint.

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 'key' parameter described as 'Memory key to delete.' The description's phrase 'by key' adds no new meaning beyond the schema. The example in the schema provides a concrete value, so the description does not compensate further.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' This is a specific verb (delete) and resource (memory), and it distinguishes from sibling tools like 'remember' (store) and 'recall' (retrieve) by specifying deletion. The phrase 'previously stored' adds scope.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' implying the workflow. However, it does not explicitly state when not to use it or compare with alternatives, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context by explaining the process (fetches page, extracts title/description/key links, emits markdown) and output format, going beyond annotations without contradicting them.

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

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

The description is concise and well-structured: first sentence states purpose, second explains process, third describes output, fourth lists use cases. Every sentence adds value with no redundancy or fluff.

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

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

For a simple two-parameter tool with no output schema, the description is complete. It explains what the output is (a text blob in llms.txt format), where to place it, and when to use it, leaving no significant gaps.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds minimal extra meaning (e.g., 'any URL') but does not elaborate on max_links, so it does not significantly enhance 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 clearly states the tool generates a production-ready llms.txt file for any URL, with a specific output format. It distinguishes itself from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation and listing distinct use cases.

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 'Useful for' scenarios (client sites, own projects, auditing competitors), giving clear context for when to use. However, it does not name alternative tools or explicitly state when not to use it, so it lacks full exclusion 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 rich behavioral context beyond the annotations: explains the key filter semantics with wildcards, the consequence of omitting key (fetch all series, potentially large), and the return format ('decoded series with their dimension labels and per-period values'). This goes far beyond the read-only/idempotent flags.

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

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

The description is concise, well-organized, and front-loaded with the core purpose. It includes a helpful inline example while keeping every sentence informative. No filler or redundant phrasing.

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

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

Despite having six parameters and no output schema, the description covers the essential operational details: prerequisite tool, key syntax, wildcard logic, the risk of fetching all data, and the return shape. It gives the agent enough to use the tool safely and correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description significantly enhances the most complex parameter (key) by explaining the dot-separated positions and wildcard behavior, and clarifies that omitting key vs passing an empty string are equivalent. Other parameters are left to the schema, which already provides adequate 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 the specific action and resource: 'Pull observations from a STATEC dataset.' It clearly distinguishes this from sibling tools like dataflow_structure (which provides structure, not observations) and list_dataflows. The detailed key syntax and example further reinforce the tool's unique purpose.

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

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

It gives explicit directive to 'Fetch dataflow_structure first to know the dimension order and valid codes,' which is a prerequisite and alternative-tool guidance. It also warns about the risk of fetching all series ('caution, this can be large'), telling the agent when to be careful. The example shows a concrete invocation.

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, openWorld), the description discloses result contents (`id`, English name, description, publication date, periodicity, author, category), the size of the catalog, and the query-filtering behavior. This provides meaningful context about what the agent will receive and how to navigate the dataset space.

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 focused sentences, front-loaded with the core purpose, and includes practical examples. Every sentence adds useful information without fluff 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?

Even without an output schema, the description explains what each result contains, how the `id` connects to other tools, and how to filter results. The examples and catalog-size warning give the agent enough context to decide when and how to invoke the tool.

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

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

The input schema already fully documents both parameters with clear descriptions, so baseline is 3. The description adds value by giving usage advice ('pass `query` to filter unless you really want the whole catalog'), concrete examples, and explaining the meaning of the returned `id` in relation to other tools.

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 ('Browse or keyword-search') and names the resource (STATEC datasets called dataflows). It distinguishes the tool from siblings by explicitly stating that the returned `id` is the dataflowRef to pass to `get_data` / `dataflow_structure`.

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

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

The description gives clear guidance on when to use the tool, advises filtering with `query` to avoid the whole catalog, and provides concrete examples. It also references sibling tools (`get_data`, `dataflow_structure`) and explains how the output relates to them, enabling correct tool chaining.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying that results are scoped to the caller and listing the return fields, which goes beyond the annotations and helps set expectations.

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 that are front-loaded with the core purpose, followed by return fields and a practical use case. Every sentence earns its place with no redundancy or unnecessary detail.

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

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

For a simple list tool, the description covers the scope (caller's subscriptions), the complete set of return fields, and typical use cases (review, cancel). No output schema exists, but the description adequately compensates with field enumeration.

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 the single parameter include_inactive, which is fully described in the schema. The description doesn't add extra parameter details, but the schema already provides sufficient semantics, so baseline 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb (list) and resource (subscriptions), and enumerates the exact returned fields. This distinguishes it from sibling tools like subscribe/unsubscribe, which perform different actions.

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 scenarios: 'review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it relative to subscribe/unsubscribe, though it doesn't explicitly name alternative tools or state when not to use it.

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?

Despite annotations providing no hints, the description discloses key behaviors: rate-limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and impact ('team reads digests daily'). Also warns against pasting end-user prompts, adding context beyond structured fields.

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

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

The description is a single dense paragraph but is front-loaded with purpose and usage. Every sentence earns its place (constraints, rate limit, exclusions). Slightly long but not wasteful; strong structure.

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

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

For a feedback tool with no output schema, the description covers what to include, how to scope it, what happens afterwards, and edge cases (external servers). It is complete enough for an agent to use correctly without further documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic guidance beyond the schema by advising 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the 'message' and 'context' fields. This modest addition justifies a 4.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and distinguishes itself from sibling tools by being the feedback channel for Pipeworx tools.

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

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

Explicitly specifies when to use ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection...'), even naming alternatives ('file it with that server instead'). This is exemplary usage guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: it discloses the aggregation source (CF analytics-engine), explicitly states no PII is included, reveals the result structure (pack, tool, count), and provides cache freshness (5min-1h depending on window). This is rich operational context that helps an agent understand side effects and data recency.

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

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

Four sentences, each earning its place: the core premise, output details, use cases, and data provenance. Front-loaded with the key statement, no fluff or repetition. The structure makes it easy to scan and understand 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?

For a tool with one optional parameter and no output schema, the description is thorough. It explains what is returned, the data source, privacy characteristics, and caching behavior. It also covers the key use cases. Nothing essential is missing.

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

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

Schema coverage is 100% for the single optional 'window' parameter, with the schema already explaining the enum values and tradeoffs (short vs long windows). The description mentions the window choices but adds no new semantic information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with a clear, specific statement ('What other AI agents are calling on Pipeworx right now') and details the exact outputs (top tools, top packs, total call volume). This distinguishes it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregate usage trends rather than discovery or Q&A.

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

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

The description provides three explicit 'Useful for' scenarios (discovering hot data sources, confirming canonical tool choice, aligning with agent needs), giving concrete guidance on when to use it. It lacks explicit exclusionary statements or named alternatives, but the context is clear enough to guide invocation.

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

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description discloses numerous behavioral traits: partition filters that 'return null arb signal,' a fill check that prices against live CLOB depth, and a warning that 'realizable_edge_pp ≤ 0 means... do not trade it.' No contradictions with annotations.

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

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

The description is dense and front-loaded with the core purpose, then systematically covers modes, output structure, and caveats. While lengthy, each sentence adds value; minor structure improvements could be made with bullets, but the current flow is logical and efficient.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It covers all invocation modes, expected response fields, edge cases (placeholder filters), fill-check behavior, and even references a sibling tool for additional needs. The agent has enough to select and call this tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning to both parameters. It explains that 'event' takes a Polymarket event slug or full URL for single-event mode, while 'topic' takes a seed question for cross-event scanning, and clarifies that omitting both triggers a trending scan. This goes far beyond the schema's brief descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by detailing its unique detection methods and output.

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

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

Provides explicit usage modes: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`...' and differentiates when each should be used. It also directs users to 'polymarket_fill_risk' for custom sizing, giving an explicit 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: 1h KV caching keyed on knobs, the structure of by_segment responses, diagnostics explaining empty segments, model family mechanics, and caveats like the 24h-move warning. This far exceeds what annotations alone 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 a dense block of text with ALL CAPS section headers; it is not concise. While it is logically organized (purpose, model families, response keys, knobs), the sheer length and detail make it less accessible than a trimmed version would be. It is not a tautology, but it sacrifices conciseness for depth.

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 accounts for the response shape: by_segment top-level keys, _diagnostics for debugging, and fed_candidates/fed_note. It also explains why segments may be empty (top-N stale, gate failures, knob filters) and discusses model-specific methodology. For a complex tool with 9 knobs, this is comprehensive.

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

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

The input schema already covers all 9 parameters with 100% coverage, but the description adds meaning by explaining how knobs interact: e.g., min_partition_leg_kelly applies to per-leg Kelly inside partitions because parent-level kelly_fraction_half is always 0 by design. It also explains tradeable-edge filters (min_liquidity/max_spread_pp) as execution-feed constraints. This goes beyond the schema's standalone 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 opening sentence states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a specific verb+resource+scope. It also frames the tool for 'what should I bet on today' and distinguishes it from siblings by focusing on Pipeworx data disagreements rather than pure arbitrage or fill risk.

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 the intended use case ('what should I bet on today') and notes that it avoids paging hundreds of markets. It also identifies exclusions (Fed bets are unreliable and excluded from ranking) and explains relevant knobs for filtering tradeable edges, but it does not name alternative sibling tools for explicit when-not-to-use guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by disclosing specific behaviors: the response structure (tracked[], expired[], snapshot_dates[]), the 60-day snapshot TTL limit, daily closes for decay computation, and why snapshot gaps occur. This provides rich behavioral context not available from annotations.

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

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

Although the description is long, it is extremely dense and well-structured, with clear sections for Args, RESPONSE, and LIMITS. Every sentence adds informative value, and the purpose is front-loaded. No fluff or redundancy is present.

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 absence of an output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[] with their fields) and the operational constraints (TTL, snapshot frequency, decay methodology). It covers all essential context needed for correct usage.

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

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

The input schema already provides 100% coverage of both parameters (days and window) with descriptions including defaults and ranges. The description adds minimal extra meaning, merely restating 'default 14', 'max 30', and 'default 1wk' already present in the schema. It does not provide additional parameter semantics beyond what the schema already offers.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and explicitly answers the question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tool polymarket_edges by focusing on temporal analysis of edge snapshots rather than just current edge values.

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

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

The description provides clear context for when to use the tool: to assess whether an edge is persistent or decaying, emphasizing that 'a fresh wide edge and a 3-week-old wide edge are different trades'. However, it does not explicitly mention alternatives or when not to use it, only implying that it analyzes historical snapshots.

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 goes beyond by detailing operational behavior: 'walks the ladder', mode requirements, and the risk of partial basket fills converting an arb into directional exposure. This enriches the behavioral context 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?

Though long, the description is well-structured and information-dense. It front-loads the purpose, then clearly partitions single-market and basket modes, lists outputs, and finishes with usage guidance. Every sentence adds specific value, with no redundant or filler content.

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

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

With no output schema, the description compensates by enumerating return values for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.). It also covers defaults, clamps, mode selection, and risk implications, making the tool's behavior and expected outcomes fully transparent.

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

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

The input schema provides 100% coverage for all four parameters, so the schema already explains side, event, market, and size_usd semantics. The description adds mode-conditional interpretation (single vs basket) and the 'REQUIRES one of market or event' constraint, but most parameter meaning is repeated from the schema, limiting additional value.

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 'check' against 'live CLOB order-book depth' and defines the tool's purpose: assessing realizable-vs-theoretical edge. It explicitly differentiates single-market vs basket modes and references sibling tools (polymarket_arbitrage, polymarket_edges) as the use context, removing ambiguity about its role.

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, actionable 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 warns about partial basket fills creating unhedged directional risk, which effectively conveys when and why to use it.

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 details the response structure (leg-by-leg prices, top_spreads_pp), explains the two compatibility_warning triggers, and discloses temporal_alignment limitations. It also notes that most pre-mapped topics return warnings, making the behavior and limitations transparent.

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

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

The description is lengthy but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). The first sentence front-loads the core purpose. While some sentences are dense, each contributes critical information, making the length justified for such a complex tool.

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

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

With no output schema, the description must explain what the tool returns, and it does so thoroughly: leg-by-leg prices, spread calculations, compatibility warnings, skipped cross-type/subtypes, and temporal alignment. It also covers edge cases (matched_pairs:0) that would otherwise be confusing. 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?

The input schema already documents all three parameters with descriptions, so the baseline is 3. The description adds value by explaining the two modes ('topic' as pre-mapped shortcuts vs. explicit overrides for custom pairings), which clarifies how the parameters interact. This goes beyond the schema's individual descriptions and justifies a 4.

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

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

The description opens with a clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This specifies the verb (compute spread), resource (Kalshi and Polymarket), and scope (same resolving question), and it distinguishes this tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison. The purpose is unmistakable.

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

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

The description explicitly explains two usage modes (topic shortcut vs. explicit ticker/slug) and provides guidance on when the tool's output is meaningful via compatibility_warning and temporal_alignment. It also sets expectations with 'pre-mapped ≠ tradeable.' It does not explicitly name alternative sibling tools or exclusions, but the context of cross-venue spread is clear, so a 4 is appropriate.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds contextual behavior: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and it lists all keys when the key argument is omitted. This goes beyond the structured annotations.

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

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

Three sentences, front-loaded with the core operation, followed by use cases and scoping. Every sentence adds value; 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?

For a simple read-only memory lookup with one optional parameter, the description covers operation, when to use, scoping, and related tools. The lack of an output schema is acceptable given the tool's simplicity; 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?

The input schema fully documents the single optional 'key' parameter (100% coverage). The description enriches the schema by linking the key to the 'remember' tool and providing examples (user_research_topic) of meaningful keys, plus clarifying the omit-to-list behavior.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from siblings by naming remember and forget as paired tools, and the use cases (target ticker, address, research notes) clarify its role as a memory-lookup 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 states when to use: 'Use to look up context the agent stored earlier' and gives concrete examples (ticker, address, notes). It names related tools (remember/forget) but does not explicitly exclude alternatives; however, no sibling tool provides recall of agent memory, so the guidance is sufficient.

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

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

Beyond the readOnlyHint (which is true), the description discloses the mark_read side effect, noting returned events are flagged as read to affect future calls. It also explains the data source and citation_uri format, adding valuable 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 compact but information-dense, with no wasted words. It front-loads the core purpose and efficiently covers filtering, return payload, side effects, and alternative access.

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 fully explains return value structure (source, citation_uri, raw payload) and covers all key behaviors (filtering, mark_read, polling, external feed). Makes the tool self-sufficient.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds practical semantics (e.g., 'sec_8k' as type example, ISO timestamp for since, mark_read behavior) that enrich the schema definitions.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from siblings like 'list_subscriptions' and 'recent_changes'. It explicitly states what is returned and the feed source.

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 for use ('Polls work fine') and mentions an alternative access method (public HTTP endpoint). It lacks explicit 'when not to use' exclusions, but the context is enough to guide selection.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavior beyond annotations: parallel fan-out to EDGAR, GDELT→GNews fallback (with failure conditions), USPTO soft-fail due to PatentsView API sunset, and the specific return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). 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 dense but every clause earns its place: intent phrases, fan-out behavior, fallback logic, date formats, return structure, and alternative tool reference. It is long but not repetitive or padded; front-loading the intent phrases helps agents recognize applicability.

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

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

Despite having no output schema, the description covers return format, source behavior, parameter syntax, and an explicit alternative. For a multi-source fan-out tool, this is complete and self-sufficient guidance.

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

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

Schema coverage is 100% with all three parameters described. The description adds practical guidance beyond schema: relative shorthand examples ('7d', '30d', '3m', '1y'), a typical value for monitoring ('30d' or '1m'), and clarifies value can be ticker or CIK. This earns one point above 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 opens with concrete user-intent phrases ('What's new with X', 'latest on Y'), then states a specific verb+resource: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes from siblings by naming entity_profile as an alternative for static profiles.

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 via intent examples and gives a clear exclusion: 'Use entity_profile instead when you want the static profile... regardless of window.' The description also clarifies the window semantics with 'since' formats and typical usage ('30d' or '1m').

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 provide idempotent=true and readOnly=false, and the description adds valuable context about persistence: 'scoped by your identifier', 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'. 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 well-structured, front-loaded with the primary purpose, and every sentence adds relevant detail (use cases, scoping, TTL, companion tools). 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 two-parameter write tool with no output schema and strong annotations, the description provides enough context: when to use, persistence behavior, and relationship to recall/forget. No significant gaps.

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

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

The input schema already fully describes both parameters with examples (100% coverage). The description only adds that it's a key-value pair, which is redundant with the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' across conversations or sessions. It also distinguishes itself from sibling tools by explicitly pairing with recall and forget, making the purpose unambiguous.

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

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

The description gives concrete use cases ('Use when you discover something worth carrying forward') and names complementary tools (recall, forget). It doesn't explicitly state when not to use it, but the guidance is strong enough to select the tool appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context, including internal cascading through multiple lookup endpoints, auto-disambiguation for company names, and the specific return fields (ticker, CIK, company_name, RxCUI, ingredient, brand) plus citation URIs. It does not cover error cases, but with annotations covering the safety aspects, this exceeds 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 moderately long but every sentence is informative. It is front-loaded with example queries, then gives purpose, usage instruction, and supported types with output details. The structure is clear but slightly dense; it could be broken into bullet points, but it remains concise and avoids wasting words.

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

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

Given the tool has two entity types with different outputs and no output schema, the description provides sufficient detail about return values and input formats for each type. It covers the core functionality and edge cases like auto-disambiguation. Missing error handling or no-match behavior is a minor gap, but the description is largely complete 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 properties described, so the baseline is 3. The description adds extra meaning by enumerating supported entity types for 'type' and providing format examples for 'value' (e.g., ticker, CIK with leading zeros, brand/generic names), along with the auto-disambiguation behavior, which 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 purpose: resolving a user-spoken name to the canonical/official identifier other tools require as input. It provides concrete example queries ("What's the ticker for…", "find the CIK for…") and distinctly differentiates from siblings by positioning it as the first step when you have a name but need an ID, which distinguishes it from tools like compare_entities or entity_profile.

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

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

Usage guidance is explicit: "Use FIRST whenever you have a name but need an ID." It also explains that it replaces 2-3 manual lookups, giving a clear context and effectively saying when not to need it (if you already have the ID). Supported types and input formats are specified, making it easy for an agent to decide when to invoke.

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

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

The description adds behavioral detail beyond annotations by explaining the internal process (probes with ai_visibility_check) and the output structure (ranked list with score, confidence, signal density). It doesn't cover rate limits or error handling, but annotations already declare read-only, idempotent, non-destructive safety, so the added context is sufficient.

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

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

Four sentences, each adding value: purpose, method, use case/example, and return format. Front-loaded with the main action, no fluff or repetition of schema/annotations.

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 clearly states the return format (ranked list, score, confidence, signal density). It also explains the tool's mechanics, input constraints (2-8 entities), and use case, making it fully self-contained for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description doesn't add parameter-level semantics beyond what the schema already documents, but it does reinforce the 'subjects vs competitors' structure and 'shared context' concept. No extra meaning is provided, so it stays 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 clearly states a specific verb ('Compare AI visibility') with a well-defined outcome: side-by-side ranking across multiple entities, surfacing most/least recognized. It explicitly mentions probing with ai_visibility_check, which distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

It provides clear context for when to use the tool (competitive AI-marketing audits) with a concrete example question. However, it doesn't explicitly state when not to use it or name alternatives, although the multi-entity framing implicitly contrasts with single-entity checks.

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 important behaviors: composite fan-out, return structure, graceful degradation on partial failures, and a specific 5-30s latency risk on first bundlephobia measurement. No contradiction with annotations found.

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

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

Though long, every sentence earns its place: purpose, usage, return fields, ecosystem scope, and failure handling are each covered distinctly. The structure is front-loaded with the primary purpose and progressively adds context without redundancy.

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

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

With no output schema, the description fully enumerates the return fields (summary block with exact keys, per-advisory detail, links, alternative versions). It also covers edge cases (partial failures, timeouts, ecosystem restrictions), making the tool's behavior predictable 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% (both package and version have meaningful descriptions). The description doesn't add substantial parameter-level meaning; it reiterates the 'latest' default and scoped package acceptance already present in the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource+scope formulation: 'Composite "should I add this npm package to my project" check in ONE call' and explicitly names the underlying sources (deps.dev, bundlephobia). It clearly distinguishes from siblings by limiting scope to the NPM ecosystem and stating what the tool aggregates.

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

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

Explicit guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), telling the agent exactly when NOT to use this tool and pointing to 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the retrieval mechanism (BGE-base-en embeddings, cosine, 500-char overlapping windows) and the 200K char cap with truncation flag. It also specifies output contents (offsets and similarity scores), giving the agent a clear 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 moderately long but every sentence contributes distinct information: purpose, use-case, pairing, and technical limitations. It is front-loaded with the core meaning and uses compact phrasing like 'top-N passages with character offsets and similarity scores'.

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?

Since there is no output schema, the description compensates by naming the return fields (passages with offsets and similarity scores). It also covers input limits, truncation behavior, and relationship to sibling tools, making it complete for a 3-parameter stateless search 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?

All 3 parameters are already documented in the schema with type, required status, and descriptions, and the query parameter even includes examples. The description only reinforces input types without adding new parameter-specific semantics, so a baseline of 3 is appropriate given 100% schema coverage.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which gives a specific verb, resource, and scope. It clearly states the input (text plus query) and output (top-N passages with offsets and similarity scores), and distinguishes it from siblings by explicitly contrasting with ask_pipeworx_grounded.

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

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

It explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also names the complementary alternative ask_pipeworx_grounded and describes a workflow ('fetch with the gateway, ground over the relevant passages instead of the whole document'), providing clear when-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds extensive behavioral context: the OAuth requirement, the always-on feed with a pull mechanism, email/SMS/webhook delivery details, sms verification with a 10/day cap, webhook HMAC signing with a one-time secret, and auto-disabling after 10 consecutive failures. This gives the agent a clear picture of side effects and constraints.

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 exceptionally well-structured. It opens with the core purpose and return value, moves to authentication, then lists supported types with examples, and finally details delivery channels. Every sentence carries useful information, and the use of semicolons and colons packs information efficiently without 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?

Despite having no output schema, the description covers all necessary aspects: the action, the required account type, supported subscription types with parameters, delivery options with constraints, and failure behavior (webhook auto-disable). It is fully self-sufficient for an agent to decide when and how to invoke the tool correctly.

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

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

Input schema coverage is 100% with detailed descriptions for every parameter and nested delivery object, so the baseline is 3. The description adds value by explaining the return value (new subscription id), giving concrete examples for each subscription type, and clarifying delivery channel behavior (e.g., feed always on, sms verified phone). These details enhance the schema without contradicting it.

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

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

The description opens with a specific verb-resource pair: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the tool's function and distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts by emphasizing the creation of a new subscription rather than listing, removing, or retrieving alerts.

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

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

It provides clear context for when to use the tool: requiring a Pipeworx OAuth account and noting that anonymous/BYO users cannot persist subscriptions. It also explains that the feed is always on and can be pulled via recent_alerts, suggesting this tool is for proactive notification. However, it does not explicitly name all sibling tools as alternatives, leaving some implicit 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 read-only, idempotent, and open-world semantics. The description adds valuable context that it returns 'exact tool + argument shape' for each example question, drawn from a live catalog of thousands of tools, and describes the optional topic behavior. This exceeds merely restating 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 a single dense paragraph, front-loaded with user-perspective examples and covering intent, return contents, category list, invocation variants, and usage instructions. While not terse, every sentence contributes necessary context, and the structure flows logically from what it does to how to use it.

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

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

For a tool with one optional parameter and no output schema, the description is fully self-contained: it explains what is returned, the category buckets, how to call it with and without the topic parameter, and when to prefer it over other tools. It even points to meta-tools for learning, providing a complete onboarding 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?

Schema coverage is 100% for the single optional `topic` parameter, and the description enriches it by providing example values ('finance', 'pharma', 'betting') and clarifying that omitting it yields a cross-category spread. This adds meaningful guidance beyond the schema's basic property 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?

Clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions, and explicitly lists the categories. It distinguishes itself by stating 'Use this FIRST' and referencing meta-tools like ask_pipeworx, entity_profile, and compare_entities, so the agent knows this is a discovery tool rather than an execution 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?

Gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains optional topic filtering with examples and contrasts with specific sibling tools, making alternatives 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?

Beyond annotations, adds ownership enforcement, soft-delete ('deactivated (not deleted)'), and that historical events stay available via recent_alerts. This gives a fuller behavioral picture even with annotations present.

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 core action, followed by relevant constraints and side effects. 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?

For a simple mutation tool with no output schema, it covers purpose, ownership, and persistence behavior. Missing explicit error cases or response, but not necessary given annotations and simplicity.

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 already fully describes the id parameter ('uuid returned by subscribe'). Description only says 'by id,' adding no additional meaning, consistent with baseline for 100% coverage.

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

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

Description opens with 'Cancel a subscription by id,' a specific verb+resource statement. It also notes ownership enforcement and soft-delete behavior, distinguishing it from sibling subscribe/list_subscriptions.

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

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

Provides clear context: ownership restricted to your own subscriptions, and deactivation keeps history available via recent_alerts. However, it doesn't explicitly name alternatives or state when not to use, though no direct alternative exists.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which covers the safety profile. The description adds substantial behavioral detail beyond that: it specifies the verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported), the return of an actual value with pipeworx:// citation and reasoning, the internal routing logic, and the exact percent-delta math. This is rich context 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 longer than average but follows a clear and logical structure: example queries → when to use → routing behavior → return format → efficiency benefit. It is front-loaded with a purpose statement and every sentence contributes meaningful information, though it could be tightened by removing some redundancy (e.g., 'routed to the right live source, answered with verbatim evidence, then judged').

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

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

Given the absence of an output schema and the presence of rich annotations, the description fully covers the tool's purpose, routing, return values, tolerance semantics, and usage context. It even explains the composite nature ('Replaces 4–6 sequential calls') and includes example inputs, making it essentially self-contained for an agent deciding whether and how to invoke it.

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

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

Schema coverage is 100%, so the schema already thoroughly documents both parameters: the claim example and tolerance_pct's meaning and default. The description adds little beyond the schema—it mentions tolerance in the narrative but the schema already defines it clearly. This meets the baseline for high coverage without adding significant new meaning.

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

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

The description opens with concrete natural-language examples ('Is it true that…', 'fact check') and explicitly states it performs 'claim verification against authoritative sources.' It distinguishes the tool from siblings by describing the two routing paths (financial via SEC EDGAR vs. any other claim via grounded pipeline) and mentions it replaces 4–6 sequential calls, making its unique 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the boundary between company-financial claims and 'any other factual claim' with automatic routing. It does not name specific sibling alternatives to exclude, but the context strongly implies the tool is for verification rather than general research or data retrieval.

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