hackernews

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context: default model is free (Workers AI Llama-3.3-70b), Anthropic requires a BYO API key with direct cost, and it returns per-model scores with confidence, signals, and raw_response. This exceeds the annotations without contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, then key options, return format, and use cases. Every sentence adds value and there is no wasted text.

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 explicitly states the return format (per-model {score, confidence, signals, raw_response} + combined view). It also covers default model, optional models, and API key behavior. All 4 parameters are documented in the schema, and the description ties them together. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds slight nuance: it explains that workers-ai is the free default and that _apiKey is 'BYO key — you pay Anthropic directly,' which complements the schema. However, it does not significantly enhance the already well-documented parameters.

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 (probe LLMs) and the resource (a business/brand/product/topic) with a specific output (visibility score 0-100). It is specific and unambiguous, but it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it misses the top score.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives context for when to use the tool, but it does not mention exclusions or alternatives like 'use this instead of X.'

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 (readOnlyHint, idempotentHint, destructiveHint=false) already convey the safety profile, and the description adds valuable behavioral context: routing logic, automatic argument filling, stable citation URIs, works on every tier, and described as 'one fast call'. This exceeds the baseline and does not contradict annotations.

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

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

The description is long but well-structured and front-loaded with a directive. Examples and escalation guidance are useful, but length is slightly excessive for a default entry-point tool. Every sentence contributes value, so it earns a 4 rather than a lower score.

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 explains the output format (structured answer with pipeworx:// citation URIs) and covers key usage scenarios, alternatives, performance characteristics, and the tool's role as the default entry point. This is comprehensive 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 schema has 100% description coverage and all parameters are aliases for 'question', which the description confirms by stating it accepts natural language questions. The description provides example questions but does not add technical parameter semantics beyond the schema, so it does not exceed the baseline.

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

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

The description clearly states the tool's function: answering factual questions by routing to structured data sources like SEC filings, FDA data, and economic statistics, returning structured answers with citations. It explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different 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 when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' for grounded or deep research. It also covers when not to use it, such as for breaking news (already handled internally) and multi-part broad questions (use deep_research).

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, and idempotent annotations, the description discloses experimental status, live candidate routing behavior, the retirement date of the last candidate, and the lack of fallback. This adds substantial context about how the tool behaves and why it might differ from the stable version.

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

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

The description is well-structured and front-loaded with the tool's identity, then clarifies current state, usage, and fallback. Every sentence carries specific, non-redundant information (e.g., 5,529 tools, retirement date, no fallback), earning its place without being verbose.

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 states 'same response shape' as ask_pipeworx, which is sufficient given this is a beta alias of a known sibling tool. It covers routing scope, current state, and evaluation behavior, making the tool's behavior complete enough for an agent to invoke and interpret results.

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

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

The input schema fully describes all six parameters (question and five aliases), so schema coverage is 100%. The description only adds that arguments are identical to ask_pipeworx, which is useful but does not meaningfully enhance per-parameter understanding. 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 identifies this as a beta version of ask_pipeworx: a universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by being an experimental edge, 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?

It provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no active candidate, so it matches ask_pipeworx exactly) and that results are compared against the stable router, giving clear context for when to choose this tool over alternatives.

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

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

Annotations already state readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral detail beyond these: it only uses the tool result content, has specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and returns structured evidence. It also notes the cost of an extra LLM call. No contradiction with annotations.

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

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

The description is dense yet every sentence earns its place: purpose, mechanism, return format on success, refusal formats, use cases, and cost tradeoff are all covered succinctly. It is front-loaded with the key differentiator ('Hallucination-resistant') and structured logically, with no filler or redundant 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 fully specifies the return value shape including evidence, confidence, source, and refusal reasons. Combined with rich annotations and sibling context (ask_pipeworx, ask_pipeworx_beta), the description is complete for an AI agent to know what to expect and how to act on results.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for 'question.' The description adds no new parameter semantics but also doesn't need to, since the schema fully covers the only meaningful input. The tool's behavior around the question parameter is clear from the schema, 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 specific verb+resource: 'hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes it from the sibling ask_pipeworx by emphasizing grounded extraction and refusal when data doesn't directly answer. It explains the mechanism (picks tool, fetches data, extracts using only tool result) and the exact use case, 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?

Explicit 'when to use' guidance is provided: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also explicitly says to 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost, giving a clear decision rule against the sibling tool.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing detailed behavioral nuances: parallel fan-out, resolver confidence levels, low-confidence short-circuit behavior, closed-market handling, wide-spread market warnings, and cancellation-rule parsing. It even explains the practical reality of de-indexed markets and the blocking nature of both routes. This is comprehensive and adds substantial value 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 long but extremely well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) and a front-loaded purpose statement. Every section adds necessary detail for a complex tool, so it earns its place. However, the sheer volume of information and some redundant clarifications (e.g., explaining both blocking routes repeatedly) prevent a perfect 5.

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

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

Given the tool's high complexity and the absence of an output schema, this description is exceptionally complete. It covers input formats, classifier types, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent-event extraction, news fallback fields, safety behaviors, and cancellation-rule risk. It leaves little to guesswork, making it a fully self-contained reference for an AI agent.

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

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

