Congressional Documents

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

Annotations already declare readOnlyHint=true, and the description consistently describes a read-only probe. It adds valuable behavioral context beyond annotations: cost implications ('you pay Anthropic directly'), default model selection, and return shape (per-model {score, confidence, signals, raw_response} + combined view). No contradictions.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds information (purpose, model options/cost, return format, use cases). No filler or repetition of schema details.

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

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

Despite having no output schema, the description explains the return format explicitly. It covers prerequisites (API key), supported models, and use cases, making it complete enough for an agent to select and invoke the tool correctly for a 4-parameter, 1-required-tool. No missing critical information.

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 all four parameters (entity, models, _apiKey, context) are already documented. The description adds marginal semantic value by emphasizing the free default model and cost of Anthropic, but it does not go beyond what the schema and description already convey. 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 uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs' knowledge about a business/brand/product/topic). It distinguishes itself from siblings by focusing on AI visibility scoring rather than general Q&A or research, and mentions the default model and optional Anthropic probing.

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') and prerequisites (default model free, _apiKey needed for Anthropic), but it does not explicitly name alternative tools or state when not to use it. This is clear context without 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 reveals key behavioral traits: it automatically routes to the appropriate source, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a fast single call. This adds substantial context that the annotations alone do not provide, with no contradictions.

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

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

The description is lengthy but well-structured and front-loaded with the core directive 'PREFER OVER WEB SEARCH'. Every sentence adds value: routing details, examples, and alternative tool guidance. It could be slightly trimmed, but its density is justified for a tool with such broad applicability.

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

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

Given the tool's complexity, the absence of an output schema, and the richness of annotations, the description is complete. It covers what the tool does, when to use it, when not to, alternatives, and even notes that it handles breaking news internally. The combination of annotations and description leaves no significant gaps for an agent selecting or invoking the tool.

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

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

The schema already fully documents the single question parameter and its aliases (100% coverage). The description adds meaning by providing concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') and indicating the range of accepted query types, which helps the agent formulate the parameter value effectively.

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 that this tool routes questions to one of 5,322 tools across 1,393 verified sources and returns structured answers with citation URIs. It uses specific verbs like 'routes' and 'returns', and differentiates from siblings by explicitly mentioning alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for a broad range of factual queries, provides examples, and states 'START HERE for most questions'. It also gives explicit when-not-to-use guidance by mentioning 'Step up only when needed' and names the specific alternatives (ask_pipeworx_grounded, 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?

Annotations already cover read-only/idempotent behavior. The description adds valuable context: it is an experimental edge with no fallback, currently matches stable, and candidate routing improvements are live-tested. This goes beyond annotations without contradicting them.

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

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

Three sentences, front-loaded with the core beta status. Some redundancy ('this IS a full working router') but every sentence contributes to understanding the experimental nature and usage context.

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

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

Covers experimental status, current equivalence to stable, usage guidance, and full-fidelity behavior. It does not specify the return value shape, but it points to ask_pipeworx's response shape, which is sufficient for a router with an existing sibling reference.

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

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

Schema coverage is 100% with each parameter described, including aliases for question. The description adds no new parameter-level detail but references 'same arguments', which is acceptable given full schema coverage.

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

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

The description clearly states this is the beta version of ask_pipeworx, identical in function but with experimental routing improvements. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing it is the experimental edge and currently matches ask_pipeworx exactly.

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 it like ask_pipeworx when you want the newest routing. It names the stable alternative and explains that results are compared with ask_pipeworx, but does not explicitly state a when-not-to-use scenario.

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

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

Beyond the read-only annotation, the description details the return structure, refusal reasons, and the strict grounding behavior ('using ONLY what the tool result contains'). It also discloses the extra LLM call cost, adding significant behavioral context without contradicting annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then packing return schema, use cases, and cost trade-off into a compact paragraph. Every sentence contributes unique value.

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

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

With no output schema, the description fully explains the return object, refusal reasons, and error modes. It also covers the tool's routing scope and comparisons with siblings, making it complete for an agent to use correctly.

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

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

The schema covers 100% of parameters with aliases, and the question parameter is well-described. The description adds no new parameter-level details, so it meets the baseline for high schema coverage but does not exceed it.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from ask_pipeworx by emphasizing that answers are extracted only from tool results. It names the sibling tool and explains the routing process, making the purpose unmistakable.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also mentions the additional LLM cost trade-off, giving the agent clear criteria for selection.

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

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

The description discloses extensive behavioral traits beyond the annotations: fan-out logic, resolver confidence levels with short-circuit statuses, closed-market handling, wide-spread warnings, cancellation rule parsing, and news fallback behavior on GDELT 429s. This is far more than the readOnly/openWorld/idempotent hints 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 long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, RESOLUTION-RULE RISK) and front-loads the core purpose in the first sentence. Every sentence carries substantive information for a complex tool, but it could be trimmed slightly without losing critical detail.

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

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

Without an output schema, the description takes on the burden of explaining return shapes and edge cases. It thoroughly covers result.market, result.analysis, result.evidence, resolver contracts, parent_event extraction, and various status codes. Given the tool's complexity, the description is effectively complete for safe agent 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 coverage is 100% and schema descriptions are already clear. The description adds value by elaborating on acceptable market input formats (slug, URL, question text), showing fan-out examples per classifier, and explaining the impact of include_raw and depth parameters. This enriches semantic understanding beyond the schema alone.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool's function, input types, and outputs, and distinguishes it from siblings by focusing on Polymarket-specific research with market-vs-model comparison.

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

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

Explicit 'Use for' guidance is provided: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This gives clear invocation context. However, it doesn't explicitly mention when not to use it or name alternative tools, which would fully complete the guidance given sibling tools like validate_claim and 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 annotations (readOnly, idempotent), the description reveals behaviors: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and return format with citation URIs. It also quantifies efficiency ('replaces 8–15 sequential lookups'), providing rich 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 every sentence contributes value: usage examples, type-specific data details, sorting behavior, return format, and efficiency claims. It is front-loaded with the core purpose and structured for quick 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 comparison tool with two entity types, the description covers both modes, data fields, count limits, fiscal year handling, sorting, and return output. Even without an output schema, the agent can infer what to expect. The completeness is appropriate for the tool's complexity.

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

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

The schema covers parameters, but the description adds substantial meaning: explains what each 'type' value pulls (company financials vs. drug adverse events/trials) and gives concrete examples for 'values' (e.g., tickers, drug names). This goes well beyond the schema's bare 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 concrete query examples and explicitly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sequential lookups and siblings by positioning itself as the preferred way to compare entities.

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

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

Includes a direct usage directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and details the supported comparison types (company, drug) with entity-count limits. It clearly signals when to use this tool and discourages the alternative of multiple single calls.

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, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: account/payment requirements, response structure (findings packet, gaps[], contradictions[]), semantic excerpting behavior, expected latency (15-60s, up to ~90s), and a no-hallucination guarantee ('never invented'). No contradiction with annotations.

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

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

The description is long but information-dense, with an appropriate front-loaded account requirement. It is structured logically, though there is slight redundancy (ask_pipeworx mentioned twice) and some overlap with schema depth descriptions. Still, every sentence serves a purpose.

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

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

With no output schema, the description fully explains expected returns: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. Covers account requirements, alternatives, depth semantics, and performance expectations. Very complete 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 covers 100% of parameters (question, depth), so baseline is 3. The description adds value by explaining depth variants' behavior (gap recovery, lead chasing), giving example questions, and noting that thorough requires a paid plan. This elevates it above baseline, though not to a 5 since some details are already in the schema.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call.' It distinguishes from siblings with explicit contrasts like 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx,' plus concrete example 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?

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also notes the account requirement and tells non-signed-in users to use ask_pipeworx.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, which the description does not contradict. The description adds useful behavioral context: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and notes the results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations and helps the agent understand the tool's output format and usage pattern.

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

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

The description is three sentences long and front-loaded with the core purpose. The list of domains is useful but somewhat lengthy; still, it is concise and every sentence contributes to understanding. It avoids excess and is well-structured.

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

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

Given the tool's role as a discovery meta-tool, the description covers the key aspects: what it returns (top-N tools, schemas, examples), how the output can be used (ready to call directly), and when to use it (first when exploring many options). Without an output schema, the description's explanation of the return format is sufficient. Minor gaps like error handling are not critical for this type of tool.

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

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

The input schema has 100% description coverage, with all parameters (query, q, task, limit, search, description) well-documented. The description reinforces the semantics of the query parameter ('describing the data or task') and mentions the 'top-N' return which relates to the limit parameter. However, it does not add meaningful detail beyond the schema, 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 purpose: 'Find tools by describing the data or task.' It uses specific verbs and a resource ('tools'), and distinguishes itself from siblings by emphasizing discovery, browsing, and searching across many listed domains. The phrase 'Call this FIRST' further differentiates it from tools that answer directly.

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

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

The description provides explicit when-to-use guidance: '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.' It does not explicitly name alternative tools or state when not to use it, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds meaningful context beyond that: it fans out across multiple sources in parallel, returns specific fields, has a soft-fail for the USPTO API, and uses a GDELT→GNews fallback. These behavioral traits help an agent anticipate potential partial results and understand the tool's operational characteristics.

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 clause earns its place. The opening examples are repetitive but serve to catch varied user phrasings. The structured list of output fields is necessary given no output schema. It is front-loaded with usage examples and preferences, making it easy to scan. It could be slightly shorter without losing meaning, but it is far from wasteful.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns: cik, company_name, recent_filings, fundamentals, patents, news, and LEI. It also covers important caveats like the USPTO API sunset, the GDELT→GNews fallback, and input constraints. For a tool of this complexity, this description provides enough context for an agent to select and invoke it correctly and to 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces what the schema already says (ticker or zero-padded CIK, names not supported) with examples like 'AAPL' and '0000320193', but it does not add substantive new meaning beyond the schema's own parameter descriptions. The value is mostly redundant, though the examples and the explicit mention of resolve_entity for names are marginally helpful.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company. It uses specific verbs like 'profile' and 'research' and lists concrete example intents. It distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, which differentiates it from other research tools like deep_research or compare_entities.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER' for holistic company profiles, and even names an alternative: 'use resolve_entity first' if only a name is available. It also specifies acceptable inputs (ticker or CIK) and what to do if the user provides a name, making the decision process very clear for an agent.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context about clearing sensitive data and the conditions for deletion, which goes beyond the annotations, though it doesn't elaborate on error handling or side effects.

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

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