The input schema already provides 100% descriptive coverage of all three parameters, so the baseline is 3. The description enriches this by giving concrete fan-out examples that illustrate what 'thorough' depth produces per market category, and by explaining the input format (slug/URL/question) in the context of the resolver. It does not explicitly discuss depth/include_raw by name, but the examples and response-shape explanations add meaningful context 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 first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It uses a specific verb ('research') and resource ('Polymarket bet') and distinguishes itself from siblings by focusing on market-vs-model comparison and evidence packets for betting decisions. The 'Use for' section further clarifies its niche.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive fan-out examples for different bet categories, giving concrete context. However, it does not explicitly mention when not to use it or compare it to alternatives like search or validation tools, so it falls short of a 5.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses specific behavioral traits: pulls from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and replaces 8-15 sequential lookups. This adds substantial context beyond the annotations.

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

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

The description is dense but well-structured: starts with trigger phrases, then core function, data source specifics, sorting, and efficiency benefit. Every sentence serves a purpose, with no filler, and is appropriately sized for the tool's complexity.

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

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

The description covers all relevant aspects for a comparison tool: input constraints (2-5), data sources, fiscal year handling, sorting, output (paired data + citation URIs), and performance benefit. With no output schema, it adequately explains return values, making the tool fully understood.

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

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

Although schema coverage is 100%, the description enriches parameter meaning: it explains that 'type' determines data source (SEC vs FAERS) and that 'values' are tickers/CIKs or drug names with examples. It also clarifies sorting behavior and output structure, adding value beyond the bare schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with specific trigger phrases. It distinguishes itself from siblings like entity_profile (single entity) and resolve_entity by explicitly preferring this over sequential single-pack lookups.

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

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

It explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also details what each type (company/drug) does, making the decision between entity types obvious.

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 by disclosing account requirements, paid tier, gap recovery behavior, contradictions[] output, citation_uri fetchability constraints, semantic excerpting, and latency expectations. These details are critical for an agent to set user expectations and are not present in the annotations.

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

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

The description is long but well-structured and front-loaded with the most critical operational warning (account required). Every sentence provides operational value—core function, usage guidance, depth semantics, output format, and timing—without redundancy, making the length justified.

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

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