The description is three concise sentences, front-loaded with the action, then usage, then related tools. No fluff or repetition; every sentence adds value.

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

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

The description fully covers the tool's purpose, usage, and relationship to siblings. With a single parameter and no output schema, no further details are necessary. The guidance on sensitive data and pairing with remember/recall makes the description complete.

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

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

Schema coverage is 100% (the key parameter is fully described). The description reiterates that deletion is by key but does not add new semantic meaning beyond the schema, so it meets 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 deletes a memory by key, using a specific verb and resource. It distinguishes itself from siblings like remember and recall by explicitly saying 'delete' and describing the 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?

The description gives explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also points to sibling tools remember and recall, providing context for alternative actions.

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 value by explaining the internal process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond the annotations and clarifies the tool's behavior. It does not mention advanced details like rate limits or error handling, but that is acceptable given the annotation coverage.

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 concise. The first sentence states the purpose, the second explains the process, and the third lists use cases. Every sentence earns its place with no redundancy, making it highly readable and efficient.

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

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

The tool is relatively simple with only two parameters and no output schema. The description compensates by specifying the output as 'a single text blob ready to drop at site-root/llms.txt' and mentioning the standard format. It provides all essential information for an agent to invoke the tool correctly. Minor gaps like handling of invalid URLs or edge cases prevent a perfect score.

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 for both parameters (url and max_links). The description adds little to parameter understanding beyond what the schema states—it does mention 'any URL' and 'key links', which aligns with the schema. Since the schema already carries the burden, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for a given URL. It specifies the verb 'generate', the resource (llms.txt), and the output format (markdown text blob). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on checking AI presence rather than generating the file itself.

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

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

The 'Useful for' section provides explicit use cases: getting a client's site indexed, drafting llms.txt for a project, or auditing how an AI crawler sees a competitor. This gives clear context on when to use the tool. However, it does not mention when not to use it or name alternative tools, 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.

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

The description adds behavioral details beyond annotations: truncation default, paging via offset, and return fields (citation, page range, URL). It doesn't contradict the read-only/idempotent hints and gives useful context about long transcripts.

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

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

Four sentences with each serving a purpose: purpose, usage, return values, truncation caveat. No wasted words, well-front-loaded.

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

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

For a tool with five parameters and no output schema, the description adequately lists what is returned and how to handle large outputs. It might miss error handling or format details, but it's largely complete.

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

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

Schema covers 100% of parameters, but the description enriches understanding by linking package_id/granule_id to search results and explaining why max_chars and offset matter for long hearings. This adds value beyond the schema's basic descriptions.

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

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

The description clearly states the tool reads full text of congressional documents, distinguishes it from search_congressional_documents by focusing on retrieval for quoting, and lists return components. The verb 'Read' and resource 'congressional document' are specific and unambiguous.

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

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

It instructs to pass package_id and optionally granule_id from search_congressional_documents, establishing the workflow. It also explains how to handle truncation for long transcripts, providing practical usage guidance. It doesn't explicitly mention when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context about what the tool reveals: 'what this source does and does not cover', which aligns with the openWorldHint. No contradictions; the added behavioral context is relevant but not extensive.

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

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

The description is two sentences, front-loaded with the verb and resource, then followed by a clear usage directive. Every word earns its place, providing both function and guidance without any 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 parameterless tool with no output schema, the description fully covers what the tool does, what it returns (the list and content descriptions), and the edge of its coverage ('does and does not cover'). It also gives decision-relevant context for when to invoke it, making it complete for the given 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 tool has zero parameters, so the baseline for this dimension is 4. The description mentions no parameter details, but none are needed. The schema is empty, and the description does not need to compensate for missing schema 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 uses the specific verb 'List' and identifies the resource as 'kinds of congressional documents', enumerating examples (hearings, committee reports, etc.). It clearly differentiates this from sibling tools like search_congressional_documents and get_congressional_document_text by focusing on the taxonomy of document types rather than searching or retrieving content.

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: 'Call this when unsure which doc_type answers a question.' This gives a clear trigger condition. However, it does not mention alternatives by name or provide explicit when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by listing the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the default 'active' scope, which is not fully covered by 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, both purposeful: the first states what the tool does and what it returns, the second gives usage context. No redundant wording or filler—every sentence earns its place.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description is fully self-contained. It explains the return fields, the default scope, and when to use it, while annotations cover safety. No significant gaps remain.

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

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

Schema coverage is 100%, and the only parameter (include_inactive) has a full description in the schema. The tool description does not add additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'List' and resource 'the caller's active subscriptions', clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also specifies the exact return fields, leaving no ambiguity about the tool's function.

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

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

Explicit guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly indicates when to use this tool versus adding or removing subscriptions, and it names the alternatives implicitly.

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?

All annotations are false, so the description carries the full burden. It discloses behavioral constraints: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also signals real-world impact ('signal directly affects roadmap') and gives content rules. No contradiction with annotations 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?

Five sentences, each serving a distinct purpose: purpose statement, use-case enumeration, content formatting guidance, team process, and operational constraints. It is front-loaded with the core action and contains no redundant or filler 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?