This tool has no output schema, so the description must cover return values, which it does comprehensively: findings packet contents (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, and citation_uri conditions. It also covers account prerequisites and performance expectations, making it complete for the tool's complexity.

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

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

Although the schema already covers both parameters, the description adds substantial semantics: it explains the depth enum (quick=3, standard=5, thorough=8), the default (standard), the paid plan requirement for thorough, and the associated gap-recovery/contradictions behaviors. This is extra meaning 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 what the tool does: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources', decomposes questions into facets, routes to 5,529 tools in parallel, and returns a findings packet. It explicitly distinguishes itself from ask_pipeworx, 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?

Usage guidance is explicit: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also states when it is best: 'Best for broad/multi-part questions over structured data', providing clear alternatives and exclusions.

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

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

Beyond the annotations (read-only, idempotent), the description adds concrete behavioral details: it 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed.' This gives agents a clear expectation of the tool's output and immediate usability. It does not mention rate limits or ranking logic, but annotations cover the safety profile.

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

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

The description is front-loaded with 'Find tools by describing the data or task' and then provides a useful domain list and return-format details. While the domain list is somewhat long, it is purposeful in helping agents recognize applicable topics. Every sentence adds value; 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 discovery tool with six parameters (mostly aliases) and no output schema, the description sufficiently covers what is returned (top-N tools with full schemas) and when to use it. The input schema already provides examples and alias handling. It could have specified default/max limit textually, but that is in the schema. Overall, the description provides enough context for correct invocation.

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

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

Schema description coverage is 100% and already documents all parameters, including aliases for 'query' (q, task, search, description) and the 'limit' range. The description adds only a high-level statement that the tool takes a 'description of what you want to do,' which aligns with the schema but does not add new semantics beyond it. The schema carries the full weight, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by explicitly positioning itself as a discovery layer (e.g., 'Call this FIRST when you have many tools available'), which is unique among the listed siblings that are direct data 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?

Provides explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly frames it as an initial discovery step, contrasted with using specific tools 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 discloses significant behavior beyond the annotations: it fans out in parallel, returns specific fields like recent_filings with pipeworx URIs, and notes that the USPTO PatentsView API sunset in May 2025 and soft-fails. It also explains the fallback chain for news (GDELT→GNews) and the LEI via GLEIF. These details are not present in the annotations and provide valuable behavioral context.

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

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

The description is dense but not overly long, starting with relatable example queries then moving to technical details. It uses semicolons to list return fields, making it scannable. However, it's a single long run-on sentence; breaking it into bullet points or shorter sentences would improve readability. Still, 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?

Without an output schema, the description carries the burden of explaining return values, and it does so thoroughly: it lists each returned field (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and clarifies edge cases like the patents API soft-fail and the name limitation. Given the tool's complexity (multi-source fan-out), the description is complete enough for an agent to understand what it will receive and how to use it correctly.

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

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

Schema description coverage is 100%: both parameters (type and value) are fully described with enums and examples. The description essentially repeats what's in the schema, adding the example queries but no new parameter semantics. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes itself from siblings by noting it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF and returns a structured set of fields. Example queries ('tell me about X', 'research Acme') provide concrete usage context, and the mention of 'ALWAYS PREFER' separates it from chaining single-pack lookups.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells when not to use it directly: 'names not supported (use resolve_entity first if you only have a name).' This gives clear direction on both preferred and fallback usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows the safety profile. The description adds practical usage context but no additional behavioral details beyond what annotations imply (e.g., no mention of permanence or return values). It does not contradict annotations.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: action, when to use, and related tools. There is 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 one-parameter tool with no output schema, the description fully covers what the tool does, when to use it, and connects to siblings. Annotations cover destructive/idempotent behavior, so no critical information is missing.

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

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

The schema description covers 100% of the parameter ('Memory key to delete'). The description repeats this without adding new meaning about key format or usage. Baseline of 3 is appropriate since the schema carries the parameter information.

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: 'Delete a previously stored memory by key.' This uses a specific verb and resource, and the mention of pairing with 'remember and recall' distinguishes it from sibling tools.

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

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

The description gives explicit usage contexts: 'when context is stale, the task is done, or you want to clear sensitive data.' It also references sibling tools ('Pair with remember and recall'), but does not explicitly state when not to use this tool. This is clear but not fully exhaustive.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds behavior: 'Fetches the page, extracts title/description/key links' and outputs a 'single text blob.' This explains the fetch-and-transform process and output format without contradicting annotations.

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

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

The description is front-loaded with the primary action, then provides process detail and use cases in a compact format. Every sentence adds value, and the 'Useful for' list is structured for easy scanning.

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 generator with robust annotations, the description covers the output ('standard llms.txt markdown format', 'single text blob ready to drop at site-root/llms.txt') and the high-level workflow. No output schema exists, but the description sufficiently communicates the return value.

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

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

Input schema covers both parameters (url and max_links) with clear descriptions, giving 100% coverage. The tool description doesn't add parameter-specific detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific action: 'Generate a production-ready llms.txt file for any URL' and details the process (fetches page, extracts title/description/key links, emits standard markdown). This clearly distinguishes the tool from sibling tools, none of which target llms.txt generation.

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

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

The 'Useful for' section explicitly lists three concrete scenarios: getting a client's site indexed, drafting for own project, and auditing competitor presence. It doesn't provide exclusions or alternative tool references, but given the absence of similar siblings, this is clear context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds that it resolves comment IDs to text and returns author, text, time, and reply count, which is useful beyond annotations. No contradiction exists.

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?

Each of the five sentences serves a distinct purpose: function, usage preference, differentiation from get_item, ID sourcing, and output description. It is front-loaded with the core action and contains no wasted words.

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

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

The description fully covers the tool's role: it specifies the input (item ID), the scope (top-level comments with text), and output fields, and gives context on when to use it. Since there is no output schema, the return description is necessary and present.

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

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

Schema coverage is 100% with clear descriptions for both id and limit. The description's mention of 'by its item ID' aligns with the schema but adds no extra parameter-level detail beyond what is already in the schema, so it stays at the baseline.

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

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

The description uses a specific verb ('Fetch') and resource ('discussion... on a Hacker News story'), and explicitly distinguishes from get_item by noting it returns actual text rather than just comment IDs. It also clarifies the scope to top-level comments, 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 explicitly says 'PREFER OVER WEB SEARCH' for HN discussion/sentiment queries, and contrasts with get_item which returns only IDs. It also tells users to find a story ID via get_top_stories or search_hn, giving clear context for when to use this tool.

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

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

Annotations already declare safe read-only behavior. The description adds valuable context by listing the returned fields (full text, score, author, timestamp, child replies), giving the agent a concrete idea of the output beyond the annotations.

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

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

The description is a single sentence, front-loaded with the action, and includes an example and key return fields. No wasted words; every element contributes to understanding.

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 fetch tool with an output schema, the description is complete. It states what the tool fetches, provides an example, and lists the important return fields. Sibling tools do not require additional clarification.

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

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

Schema coverage is 100% with a clear description ('The numeric Hacker News item ID'). The description adds an example and reinforces the 'by ID' usage but does not significantly extend beyond the schema's existing 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 action: 'Fetch a Hacker News story or comment by ID'. It specifies the resource (Hacker News items), the scope (by ID), and provides an example ID. This distinguishes it from list-oriented siblings like 'get_stories' and 'get_top_stories'.

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

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

The description clearly conveys when to use the tool: when you have a specific item ID to fetch. It does not explicitly mention alternatives or exclusions, but the 'by ID' phrasing gives strong contextual guidance for appropriate usage.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds useful behavioral details like returning self-text instead of URL for Ask/Show and listing the exact fields returned. No contradictions 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?

Two sentences, front-loaded with the main action, and every clause adds value (types, usage guidance, return fields). No fluff or repetition of schema content.

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

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

The tool is simple with 0 required parameters, and the description covers return values explicitly, which compensates for the lack of an output schema. Combined with strong annotations, this is nearly complete for an agent to invoke successfully.

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 both parameters, so the baseline is 3. The description adds semantic clarity beyond the schema by mapping enum values to human-readable concepts ('new (newest)', 'ask (Ask HN)', 'job (jobs/hiring)'), exceeding 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 a specific verb and resource ('Fetch Hacker News stories') and enumerates the supported types. It clearly distinguishes from siblings like get_top_stories (which is likely a single fixed type) and get_hn_comments.

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 'PREFER for' phrase gives explicit user-intent examples ('newest HN stories', 'Show HN', etc.), which is strong when-to-use guidance. It does not explicitly mention when-not to use or name alternative tools, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds context about live data and the 'up to count' limitation, but does not disclose rate limits, authentication, or other behavioral details. 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?

Two sentences front-load the verb and resource, then cover the parameter behavior and return fields without redundant words. The description is efficient and well-structured.

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

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

This is a simple read-only tool with one optional parameter, rich annotations, and an output schema. The description provides the essential context about live data, count limits, and return fields, leaving no critical gaps.

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

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

The schema covers the single `count` parameter with its default, but the description adds the crucial clarification that the tool returns 'up to `count` stories', implying it may return fewer. This goes beyond the schema's generic 'Number of top stories to return'.

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

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

The description clearly states the tool fetches 'current live top-ranked Hacker News stories from the Firebase API', using a specific verb and resource. It distinguishes from siblings like get_stories by mentioning 'top-ranked' and 'live', but does not explicitly compare or contrast with alternatives.

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

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

No explicit when-to-use or alternative guidance is provided. The description implies it should be used for retrieving top Hacker News stories, but does not mention exclusions or direct users to sibling tools like get_hn_comments or search_hn for other needs.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the default active-only filter and enumerates the return fields (id, type, params, etc.), which is valuable since there is no output schema. No contradiction with annotations.

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

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

The description is two concise sentences, front-loaded with the action, and includes targeted usage guidance. Every word earns its place with no 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 one optional parameter, rich annotations, and a clear return field list, the description is largely complete for an agent to invoke the tool correctly. Minor omissions like pagination or ordering are not critical for this simple list 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 only parameter, include_inactive, is fully described in the schema with its default value. The description does not add any additional parameter-level meaning beyond what the schema already provides, 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 and resource, and specifies the returned fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing 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?

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel.' This clearly indicates when to use the tool, though it does not explicitly name alternative tools like subscribe or unsubscribe.

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?

Providing rich behavioral context beyond the all-false annotations: the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), and the claim_token workflow for tracking resolution. This gives agents realistic expectations about side effects and follow-up 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 longer than average but every sentence conveys a distinct operational fact. It is front-loaded with a clear summary, followed by usage criteria, exclusions, token mechanics, rate limits, and quota. Slightly overpacked, but each piece 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?

Since there is no output schema, the description compensates by explaining what the return value contains (claim_token) and how to use it to check status. It addresses the full lifecycle: when to file, what to include, limitations, and follow-up, making the tool fully understandable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token round-trip workflow ('Filing without an account returns a claim_token; pass it back later') and by giving message content guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which is beyond the schema descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist.' — a specific verb and resource that clearly states the tool's purpose. It distinguishes itself from sibling tools like ask_pipeworx by framing itself for bug/feature/praise feedback rather than general queries.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: 'if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds meaningful behavioral context: it is self-aggregating, derived from CF analytics-engine, excludes PII, returns only (pack, tool, count), and is cached 5min-1h depending on window. This provides freshness and privacy characteristics beyond the annotations.

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

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

The description is compact and front-loaded. First sentence states the function, followed by a focused bullet list of use cases, then a brief note on data provenance and caching. Every sentence adds value without redundancy.

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

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

With no output schema, the description compensates by loosely describing the return shape ('just (pack, tool, count)') and the nature of the data. It covers data sources, privacy, and caching. It could be more explicit about exact response structure or sorting, but for a simple read-only tool with strong annotations, this is sufficiently complete.

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

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

The sole parameter 'window' is fully documented in the schema with enum values and semantics (short vs long windows). The description mentions the same window options but adds no additional meaning beyond the schema. With 100% schema coverage, 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 statement 'What other AI agents are calling on Pipeworx right now' and specifies the return elements (top tools, top packs, total call volume) and window options. This clearly differentiates it from siblings like discover_tools by focusing on aggregate agent call behavior rather than tool discovery.

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 includes a 'Useful for' bullet list with three concrete application scenarios (discovering hot data sources, confirming canonical tools, aligning use case with demand). It doesn't explicitly contrast with alternatives or provide when-not-to-use, but the context is strong enough for an agent to select 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 read-only, non-destructive, but the description adds substantial behavior: partition_check thresholds, Jaccard similarity anchor, placeholder filtering, fill_check against live CLOB depth, and the warning that realizable_edge_pp <= 0 means 'do not trade it.' No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the primary purpose. Every section contributes essential operational detail, though a slightly tighter organization could improve skimmability.

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

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

Given the tool's complexity and absence of an output schema, the description covers modes, filters, thresholds, response shape, and a critical execution caveat (thin legs, realizable vs theoretical edge). It sufficiently equips an agent to select and invoke the tool correctly in varied scenarios.

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

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

Schema covers both parameters, but the description adds deep meaning: examples of event slugs and topic seeds, plus concrete behavior for each mode (walking child markets, computing partition_check, flattening related events). This transforms parameter usage from bare strings to actionable tool 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by detailing three modes (trending_scan, event, topic) and contrasts with polymarket_fill_risk for sizing.

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

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

Explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends event mode for a specific market and points to polymarket_fill_risk for custom sizing, effectively excluding other tools.

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

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

Beyond the annotations, the description discloses significant behavioral context: caching (at KV level for 1h), diagnostic output fields, per-model behavior (e.g., 'soft signal w/ halved Kelly'), placeholder filters, and the Fed signal caveat. This goes far beyond 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 extremely long and dense, mixing model details, response structure, and knobs into a single paragraph with extensive parentheticals. While all content is relevant, the lack of structural formatting (e.g., bullet points or sections) makes it harder to parse. It could be tightened and organized.

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 (9 parameters, multiple model families, no output schema), the description is remarkably complete. It covers the purpose, model logic, response top-level fields, filtering knobs, diagnostics, caching, and known limitations (e.g., Fed signal unreliability). An agent can confidently invoke this tool after reading 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?

Although the schema already covers all parameters with 100% coverage, the description adds interpretive value that aids understanding. For example, it explains that min_liquidity / max_spread_pp 'drop opportunities where edge isn't realizable' and details the special behavior of min_partition_leg_kelly for partition arbs that return 0 Kelly at the parent level. This significantly enriches the raw 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 opens with a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly defines the tool's function and differentiates it from sibling tools like polymarket_arbitrage by emphasizing the Pipeworx data disagreement angle.

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

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

The description states it is 'Built for "what should I bet on today"' and explains that agents discover opportunities without paging hundreds of markets. It also describes segments and knobs, giving clear context for when to use. However, it does not explicitly name alternatives or exclusion criteria, 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?

Even with readOnlyHint=true and destructiveHint=false, the description discloses critical behavioral limitations: the 60-day snapshot TTL bound, the fact that snapshots are written only on cache-miss (so gaps mean no scan), and that decay numbers use daily closes rather than intraday. This significantly enriches how an agent should interpret results.

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 densely packed with distinct, necessary sections (Args, RESPONSE, LIMITS). It is front-loaded with the core question it answers and uses uppercase labels to separate concepts. Every sentence contributes operational value, and no fluff 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?

With no output schema, the description fully compensates by outlining response fields (tracked[], expired[], snapshot_dates[]) and their meanings. It also explains data gaps and history bounds, making the tool actionable and complete for a telemetry listing tool.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description repeats defaults ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') and adds the phrase 'snapshot family,' but this is a minor semantic addition. No material meaning is added beyond the schema's existing descriptions.

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

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

The description opens with a specific verb-resource pairing: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a precise question and clearly differentiates from siblings like polymarket_edges (which likely shows current edges) by focusing on persistence and decay over time.

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 strong contextual usage advice: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)' and mentions the median lifespan as 'your competition clock.' However, it does not explicitly name an alternative tool (e.g., polymarket_edges) for current-edge viewing, so it falls short of a full 5.

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

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

Annotations (readOnly, idempotent, non-destructive) are supplemented with rich behavioral detail: the tool 'walks the ladder', returns a verdict, identifies thin legs, and computes 'forced_directional_risk'. It warns about the dominant loss mode in arb bots. This goes far beyond the annotations, revealing internal behavior and risk scenarios 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 long and dense, but structured with clear mode labels (SINGLE-MARKET, BASKET) and a final 'USE THIS' directive. Every sentence adds functional information. Minor deduction for being a wall of text; it could be split into bullets for quicker parsing, but it remains appropriately sized for the tool's complexity.

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

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

Given the absence of an output schema, the description comprehensively lists return values for both modes (e.g., vwap_fill_price, capture_ratio, thin_legs[], max_clean_notional_usd). It also covers prerequisites, parameter interpretation, and failure modes. The tool has two distinct modes and all relevant context is provided without missing critical aspects.

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

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

The input schema covers all parameters at 100%, but the description adds substantial meaning: it explains how `size_usd` is interpreted differently for buys (max spend) vs sells (target proceeds) vs basket (settlement notional S per leg), clarifies the side defaults (e.g., 'default auto from partition sum'), and distinguishes market vs event usage. This deepens schema semantics.

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

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

The description opens with a clear definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly names the resource (order-book depth) and the verb (check), and distinguishes two modes (single-market and basket). It also differentiates from siblings by referencing polymarket_arbitrage and polymarket_edges, making the tool's unique role obvious.

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

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