For a feedback tool with no output schema, the description covers what the tool does, when to use it, how to phrase feedback, and operational limits (rate limiting, quota exemption). The nested context object is self-explanatory via the schema, and the description does not leave any practical ambiguity for an agent.

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

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

The schema already provides 100% coverage with detailed descriptions for every parameter. The description adds value by advising how to structure the message (be specific, 1-2 sentences, describe in terms of tools/packs rather than end-user prompts), which goes beyond the schema's field-level explanations.

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', clearly stating the action (sending feedback) and the target (Pipeworx team). No sibling tool offers a similar feedback channel, so it is easily distinguished from the research and subscription tools.

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

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

Explicitly lists trigger conditions: bug (wrong/stale data), feature/data_gap, and praise. It also provides guidance on what to include (tools/packs, not end-user prompts) and notes the rate limit, giving the agent clear decision criteria for when to invoke 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?

Beyond annotations (read-only, idempotent), the description discloses caching behavior ('Cached 5min-1h depending on window'), data source ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). These are valuable behavioral traits not present in annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It uses numbered use cases for readability, and every sentence adds value (aggregation source, PII, caching). No wasted words.

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

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

For a simple one-parameter read-only tool, the description covers purpose, usage contexts, return contents, data source, privacy, and caching. No output schema exists, but the description explicitly states what is returned ('top tools, top packs, and total call volume'), making it complete.

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

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

The schema already fully describes the only parameter 'window' with enum values, default, and trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description repeats this exact information, adding no new semantic value beyond the structured schema. Baseline 3 applies due to high schema coverage.

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

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

The description clearly states a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes the tool from siblings like discover_tools or ai_visibility_check by focusing on aggregated usage trends of other AI agents.

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 with '(1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice, (3) seeing whether your use case aligns with what most agents need.' It lacks mention of alternatives or when not to use, but the context is clear.

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

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

The description extensively discloses behavior beyond the annotations. It explains internal checks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), what gets filtered (placeholder slugs), and actionable warnings ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it'). The annotations (`readOnlyHint: true`, `destructiveHint: false`) are consistent and the description adds substantial 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 long but well-structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes technical details, though some repetition (e.g., partition_check appears multiple times) makes it slightly less concise than it could be. Overall, it earns its length given the tool's complexity.

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

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

With no output schema, the description clearly states the response structure ('Response: opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)...'), covers edge cases (skipped_low_similarity, placeholder filters), and provides actionable trade guidance. Given the tool's complexity, this is exceptionally complete.

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

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

Although schema description coverage is 100%, the description adds significant semantic detail: `event` triggers a child-market walk with ordering checks and partition-sum computation, `topic` performs cross-event search and flattening, and 'no args' triggers a trending scan—which is not explicitly in the schema. It also clarifies accepted URL formats. This goes well beyond the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (no-arg trending scan, event mode, topic mode) and differentiates from siblings by naming specific alternative tools like `polymarket_fill_risk`.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also gives a recommendation ('event (recommended for a specific market)') and an explicit alternative ('For custom sizing use polymarket_fill_risk'). This is exactly the kind of when-to-use information an agent 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?

The description discloses behavioral traits far beyond the annotations: caching at the KV level with 1h TTL keyed on knobs, the internal model families (crypto_price, news_momentum, partition_overround, etc.), response segmentation, diagnostics for empty results, a 24h-move warning that signals edge may already be priced in, and the note about Fed signals being unreliable without paid data. This is rich, honest transparency about how the tool behaves.

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

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

The description is long but well-structured with clear section markers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It front-loads the core purpose and then dives into necessary detail. While some specifics (like per-sport alpha values) are niche, they serve to precisely communicate the tool's behavior. Every major claim earns its place, and the format aids scanning, though bullet points would have improved 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?

With no output schema, the description takes full responsibility for explaining return values and does so comprehensively: by_segment structure, diagnostics for empty segments, fed_candidates exclusion, and the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers behavioral nuances like the 24h-move warning and cache invalidation. For a tool of this complexity, the description is exceptionally complete.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The tool description adds extra semantic value by explaining the rationale behind the knobs (e.g., 'min_liquidity... Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven') and by clarifying how parameters interact (e.g., min_partition_leg_kelly explanation for partition_overround). This goes beyond what the schema provides, warranting a 4.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and differentiates from siblings like polymarket_arbitrage (which likely focuses on cross-market arbitrage) by emphasizing the Pipeworx disagreement signal. The 'Built for "what should I bet on today"' framing adds concrete use-case context.

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

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

The description provides clear usage context ('what should I bet on today', agents discovering opportunities without paging hundreds of markets) and explains when the tool is appropriate. It also details the tradeable-edge knobs and how to use them, and notes when segments may be empty. However, it does not explicitly compare to sibling tools or state when NOT to use it, so it earns a 4 rather than a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses critical behavioral details: decay is computed on |edge_pp_net|, snapshots are written on cache-miss (so gaps mean no scan), history is limited by a 60-day TTL, and decay is based on daily closes not intraday. This gives a complete picture of how the tool behaves with respect to data freshness and limitations.

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

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