Provides explicit when-to-use guidance: 'USE 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, partial fills create unhedged positions) and how to select modes via required parameters. The direction is unambiguous and actionable.

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

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

Beyond the readOnly/idempotent annotations, the description thoroughly discloses behavior: compatibility_warning triggers, skipped_cross_type/subtype counters, temporal_alignment logic, and the caveat about pre-mapped topics. 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 and dense, but every sentence earned its place given the tool's complexity. It is front-loaded with purpose and flows logically to warnings. Slightly run-on but not bloated.

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

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

With no output schema, the description fully explains response structure (leg-by-leg prices, spread array, safety fields) and edge cases. It covers modes, matching logic, and failure conditions comprehensively for a complex tool.

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

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

Schema coverage is 100% and all three parameters are already described. The description adds value by explaining the topic shortcuts, the override relationship between topic and explicit tickers, and the meaning of using both explicit parameters together. Baseline 3 plus clear semantic additions earns 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — a precise verb+resource statement that distinguishes this from siblings by naming both venues and the spread concept. It clearly defines the tool's unique 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?

It provides explicit usage context: two modes, when the delta is a 'real signal' vs not, and the temporal alignment condition for meaningful spreads. It also warns that pre-mapped topics are often not tradeable. However, it doesn't explicitly name alternative tools for exclusion, so it falls just short of a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: omitting the key lists all keys, and the tool is scoped to a per-identifier memory space. It does not contradict annotations and provides useful supplementary details.

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

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