The description is well-structured with clear sections for Args, RESPONSE, and LIMITS. Each sentence provides essential information—including the response schema, edge cases, and limitations—without redundancy or fluff. Despite being longer than typical descriptions, every part earns its place for a tool with this complexity.

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

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

Since there is no output schema, the description takes on the full burden of explaining the response format, which it does thoroughly: tracked[], expired[], and snapshot_dates[] with their fields and meanings. It also covers limitations (TTL, snapshot gaps) and data provenance, making it complete for an agent to understand what to expect and how to 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 schema already provides full coverage for both parameters: days (lookback, default 14, clamp 2-30) and window (24hr | 1wk | 1mo, default 1wk). The description adds a slightly less precise mention of 'max 30' for days but does not introduce new semantics beyond what the schema already states. Thus, it meets the baseline for schema coverage without adding significant value.

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

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

The description clearly states the tool's purpose as 'edge persistence and decay telemetry built from daily polymarket_edges snapshots,' answering a specific question about edge age and shrinkage. This distinguishes it from siblings like polymarket_edges and polymarket_arbitrage by focusing on historical telemetry rather than current edge 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 implies a strong use case: assessing whether an edge is fresh or decaying before trading, using the analogy of fresh vs. 3-week-old edges. It provides clear context on when to use the tool, but does not explicitly name alternative tools or state when not to use it, so it falls short of a perfect 5.

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

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

Annotations already mark it readOnly, idempotent, and non-destructive; the description adds meaningful behavior: it walks the order-book ladder, distinguishes single-market vs basket mode, highlights partial-fill risks, and defines verdict values. This exceeds what annotations convey.

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

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

Although lengthy, it is front-loaded with a one-line summary and then organizes details under REQUIRES, SINGLE-MARKET, BASKET, and USE THIS. Every segment adds operational value for a complex tool; no filler.

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

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

For a 4-param, 2-mode tool with no output schema, the description enumerates return fields, mode contracts, risk warnings, and typical usage contexts. It covers what an agent needs to decide when to call and how to 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?

Schema descriptions already cover all 4 parameters, but the description adds crucial semantics: size_usd meaning differs by mode (spend vs target proceeds vs settlement notional), side defaults differ, and return fields are enumerated per mode. This deepens the agent's understanding beyond the schema alone.

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

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

The description opens with a precise statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It names the resource (Polymarket CLOB fill depth) and clearly differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal 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?

Explicitly specifies mode selection: REQUIRES one of `market` or `event`, and tells the agent to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This gives clear when-to-use and alternative context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description goes far beyond that by disclosing detailed behavior: response format (leg-by-leg prices, spread[]), safety fields (compatibility_warning with two distinct failure cases), temporal alignment semantics, and skipped_cross_type/subtype counters. It also cautions that most pre-mapped topics are not tradeable, which adds critical behavioral context beyond any structured field.

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

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

The description is information-dense and front-loaded with the core purpose. It is structured with clear sections for modes, response fields, and safety warnings. While it is longer than average, each sentence earns its place by explaining behavior or constraints. Minor redundancy exists (e.g., 'same resolving question' appears twice), but overall it is well-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?

Despite lacking an output schema, the description thoroughly explains return values: leg-by-leg prices, spread[], compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases (matched_pairs:0 with and without skipped_cross_type) and explains the meaning of temporal misalignment. For a tool with three optional parameters and no formal output schema, this description is exceptionally complete.

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

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

Schema coverage is 100% with parameter descriptions for topic, kalshi_event_ticker, and polymarket_event_slug. The description adds value by explaining how parameters interact: topic auto-fetches matching events, explicit tickers/slugs override the mapped side, and the distinction between pre-mapped shortcuts and custom pairings. This is more than the schema alone provides, though not exhaustive for every edge case.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (spread between two venues) and the verb (compare/compute), and distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue same-outcome comparisons. The two modes (topic shortcuts vs explicit tickers/slugs) are also clearly outlined.

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

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

The description provides clear context for when to use the tool: when comparing the same question across Kalshi and Polymarket, with explicit mode selection ('TWO MODES'). It also gives important when-not guidance, such as compatibility_warning and temporal_alignment indicating meaningless spreads. However, it does not explicitly name alternative tools for other use cases, so it falls just short of full alternative-based 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 indicate readOnly, idempotent, and non-destructive, and the description adds behavioral context beyond that: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and it has a dual mode—returning a single value or listing all keys when the key argument is omitted. No contradictions.

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

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

Three sentences, front-loaded with the main action, with each sentence adding distinct value: function, usage examples, and scoping/pairing. 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 the tool's simplicity (one optional parameter, no output schema), the description covers retrieval, listing, scoping, and related tools. It doesn't specify return format or error behavior, but for a memory lookup the implied return (the stored value or list of keys) is clear enough; this is a minor gap.

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

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

The schema already covers the single `key` parameter with 100% coverage, including the omit-to-list behavior. The description reinforces this and adds semantic examples of stored content (target ticker, address, research notes) and scoping implications, enriching the parameter's meaning.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes the tool from its siblings (remember, forget) and states exactly what it does.

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

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

The description explicitly says 'Use to look up context the agent stored earlier' and gives concrete examples (ticker, address, research notes). It also names the paired tools: 'Pair with remember to save, forget to delete,' providing clear when-to-use and when-not-to-use guidance.

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

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