Three sentences, each earning its place: the first states the core functionality, the second gives use cases, and the third explains scoping and related tools. There is no fluff or repetition, and the most important information is front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description is thorough. It covers the purpose, usage scenarios, scoping, and the relationship to sibling tools (remember, forget), providing everything an agent needs to decide when 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% with the key parameter already described as 'Memory key to retrieve (omit to list all keys).' The description adds semantic meaning by explaining the key references a value saved via 'remember' and by giving concrete examples (user's target ticker, address, research notes), which helps an agent understand what kind of data to expect.

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

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

The description opens with a specific and clear action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It names the resource (saved memory) and the two modes of operation, and it explicitly distinguishes itself from siblings by referencing 'remember' and 'forget' as complementary tools.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides clear alternatives and relationships: 'Pair with remember to save, forget to delete.' The scoping note ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') helps the agent understand applicability.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive traits. The description adds meaningful context beyond those: events are written by 'the evaluator' to a persisted feed, each event includes specific fields, mark_read:true has a side effect (flagging read so next call shows newer ones), and the same feed is available externally. This transparently discloses the state-changing behavior of mark_read, which is not fully implied by the annotations alone.

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

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

Four tightly-packed sentences with zero fluff. The first sentence states the core action, the second describes the return structure, the third explains filtering and mark_read side effect, and the fourth offers an alternative access path. Every sentence earns its place, and the most critical information is front-loaded.

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

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

Despite having no output schema, the description explains what is returned (source, citation_uri, raw payload) and the filtering/marking behavior. It covers the tool's purpose, parameters, side effects, and alternative access. Given the tool's moderate complexity and the rich schema/anatations, this description is fully complete for an AI agent to select and invoke it correctly.

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

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

The input schema has 100% coverage for all 5 parameters, so the baseline is 3. The description adds extra value by giving a concrete type example ('sec_8k'), explaining the since parameter as ISO timestamp, and elaborating on mark_read's effect ('so the next call only shows newer ones') which goes beyond the schema's single-line description. It does not repeat limit/unread_only details, but those are already well-documented in the schema.

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

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

The description opens with a specific verb+resource construction ('Pull fired events from your subscription feed') that immediately distinguishes it from sibling tools like list_subscriptions. It clearly identifies the return payload (source, citation_uri, raw event payload) and the filtering options, making the tool's 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?

Provides clear usage context: polling is endorsed, filtering by type and since is described, mark_read behavior is explained, and an alternative access method (GET registry.pipeworx.io/alerts.json) is given. It does not explicitly name exclusions or compare against sibling tools, but the guidance is sufficient for correct selection and 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description goes further by detailing the parallel fan-out to SEC EDGAR, GDELT→GNews fallback logic, USPTO soft-fail due to API sunset, and the exact return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This is substantial behavioral context that annotations alone do not provide.

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

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

The description is dense but well-organized. It front-loads natural-language queries and the core one-call fan-out behavior, then efficiently adds fallback details, parameter syntax, return summary, and the alternative tool pointer. Every sentence earns its place and no filler 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 that this is a multi-source tool with no output schema, the description is remarkably complete. It covers trigger phrases, data sources, failure/fallback behavior, parameter format, return structure, and an alternative tool. An agent has enough context to select the tool, invoke it with correct parameters, and understand the returned data.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples for `since` (ISO date vs '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also reinforces that `value` accepts a ticker or zero-padded CIK, which clarifies usage beyond the bare schema text.

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

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

The description clearly defines the tool as a 'change feed for a company in the last N days/weeks/months' and enumerates the concrete data sources (SEC EDGAR, GDELT/GNews, USPTO). It also explicitly distinguishes this tool from the sibling entity_profile by pointing out the alternate use case, so an agent can immediately grasp the specific purpose.

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

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

The description includes natural-language trigger examples ('What's new with X', 'latest on Y') and explicitly states when to use entity_profile instead ('Use entity_profile instead when you want the static profile... regardless of window'). It also explains fallback conditions (GDELT preferred, GNews on rate limit/5xx), which is actionable guidance for choosing this tool over others.

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

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

Annotations already indicate a non-read, non-destructive, idempotent operation. The description adds critical context beyond annotations: key-value storage scoped by identifier, with persistence duration varying by auth state (persistent for authenticated, 24h for anonymous). This adds meaningful behavioral detail.

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

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

The description is four sentences, each conveying essential info: purpose, usage examples, storage scoping/persistence, and related 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 2-param write tool with no output schema, the description covers purpose, trigger conditions, persistence model, and relationships to recall/forget. Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description's examples of keys/values align with schema descriptions but don't add technical format requirements beyond what the schema provides. It reinforces the key-value structure but adds no new parameter semantics.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It distinguishes from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.' Examples of data types make the purpose concrete.

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 clear when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also distinguishes from retrieval and deletion tools by naming recall and forget, and explains session vs authenticated persistent storage.

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

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

The description discloses behavioral traits beyond annotations, such as graceful degradation of LEI/FIGI enrichment when upstream sources fail, explicit labeling of source origins, and stating unresolved identifiers rather than omitting them. These details add significant context beyond the readOnly/idempotent annotations.

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

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

The description is front-loaded with a quick use-case and then structured tightly by entity type. It is longer than average but every sentence adds value; the only minor deduction is the repeated examples that could be trimmed slightly without losing meaning.

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

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

Given no output schema and moderate complexity, the description is highly complete. It covers input semantics, return characteristics (source-labeled identifiers, explicit unresolved), fallback behavior, and replaces manual lookups—sufficient for an agent to select and invoke correctly.

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

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

While schema coverage is 100%, the description enriches parameter semantics substantially. It explains exactly what each type returns (cross-source identity spine for company, RxCUI + ingredient/brand for drug), the accepted input formats (ticker, CIK, name), and the resolution behavior (e.g., parent/child ownership for LEI).

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 verb and resource: resolving user-spoken names to canonical identifiers. It distinguishes itself from siblings by specifying it should be used first when a name needs an ID, and by detailing supported entity types (company, drug).

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives clear when-to-use guidance. It also mentions that using resolve_entity replaces 2-3 manual lookups, reinforcing its role as an initial resolver.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds value by explaining that it probes each entity, ranks by score, and returns specific fields (score, confidence, signal density), which goes beyond the annotation-only safety profile.

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

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

The description is three concise sentences with no redundant wording. It front-loads the main action, then adds behavioral detail and output format, earning its place efficiently.

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

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

With no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It covers purpose, process, and output, though it does not mention edge cases or API key requirements, which are covered in 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 baseline is 3. The description does not add nuance to parameters beyond what the schema already includes; it merely describes the process using the parameters. Thus, no additional semantic value is provided.

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

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

The description clearly states the tool's function with the verb 'Compare' and specific resource 'AI visibility across multiple entities side-by-side.' It explicitly mentions probing with ai_visibility_check, distinguishing it from the single-entity sibling tool, and clarifies its competitive comparison purpose.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an illustrative example, and implies it is the multi-entity alternative to ai_visibility_check. However, it does not explicitly state when not to use it or contrast with compare_entities.

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 readOnly/idempotent/non-destructive annotations, the description discloses fan-out behavior, partial failure degradation ('sources_failed will list it if it times out, the rest still returns'), and timing caveat ('first measurement ... can take 5-30s'). This adds meaningful behavioral context.

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

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

Although lengthy, every sentence conveys necessary information: purpose, usage, return fields, ecosystem limits, and failure behavior. The structure is front-loaded with the core purpose and uses separators for clarity.

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 lists all summary fields and explains failure modes, timeout behavior, and ecosystem scope. It is sufficiently complete for an agent to understand what to expect and when to use the tool.

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

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

Schema coverage is 100% and describes both parameters. Description adds no new semantic details beyond what the schema already states, but it does reinforce the default version behavior. Baseline 3 is appropriate.

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

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

Description opens with a specific composite purpose: 'should I add this npm package to my project' check, and details the fan-out across deps.dev and bundlephobia. It clearly indicates the resource (npm package) and the action (scan), distinguishing it from siblings by focusing on dependency metrics.

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

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

Explicit when-to-use guidance is given: 'Use whenever an agent asks ...' plus an explicit exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' steering users to an alternative for non-npm packages.

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, covering the safety profile. The description adds useful behavioral context: it uses Algolia, defaults to 'story' tag when not specified, and lists the return fields (title, URL, score, author, comment count, timestamp). This goes beyond the annotations without contradicting them.

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

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

The description is two sentences that front-load the core purpose, then detail parameters and return fields. Every sentence adds value, and there is no redundant or overly verbose language.

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

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

Given the tool's moderate complexity and that an output schema exists, the description covers the essential aspects: the query, optional tag filtering, and return fields. It does not mention sorting or pagination explicitly, but these are captured in the schema. The combination of annotations and description is sufficient for a functional understanding.

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

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

Schema description coverage is 100% for all three parameters, each already having clear descriptions. The description reinforces the tags parameter by restating the default but does not add new semantic meaning beyond what the schema provides. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states 'Full-text search Hacker News via Algolia', using a specific verb and resource. It distinguishes the tool from siblings like get_stories or get_top_stories, which are retrieval tools for specific story sets, while search_hn is the general search entry point.

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

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

The description implies usage by stating how to construct a query with optional tags, but it does not explicitly mention when to prefer this tool over alternatives like search_within or get_hn_comments. No exclusion criteria or alternative recommendations are provided, leaving usage guidance mostly implicit.

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 the description adds substantial behavioral context beyond that: 200K char cap with truncation and flagging, BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and output format (top-N passages with offsets and similarity scores). 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?

Every sentence earns its place: purpose, examples, use case, sibling integration, and technical details are each covered in a compact five-sentence description. It is front-loaded and dense without being bloated.

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

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

Given the tool's moderate complexity and no output schema, the description covers inputs, usage rationale, output characteristics (offsets, similarity scores), edge-case behavior (truncation), and integration with a sibling tool. It is fully sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples of text inputs ('SEC 10-K body, an article') and query examples, plus clarifying the truncation behavior for the text parameter. This enriches the schema without redundancy.

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

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

The description explicitly states the tool performs 'Semantic search INSIDE a fetched record' with a specific verb and resource, clearly distinguishing it from siblings like search_hn (searches Hacker News) and ask_pipeworx_grounded (grounded Q&A). The scope is unambiguous.

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

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

Provides explicit guidance: 'Use when the record is too big to cram into the prompt' and describes a workflow pairing with ask_pipeworx_grounded. It also explains the benefit of offset-based verification, giving the agent clear decision criteria.

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

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

The description goes well beyond the annotations by specifying the return value (subscription id), auth prerequisites, limitations (anonymous/BYO cannot persist), and delivery behavior including SMS verification and the 10/day cap. It also explains the always-on feed, which is not implied by the annotations. No contradiction with readOnlyHint=false, idempotentHint=true, etc.

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 logically organized by type then delivery. Every sentence contributes useful information, though it could be slightly more scannable with line breaks. It remains appropriately sized for the tool's complexity.

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

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

For a tool with 3 parameters, nested objects, and no output schema, the description covers all necessary context: return value, auth requirement, type examples, delivery behavior, and the persistent feed. The schema fills in webhook details, so the overall tool definition is complete.

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

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

Although the schema already covers all parameters (100% coverage), the description adds concrete examples (e.g., items:["5.02"], topic:"fed", delivery:{email:...}) that aid the agent in constructing valid parameter values. This is value beyond the schema, earning a 4 rather than the baseline 3.

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: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts, which handle listing, removal, and retrieval respectively.

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 on when to use the tool: it requires a Pipeworx OAuth account, lists supported subscription types, and explains delivery channels. However, it does not explicitly state when not to use it or directly reference alternatives, so it falls just short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: returns category-bucketed example questions, includes the exact tool and argument shape, is drawn from the live catalog, and supports optional topic narrowing. 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 front-loaded with natural-language query patterns and densely packs purpose, output, usage, and examples. However, it is one long run-on paragraph with a repetitive list of user phrasings that could be trimmed, keeping it just below a perfect score.

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

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

Despite having no output schema, the description fully covers return content ('category-bucketed example questions... each with the exact tool + argument shape'), invocation behavior, and use case. It is complete for a simple tool with one optional parameter.

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

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

The input schema already documents the optional topic parameter with values and 'omit for cross-category spread' guidance (100% coverage). The description adds examples like 'finance', 'pharma', 'betting' and says 'call with no arguments for full spread', but this largely restates the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('suggest') and resource ('questions'), and clearly positions the tool as the onboarding entry point for learning what Pipeworx can do. It distinguishes itself from sibling meta-tools by explaining that it teaches you how to call ask_pipeworx, entity_profile, and others.

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

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

Explicitly states when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains both no-argument and topic-filtered invocation. It does not explicitly name an alternative for users who already know what they want to ask, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses that ownership is enforced, the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This significantly enhances the agent's understanding of side effects and access control.

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 concise sentences, each adding essential information: what it does, who can do it, and the deactivation behavior. No filler or redundancy.

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

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

With one simple parameter, rich annotations, and a clear description of side effects and constraints, the description is fully adequate for an agent to invoke the tool correctly 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?

The schema already provides 100% coverage for the single parameter, describing it as a UUID returned by subscribe. The tool description adds no further parameter details, so the 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 specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe and list_subscriptions, and the ownership detail adds further specificity.

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

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

The description clearly implies usage for canceling subscriptions and notes ownership constraints. It doesn't explicitly compare to alternatives, but the mention of recent_alerts hints at a rationale for deactivation over deletion, providing usable 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 well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by disclosing nuanced behavior: the distinction between 'could_not_verify' (verification didn't happen, not evidence) and 'unsupported' (searched but no source found), the routing logic, verbatim evidence with citations, and the fact that it judges claims after grounding. This is exactly the kind of context an agent needs to 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 front-loaded with actionable examples, then states purpose, routing logic, return values, and critical caller caveats. Every sentence contributes: the query patterns help pattern-matching, the fast-path vs. grounded explanation clarifies behavior, and the error-semantics note is essential. No redundancy or filler.

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

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

Given this is a complex tool without an output schema, the description fully compensates by explaining the verdict types, the return format (actual value with citation and reasoning), the two verification pipelines, and the exact meaning of 'could_not_verify' vs. 'unsupported.' It also covers the idempotent/read-only nature implicitly through context. The agent has everything needed to invoke this tool safely and interpret its result 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 parameters documented. The description adds valuable semantic context beyond the schema, notably that tolerance_pct 'overrides the tolerance implied by the claim wording' and suggests a specific use case ('set 1–2 for hallucination detection'). This goes beyond the raw schema and gives the agent a clearer mental model of how to use the 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 opens with concrete query examples ('Is it true that…', 'fact check') and immediately states the core purpose: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from sibling tools by describing an end-to-end claim-verification workflow that 'replaces 4–6 sequential calls,' which is a specific verb+resource+scope formulation.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also explains the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for anything else). However, it doesn't explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of a full 5.

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