The description contradicts the annotations: readOnlyHint=true implies no state-changing operations, but the text describes mark_read:true as flagging returned events read so subsequent calls show newer ones—a clear state mutation. This is an annotation contradiction, so the score is 1 regardless of other disclosed behaviors.

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?

Five sentences, each contributing unique information: purpose, return payload, filtering, mark_read effect, and alternative feed location. There is no redundant wording, and the key purpose 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?

With no output schema, the description compensates by detailing the returned event fields (source, citation_uri, raw payload). It also covers filtering, mark_read behavior, polling suitability, and an alternative access method. The missing unread_only explanation is adequately handled by the schema, so the description is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a concrete type example ('sec_8k'), specifies ISO timestamp format, and explains the consequence of mark_read (next call only shows newer events), which is extra semantic value beyond the schema's descriptions.

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

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

The description opens with a specific verb and resource ('Pull fired events from your subscription feed'), clearly distinguishing it from siblings like list_subscriptions or recent_changes. It also enumerates return payload contents, making the tool's function unambiguous.

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

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

The description provides clear usage context: filtering by type and since, setting mark_read to control future calls, and an explicit note that polling is fine. It also offers an alternative endpoint for scripts/dashboards, effectively giving 'when to use' guidance without explicitly naming alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds meaningful behavioral context beyond that: it discloses the fan-out to SEC EDGAR, GDELT→GNews fallback, the USPTO soft-fail due to PatentsView API sunset, and the structured return format (changes[] grouped by source, total_changes, pipeworx:// URIs). This goes well beyond the annotations, though it does not fully discuss rate limits or latency beyond the GNews fallback trigger.

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

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

The description is information-dense but every sentence contributes: user-intent triggers, source fan-out and fallback, parameter syntax, return format, and a clear alternative. It is slightly long but well-organized and front-loaded. It earns a 4 rather than 5 because the source details and fallback logic could be trimmed without losing essential guidance.

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

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

Despite having no output schema, the description explicitly states what is returned ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers all three upstream sources, fallback behavior, the `since` format, and the entity_profile alternative. For a complex tool with multiple data sources and no output schema, this description is highly complete.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description reinforces the `since` syntax with ISO and relative shorthand examples and notes that `value` can be a ticker or CIK, but these facts are already in the schema descriptions. The main added value is how parameters influence the fan-out behavior, which is more behavioral than parameter-specific.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y') and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly identifies the resource (a company's recent changes) and distinguishes itself from sibling entity_profile by explicitly naming the alternative for static profiles.

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

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

The description provides explicit when-to-use guidance through natural language triggers and even tells the user to 'Use entity_profile instead when you want the static profile' regardless of window. It also clarifies the `since` parameter's accepted formats with examples, making context-of-use unambiguous.

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

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

The description adds valuable behavioral context beyond annotations: memory is scoped by user identifier, authenticated users get persistent memory, and anonymous sessions retain for 24 hours. Annotations already declare it's a non-destructive, idempotent write, and the description aligns 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 succinct and well-structured: first sentence states purpose, second gives usage guidance, third explains storage mechanics, fourth covers persistence and companion tools. Every sentence earns its place without redundancy.

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

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

For a simple two-parameter tool with full schema and annotations, the description covers purpose, usage, persistence, and pairing with siblings. There is no output schema, but as a write-only operation, that is not a gap. Overall, 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?

With 100% schema coverage, the baseline is 3. The description's examples (ticker, address, preference) closely mirror the schema's key examples, adding little beyond what's already in the parameter descriptions. The only additional context is the key-value storage model, which is more about tool behavior than 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 clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later.' It distinguishes itself from siblings by mentioning pairing with recall and forget, making it unmistakably the memory-write tool.

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

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

It explicitly says 'Use when you discover something worth carrying forward' and lists concrete use-cases (ticker, address, preference, research subject). It names complementary tools recall and forget, but lacks an explicit 'when not to use' statement, so it earns a 4 rather than a 5.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description adds valuable behavioral detail: it cascades through multiple lookup endpoints, auto-disambiguates input, and returns citation URIs. It also specifies data sources (SEC EDGAR, RxNorm) and the exact fields returned, which helps set expectations.

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

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

The description is well-structured, starting with relatable query examples, then the core purpose, usage guidance, and detailed type breakdown. Each sentence adds value, and the formatting with labeled types makes it easy to scan.

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

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

With no output schema, the description compensates by listing exact return fields for each type. It also explains the internal cascading behavior and that it replaces manual lookups. It could mention failure modes or what happens when no match is found, but for a two-parameter tool with good annotations, it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the parameter semantics with examples and notes auto-disambiguation, but it does not significantly add beyond what the schema already documents for 'type' and 'value'.

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

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

The description explicitly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific example phrasings and details the two supported types (company, drug), making it clear what resource it acts on and distinguishing it from sibling tools that likely consume these identifiers.

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

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

It provides clear guidance: 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use (if you already have the ID) and explains that it replaces multiple manual lookups. However, it does not explicitly name alternative tools or state exclusions beyond the implied one.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds behavioral context by explaining the process (probes each entity with ai_visibility_check) and the output structure (ranked list with score, confidence, signal density). 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 are front-loaded with the main purpose, then detail the process, use case, and output. Every sentence earns its place with no wasted words.

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

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

The tool has no output schema, so the description's mention of the returned ranked list with score, confidence, and signal density is valuable. It covers purpose, process, output, and a concrete use case, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for all four parameters. The description does not add parameter-specific details beyond what the schema provides; it only alludes to entities as 'your brand + N competitors,' which is already stated in the schema. Therefore, the description adds no extra meaning to 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 tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb and resource, and distinguishes itself from sibling tools like ai_visibility_check by describing the multi-entity comparison and ranking process. The example use case reinforces the 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: 'Useful for competitive AI-marketing audits: 'does Claude know about us as well as our competitors?'' This indicates when to use the tool. However, it does not explicitly mention when not to use it or name alternatives like compare_entities, though referencing ai_visibility_check as the underlying probe implies single-entity use cases are covered by that tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral traits: it is a composite of two external services, returns a specific summary block plus advisory details and links, handles partial failures gracefully (with a 5-30s timeout on bundlephobia's first measurement), and reports failures via 'sources_failed'. It also states the NPM-only v1 scope, providing important context not available from annotations or schema.

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

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

The description is well-organized and front-loaded with the core purpose, followed by usage, return value details, ecosystem scope, and failure behavior. Each sentence provides necessary information, but it is longer than the minimal viable version—five sentences with many specifics. While every sentence earns its place, a 4 reflects that it could be slightly tightened without losing critical content.

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

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

Given the tool's complexity (composite of two services, no output schema), the description is highly complete. It explicitly enumerates the return fields, mentions per-advisory detail and links, explains the partial-failure mode, and notes the NPM-only restriction. The agent has all necessary context to know what the tool does, what it returns, and what to expect in edge cases.

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 clear descriptions for both parameters (package name, version with default behavior) and has 100% coverage. The description does not add significant new parameter semantics beyond what the schema states; it reinforces that the package should be an npm package and version defaults to latest, but these are already in the schema. Thus the baseline of 3 is appropriate, as the schema does the heavy lifting.

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

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

The description clearly states it is a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It explicitly names the specific resources (npm package, deps.dev, bundlephobia) and the output summary, distinguishing it from any sibling tools. The verb 'scan' and the detailed scope make the purpose unmistakable.

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

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

The description gives explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states the ecosystem limitation and directs other ecosystems to a different tool ('deps.dev:version directly'). This is a clear when-to-use and when-not-to-use guide with an alternative named.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, and the description adds meaningful context: it returns citations, dates, congress numbers, and govinfo links, and it cautions about publishing delays and interpretation of named persons. No contradictions with annotations.

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

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

The description is reasonably concise and structured: it opens with the primary action, then gives usage examples, return info, and caveats in separate sentences. Each sentence adds value, though it is somewhat longer than the two-sentence ideal and could tighten the redundant 'congressional' phrasing.

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

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

Given 7 parameters, no output schema, and good annotations, the description covers the key aspects: what it searches, what it returns, how to proceed to full text, and important caveats about publication delays and interpretation. It lacks explicit rate-limit or auth details, but the schema documents the API key and annotations cover safety, making this adequate for a search tool.

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

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

The input schema already provides 100% description coverage for all parameters, so the baseline is 3. The description adds minimal parameter-level detail beyond the schema—it mentions document types in the intro but does not elaborate on query syntax, date formats, or the _apiKey parameter, leaving the schema to carry the load.

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 searches the full text of official U.S. congressional documents and enumerates the specific document types (hearing transcripts, committee reports, etc.). It distinguishes itself from sibling tools by explicitly directing users to get_congressional_document_text for reading the actual wording.

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-case examples ('what was said in the congressional hearing about X') and warns that it only searches published documents, which implies when not to expect transcripts. It also points to the companion tool for reading full text, offering clear workflow guidance, though it does not explicitly list alternatives for other search scenarios.

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

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

Annotations already declare readOnly/idempotent/destructive hints, but the description adds deeper behavioral specifics: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K character cap with truncation and flagging, and that returned passages carry offsets and scores. This goes well beyond annotation metadata.

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 with a distinct role: the first defines the operation, the second gives the use case and benefits, the third adds technical constraints. Front-loaded with the core purpose, no redundant phrases, and every sentence contributes to agent 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?

Given no output schema, the description still explains return content (passages with offsets and similarity scores), covers parameter constraints, gives usage guidance, and discloses edge cases (truncation and flagging). This fully equips an agent to invoke the tool correctly without further documentation.

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

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

Schema coverage is 100% for all 3 parameters, but the description adds practical examples for the query ('supply-chain risk', 'fiscal year 2024 revenue') and clarifies the meaning of limit through 'top-N passages.' It also reinforces the text parameter with a concrete example (SEC 10-K body). While the schema covers basics, the description enriches usage context.

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

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

The description clearly states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It explains the inputs (text + natural-language query) and the outputs (top-N passages with offsets and scores), and differentiates from siblings by explicitly pairing with ask_pipeworx_grounded for grounding over relevant passages.

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

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

It gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names an alternative (ask_pipeworx_grounded) and explains the workflow ('fetch with the gateway, ground over the relevant passages instead of the whole document'). This provides clear direction on selecting 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 set readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral context: account-level constraints, SMS verification and cap, webhook HMAC signing, one-time secret return, and auto-disabling after 10 consecutive failures. This goes far beyond the structured annotations and provides crucial operational knowledge.

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 dense with information—every sentence covers a necessary aspect (purpose, auth, types, delivery channels). It is front-loaded with the core purpose and uses compact dash-separated examples. A minor deduction for verbosity; it could be tightened without losing critical details.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description compensates well by stating the return value ('new subscription id'), how to consume the feed, OAuth requirement, and delivery constraints. It effectively covers the full lifecycle of creating and using a subscription, leaving minimal gaps.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and examples (e.g., sec_8k items, polymarket_edge topic). The tool description largely echoes these examples without adding new parameter-level semantics. The only added value is the OAuth requirement, which is not parameter-specific. Baseline of 3 is appropriate when schema fully covers 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the tool's function, distinguishes it from siblings like list_subscriptions/unsubscribe, and even mentions the return value ('Returns the new subscription id'). This is unambiguous and differentiates from related tools.

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

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

The description provides explicit prerequisites ('Requires a Pipeworx OAuth account') and exclusions ('anonymous + BYO cannot persist subscriptions'). It also details delivery channel requirements (e.g., phone verified at /account, 10/day cap). However, it does not explicitly name alternative tools for similar actions, though siblings make the use case clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful behavior: it returns category-bucketed example questions with the exact tool + argument shape, drawn from a live catalog of thousands of tools. This helps set expectations for the output beyond 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 long but front-loaded with example queries and each clause contributes information: purpose, return shape, call modes, and usage timing. It does not repeat schema or annotation content. It could be slightly tightened, but there is no waste.

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

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

For a tool with a single optional parameter and no output schema, the description is remarkably complete: it explains what the response contains (category-bucketed questions with tool/argument shapes), how to call it (no args or topic), and when to use it (first when onboarding). No significant gaps remain.

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

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

The schema covers the single optional parameter (topic) with a description and allowed examples, so baseline is 3. The description adds value by providing concrete examples ("finance", "pharma", "betting") and clarifying the omission behavior ("full spread"), which enriches the semantic of 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 explicitly identifies the tool as "the onboarding entry point for an agent that just connected" and lists example queries users might type. It clearly differentiates from siblings by positioning itself as a guide to discovering what questions to ask, and even names the meta-tools it teaches (ask_pipeworx, entity_profile, compare_entities).

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

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

The description gives explicit when-to-use guidance: "Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools." It also explains call variants (no args vs. topic) but does not mention when not to use it or explicitly name alternatives like discover_tools, though the "FIRST" framing implies precedence.

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

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

The description goes beyond the annotations by disclosing that the row is deactivated not deleted, that ownership is enforced, and that historical events remain accessible via recent_alerts. This provides meaningful behavioral context that annotations alone (readOnlyHint, destructiveHint, idempotentHint) do not fully convey.

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

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

The description is two sentences, front-loaded with the core action ('Cancel a subscription by id'), and each subsequent clause adds valuable context about ownership and deactivation. There is no redundancy or filler.

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

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

For a simple one-parameter tool, the description covers the action, ownership constraint, the non-destructive nature, and the linkage to recent_alerts for historical data. Annotations provide additional safety and idempotency details, making the tool well-specified even without an output schema.

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

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

The input schema already fully describes the parameter ('Subscription id (uuid) returned by subscribe') with 100% coverage. The description's mention of 'by id' adds no additional semantic value beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription') and clearly identifies the action by id. It distinguishes this tool from siblings like subscribe (create) and list_subscriptions (list). The additional detail about deactivation vs deletion further clarifies its unique function.

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

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

The description provides clear context: it's for canceling a subscription, and it explicitly states a when-not through ownership enforcement ('you can only cancel your own subscriptions'). It also notes that historical events remain available via recent_alerts, which suggests an alternative for viewing history. However, it does not explicitly name alternative tools for other operations, so it stops short of full 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: the routing logic (structured vs grounded), the set of possible verdicts, the use of pipeworx:// citations, and tolerance_pct behavior. It does not overpromise or 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 longer than average but well-structured: it opens with trigger phrases, states the main use, details routing, and concludes with return-value summary. Every sentence provides useful information. Slight verbosity is justified given the tool's complexity and the absence of an output schema.

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 enumerates return components (verdict types, actual value, citation, reasoning) and explains the two execution paths. It covers the main scenarios a user would ask about. It could add edge-case handling details, but the given information is sufficient for an agent to invoke the tool confidently.

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

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

The input schema already covers both parameters (claim and tolerance_pct) with descriptive text. The description adds extra value by explaining how tolerance_pct interacts with claim wording and recommending '1–2 for hallucination detection', which is not in the schema. Claim examples are also 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 explicitly states this is a claim-verification tool: 'natural-language claim verification against authoritative sources', with trigger phrases like 'fact check' and 'verify the claim'. It distinguishes from generic search tools by explaining the two pipelines (SEC EDGAR fast path vs grounded pipeline) and the expected output (verdict, evidence, citation).

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates claim types (company-financial vs any other) and explains the routing behavior. Additionally, it frames the tool as replacing 4–6 sequential calls, guiding the agent to prefer this over manual orchestration.

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