Committee Releases

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

Given that annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral context: the default free model, the BYO-key requirement with direct payment to Anthropic, and the exact return structure (per-model score, confidence, signals, raw_response plus a combined view). This goes well beyond the structured annotations.

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

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

Three sentences, all information-dense: purpose+output, default model/key/cost, return format, and applicable use cases. No filler or redundancy; the most important information is front-loaded.

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

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

Despite having no output schema, the description explicitly enumerates the return fields (score, confidence, signals, raw_response, combined view), making the tool's behavior fully predictable. It also covers defaults, authentication, and cost in a compact way, which is complete for low-to-moderate 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 description coverage is 100%, so the schema already documents all four parameters and their allowed values. The description adds cost context and default behavior but does not clarify parameter syntax beyond what the schema provides. This matches the baseline for 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 opens with a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the output: a visibility score (0-100) per model. It distinguishes itself from siblings like ask_pipeworx by focusing on scored visibility across multiple models rather than simple Q&A.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also gives concrete guidance on defaults and when to pass `_apiKey`. It does not explicitly contrast with sibling tools like scan_competitor_ai_presence, so it misses the highest bar for alternative 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?

The description goes beyond annotations by disclosing that it routes questions, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier. This adds meaningful behavioral context beyond the readOnly/openWorld hints, and it does not contradict any annotations.

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

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

The description is long but well-structured and front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH'). Every sentence adds value—scoping, examples, alternatives, and special cases—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 broad question-answering tool with no output schema, the description is exceptionally complete: it covers purpose, usage scope, examples, alternatives, output format (citation URIs), and performance characteristics. This fully equips 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%, so the schema already fully documents the 'question' parameter and its aliases. The description adds examples of questions but no new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions with authoritative structured data from 5,322 tools across 1,393 sources, and explicitly distinguishes it from web search and siblings like ask_pipeworx_grounded and deep_research. The verb 'routes' and resource scope make the purpose unambiguous.

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

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

Explicit guidance is given: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specific trigger phrases ('what is', 'look up', 'find', etc.). It also names alternatives and when to step up, e.g., 'ask_pipeworx_grounded' for hallucination-resistant answers and 'deep_research' for multi-part questions.

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 the beta/experimental nature, the live enablement of candidate routing improvements, the current inactive state, and the comparison against the stable router. It also clarifies that it falls back to nothing and is a full working router. This goes beyond the annotations (read-only, open-world, idempotent) with valuable 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?

Four sentences, each providing distinct value: beta identification, current status, usage instruction, and clarification of functionality. No wasted words, front-loaded with the most important information.

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

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

For a router tool with rich annotations and full schema coverage, the description is complete. It explains the beta purpose, how to use it, the current experimental state, and the comparison process. No output schema exists, but the description correctly notes the same response shape as stable, which suffices.

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 all parameters with descriptions, including aliases for question. The description adds no new parameter information beyond saying 'same arguments' as the stable version, which is redundant given the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,322 tools and response shape. It distinguishes itself from the stable sibling by noting candidate routing improvements, and the purpose is unambiguous: ask questions via a router.

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 to use it 'exactly like ask_pipeworx when you want the newest routing,' which gives clear usage context and implies the alternative (stable router). It doesn't explicitly state when not to use it, but the beta status and comparison to stable provide sufficient guidance.

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

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

Beyond annotations (readOnly, idempotent), the description reveals critical behaviors: returns structured refusal reasons ('not_in_source', 'no_tool_match', etc.), extracts answers only from tool results, and incurs an extra LLM call. This adds substantial context over the annotations alone, enhancing trust and predictability.

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

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

The description is dense yet well-organized, with every sentence conveying essential information: mode definition, routing process, output format, refusal reasons, use cases, and cost trade-off. No redundant or filler content; length is justified by the tool's complexity.

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

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

Given no output schema, the description thoroughly explains return values on success and failure, enumerates all refusal reasons, and situates the tool within its sibling ecosystem. It also covers edge cases (data truncated, tool error), making it highly complete for an agent to invoke correctly.

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

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

Schema coverage is 100%: all six parameters are aliases for 'question' and each has a description. The description adds no additional parameter-specific meaning beyond what the schema already provides, such as formatting or constraints. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description states a clear, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads' with a defined process (routing, fetching, extracting from tool result). It differentiates from sibling 'ask_pipeworx' by emphasizing grounded extraction and refusal behavior, making it unmistakable which tool to use.

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

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

Explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial, legal, medical). Also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost differential, providing strong decision support.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral traits: resolver match confidence with suggestions[], the parent_event extractor, news fallback errors (_fallback_attempted, retry_after_sec), low-confidence short-circuiting, market_closed_or_inactive handling, illiquid wide-spread tradeability, and resolution-rule risk (cancellation_rule parsing). This is far more than annotations provide and no contradictions exist.

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-organized with ALL-CAPS section headers (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and front-loads the core purpose in the first sentence. Each section earns its place for this complex tool, though it could be trimmed slightly without losing critical information.

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

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

Given no output schema, the description thoroughly explains response shapes (result.market, result.analysis, result.evidence), resolver contracts (market_match_confidence, alternatives, suggestions), safety short-circuits, and resolution-rule risk. It even provides concrete fan-out examples per classifier. This is complete for an agent to use 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?

The input schema already covers 100% of parameters, so baseline is 3. The description adds value by explaining parameter trade-offs: 'depth' (quick vs thorough fan-out), 'include_raw' (response size control, 20KB vs 50-500KB), and 'market' accepting slug/URL/question text with examples. It also reveals how the market input influences fan-out, which is not in the schema.

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

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

The description opens with a clear, specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from siblings by emphasizing the single-call fan-out to category-specific data packs and market-vs-model comparison, which is unique among the listed research tools.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke the tool. However, it does not explicitly name alternatives or exclusion criteria (e.g., 'don't use for general questions; use ask_pipeworx instead'), so it falls short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description details behavior: for 'company', it pulls latest 10-K revenue/net income/cash/long-term debt from SEC EDGAR/XBRL, correctly handles off-calendar fiscal years, and for 'drug' pulls FAERS adverse-event counts, FDA approvals, and trial counts. It also explains sorting by primary metric and returns paired data with citation URIs, adding substantial context beyond the annotations.

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

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

The description is longer than average but every sentence contributes value: examples, data source details, fiscal year handling, sorting behavior, output format, and performance benefit. It is front-loaded with purpose, though slightly dense, but not 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 tool's complexity with two entity types, specific data sources, sorting, and output, the description covers all essential context: what data is pulled, how results are sorted, what the output includes (paired data + citation URIs), and even handles edge cases like off-calendar fiscal years. No output schema exists, but the description sufficiently explains return values.

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 covers 100% of parameters, the description adds meaningful semantics: it explains that 'type' determines the data source (company vs drug) and that 'values' are tickers/CIKs or drug names, plus elaborates on the min/max constraint implicitly. This significantly enhances understanding beyond the schema's terse 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 a specific action: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example phrasings ('X vs Y', 'rank these companies') and explicitly differentiates from single-entity lookups by saying 'ALWAYS PREFER over sequential single-pack lookups', making it distinct from siblings like entity_profile.

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

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

The description explicitly states when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains the alternatives context by saying it 'Replaces 8–15 sequential lookups,' giving clear guidance on using this instead of performing multiple individual lookups.

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 substantial behavioral context beyond the annotations: account requirements, paid tier for 'thorough', the fact that it is NOT open-web search, the gap[]-and-never-invent guarantee, second-hop iteration behavior, contradiction[] scans, semantic excerpting, and expected latency. This richly discloses what the agent should expect and is fully consistent with the readOnly/openWorld/idempotent hints.

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

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

The description is dense and every sentence adds important value, which is justified for such a complex tool. However, it is a long wall of text starting with account requirements rather than a punchy front-loaded summary, making it less immediately accessible. Still, no sentence is wasted, so it earns a 4.

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

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

With no output schema, the description must explain return values, and it does comprehensively: findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites, alternatives, depth differences, and performance expectations, making the tool fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds meaningful value by explaining depth variants in narrative form (quick/standard/thorough, gap recovery, lead chasing, contradictions[]) and giving expected timing, which goes beyond the schema. The 'question' parameter is already well described in the schema, so extra description is limited but the depth semantics are enriched enough to warrant a 4.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call' and explains the decomposition-and-routing approach. It also distinguishes itself from sibling tools like ask_pipeworx by explicitly noting this is not for single lookups or breaking news, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance (broad/multi-part questions over structured data) and when-not-to-use guidance ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also provides a fallback based on signed-in status, which is practical and clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. Description adds valuable behavioral context by specifying the return structure: names, descriptions, full input schemas with examples, and that results are ready to call without a second lookup. This goes beyond annotations.

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

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

The description is a bit long but well-structured: purpose, use case, domain list, return behavior, and a strong 'call this FIRST' directive. Every sentence contributes, though the domain enumeration could be slightly trimmed without losing meaning.

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

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

No output schema exists, but the description explains what is returned (top-N tools with names, descriptions, and full input schemas) and how to use the results. For a simple discovery tool with rich annotations and schema, this is sufficient.

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

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

Schema coverage is 100% and the schema already documents the query parameter with examples and aliases. The description adds no new parameter-level detail; it only restates the concept. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

Description opens with 'Find tools by describing the data or task' — a specific verb+resource that clearly distinguishes this discovery tool from sibling data-access tools. It enumerates the domains it covers, 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?

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. This provides clear when-to-use guidance and implicitly indicates it is for tool discovery rather than direct task execution.

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

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

Beyond the readOnly/idempotent annotations, the description discloses material behavioral traits: it fans out across multiple sources, returns specific fields, and calls out the USPTO PatentsView API sunset May 2025 with a soft-fail behavior, plus GDELT→GNews fallback. These are not visible in annotations and are essential for setting 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 dense but well-structured: it front-loads with examples, then states the core value proposition, then lists return fields and limitations. Some redundancy exists (e.g., name unsupported appears in both parameter description and the body), but every sentence contributes actionable information for a complex tool.

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

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

Given no output schema, the description compensates by explicitly listing returned fields (CIK, company_name, recent_filings, fundamentals, patents, news, LEI) and their sources. It also mentions relevant limitations, fallbacks, and the required input forms, making the tool fully usable by an agent without needing additional lookups.

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 both parameters at 100%. The description adds value by giving concrete examples ("AAPL", "0000320193"), restating the name-unsupported constraint, and directing users to resolve_entity when only a name is available. This is meaningfully beyond the schema's field 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 example queries and immediately states "full cross-source profile of a US public company in ONE parallel call," making the action and resource unequivocal. It clearly distinguishes itself from chaining individual lookups and from resolve_entity, which handles names.

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

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

Explicit usage guidance is provided: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view" and "names not supported (use resolve_entity first if you only have a name)." This gives both when-to-use and when-not-to-use with a named alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds minimal behavioral context beyond restating deletion, such as clarifying the memory was 'saved earlier' by the agent, but it doesn't disclose additional side effects like irreversibility (covered by annotations) or error handling. Since annotations carry the safety profile, a mid-range score is appropriate.

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: the first front-loads the core action, the second provides usage context and sibling relationships. No wasted words or redundant 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 it's a one-parameter tool with robust annotations and no output schema, the description covers the purpose, usage timing, and related tools sufficiently. It doesn't address missing-key behavior, but annotations and schema make the destructive and required nature clear, so the gap is minor.

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 'Memory key to delete.' The description adds meaningful context by specifying the key must be from a 'previously stored' memory and advising pairing with remember and recall, which helps the agent understand the key's provenance. This exceeds the basic schema baseline.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly differentiating from sibling tools like remember (store) and recall (retrieve). It leaves 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?

It explicitly states when to use ('when context is stale, the task is done, or you want to clear sensitive data') and references companion tools ('Pair with remember and recall'), providing excellent alternative guidance. This meets the highest bar.

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 exceeds the annotation hints (readOnly, idempotent) by explaining the actual process: fetches the page, extracts title/description/key links, and emits markdown. It also discloses the output as a single text blob, which is valuable beyond the structured annotations.

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

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

The description is well-structured and front-loaded: it states the core function first, then the process, output, and use cases. Each sentence adds distinct value without redundancy, making it appropriately concise for the information conveyed.

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 simple tool (2 params, no output schema), the description is fully complete: it explains what it does, how it works, the output format, and common use cases. No critical context is missing 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?

The input schema already covers both parameters (url, max_links) with clear descriptions at 100% coverage. The description adds no extra parameter-level 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 generates a production-ready llms.txt file for any URL, naming specific AI crawlers and the output format. It uses a specific verb ('generate') and resource ('llms.txt file'), making it distinct from sibling tools like ai_visibility_check.

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

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

The description provides clear use cases ('getting a client's site indexed by AI,' 'drafting llms.txt for your own project,' 'auditing how an AI crawler would see a competitor'). It lacks explicit exclusions or alternative tool mentions, but the context is sufficient 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?

While annotations already indicate read-only, idempotent, non-destructive behavior, the description adds crucial limitations: PDF text is NOT extracted, attachments are returned as links with URLs and sizes. This tells the agent exactly what it can and cannot do with the returned data, going beyond the annotations.

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

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

The description is three concise sentences, with the primary function front-loaded in the first sentence. Every sentence carries useful information: what it reads, how to pass the URL, and the PDF caveat.

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

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

Given there is no output schema, the description explicitly enumerates the return fields (headline, publication date, text, attachments with URLs and sizes) and the PDF limitation. With only one parameter and a clear usage flow, the description provides sufficient context to use 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?

The schema's single parameter 'url' already has a thorough description ('Full committee document URL, as returned by search_committee_documents'), and the tool description repeats this guidance. Since coverage is 100%, the description adds little new semantic value for 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 uses a specific verb ('Read') and names the exact resource ('committee document page'), listing the fields it returns (headline, publication date, text, attachments). This clearly differentiates it from search_committee_documents and other sibling tools.

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

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

The instruction 'Pass a url from search_committee_documents' clearly states when to use this tool – after obtaining a URL via search. It also provides an important usage caveat: PDF text is not extracted, so the agent should quote page text and cite attachment URLs rather than claim to have read PDFs. However, it does not explicitly name alternative tools or exclusionary conditions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds value by noting the tool reveals 'what this source does and does not cover,' giving scope beyond the annotation hints.

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

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

The description is two sentences, front-loaded with purpose and followed by actionable usage guidance. Every word earns its place, with no redundancy or fluff.

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

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

For a simple zero-parameter tool with strong annotations, the description is complete: it states the content, coverage, and when to call. It doesn't describe return format, but given the tool's simplicity and lack of output schema, 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?

With zero parameters, schema coverage is 100% and the baseline is 4. The description correctly focuses on output semantics (listing committees/document types) rather than parameter details, which are absent.

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

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

The description clearly states the tool lists congressional committees, document types per committee, and coverage scope. It uses a specific verb ('List') and resource ('committees/document types'), distinguishing it from sibling tools like get_committee_document or search_committee_documents.

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 instructs 'Call when unsure which committee or doc_type answers a question,' providing a clear when-to-use condition. However, it does not contrast with alternatives or state when not to use it, so it lacks explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about scoping to the caller and the specific return fields, which 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?

Two concise sentences front-load the main action and return fields, followed by actionable usage guidance. Every word earns its place with no redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description provides all essential context: what it returns, default scope, and when to use it. Annotations cover safety, making this 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 the include_inactive parameter well-documented. The description does not add extra parameter semantics, but since the schema fully explains it, 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 uses a specific verb 'List' with a clear resource ('the caller's active subscriptions') and enumerates the returned fields. This clearly distinguishes it from sibling tools like subscribe and unsubscribe, which perform mutations.

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

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

Explicitly states when to use the tool: 'before adding more' subscriptions or 'to find an id to cancel'. This implies the alternatives (subscribe/unsubscribe) and gives clear context 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?

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost/quota implications ('Free; doesn't count against your tool-call quota'), and human impact ('The team reads digests daily and signal directly affects roadmap'). These behavioral traits go well beyond the schema and annotations, giving the agent a complete picture.

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 fits in five sentences, each earning its place: purpose, when-to-use, how-to-write, human impact, and rate limits. It is front-loaded with the core purpose and never repeats schema content. Despite being slightly longer than typical, every clause contributes critical information, making it lean and well-structured.

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

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

For a feedback submission tool, the description is complete: it explains purpose, usage triggers, message format, context guidance, and constraints. The schema fully documents all parameters, and no output schema exists (likely a simple ack). The description leaves no unanswered questions for an agent deciding whether and how to invoke this 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, so baseline is 3. The description adds extra semantic value by explaining how to use the context object ('Describe the issue in terms of Pipeworx tools/packs') and what to avoid ('don't paste the end-user's prompt'). It reinforces the enum meanings with concrete scenarios, surpassing 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from all siblings (which are research, search, or subscription tools) by focusing on feedback submission. It also enumerates feedback categories (bug, feature, data_gap, praise), leaving no ambiguity about the tool's 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 explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a negative guideline ('don't paste the end-user's prompt') and explains how to frame the feedback in terms of Pipeworx tools/packs. This is exemplary usage guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial value by explaining it aggregates usage without PII, includes only (pack, tool, count), and is cached for 5min-1h depending on the window.

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 dense sentences cover purpose, use cases, data provenance, and caching. The structure front-loads the core function and then adds context efficiently 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?

With no output schema, the description does a solid job explaining what is returned (top tools, packs, volume, count) and the caching behavior. Precise output format is not specified, but the tool is simple enough that 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 fully documents the only parameter 'window' with enum values and guidance. The description restates the window choices but does not add new parameter-level detail beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume over configurable windows, and frames it as an aggregated signal of AI agent usage. It distinguishes itself from siblings by emphasizing self-aggregated analytics rather than search or retrieval.

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

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

Three concrete use cases are provided, making when to use the tool explicit. The short vs long window interpretation is also covered, but alternative tools are not named and there is no explicit 'when not to use' guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive safety. The description adds critical behavioral nuances beyond that: fill-check pricing against live order book, the 'do not trade it' rule when realizable_edge_pp <= 0, partition placeholder filtering, and Jaccard similarity anchoring. This gives the agent actionable insight into edge cases and failure modes.

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 it uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose and modes. Some redundancy exists between schema and prose, but the structure makes the length manageable and each section adds behaviorally relevant 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?

There is no output schema, so the description must explain return values—and it does: opportunities[] with gap_pp, suggested_trade, reasoning, plus partition_check fields. It also covers edge cases (placeholders, low-similarity pairs, fill-check conditions) and cross-references a sibling tool, making the description self-sufficient for safe 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?

The input schema already provides solid descriptions for event and topic, so baseline is 3. The tool description adds meaningful extras: no-args default behavior, concrete slug examples, event vs topic mode mechanics, and cross-event pattern motivation. That pushes it above baseline, though the schema itself already carries much of 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 opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's modes (trending_scan, event, topic) and separates it from siblings like polymarket_fill_risk by scoping its role to opportunity detection.

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: call with no args for trending_scan, pass event for a specific market (recommended), and pass topic for cross-event scanning. It also points to an alternative tool ('For custom sizing use polymarket_fill_risk'), which is exactly the kind of contrast needed.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds substantial behavioral context: response segmentation, model-family logic, filter behavior, per-opportunity fields, diagnostics for empty segments, a 24h-move warning, and 1h KV-level caching. There is no contradiction with the annotations.

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

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

The description is long and dense but front-loaded with a clear purpose and every sentence contributes substantive operational detail. There is minor redundancy in repeating the by_segment segment names, but the overall structure is logically organized and appropriate for the tool's complexity.

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

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

With no output schema, the description thoroughly explains the return structure: by_segment, fed_candidates/fed_note, _diagnostics, and per-opportunity fields. It also covers caching, filter behavior, and why segments may be empty, making it complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with detailed property descriptions, so the baseline is 3. The description adds conceptual framing like 'TRADEABLE-EDGE KNOBS' and explains why min_kelly does not filter partition arbs, but most parameter semantics are already present in the schema. This modest added value justifies a 4.

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

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

The description clearly states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings by detailing unique model families, response segments, and diagnostics, while also communicating its primary use case.

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

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

The description gives clear context for when to use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains how knobs like min_liquidity and max_spread_pp filter tradeable edges, but it does not explicitly name sibling tools as alternatives or state exclusions beyond the Fed signal reliability caveat.

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

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

Annotations declare readOnlyHint/idempotentHint, and the description adds substantial behavioral detail: snapshot write behavior on cache-miss, 60-day TTL limits, decay computation on absolute edge_pp_net, signed semantics (negative = SELL YES), and explanation of snapshot gaps. This goes well beyond the structured annotations.

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

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

The description is long but well-organized: starts with a one-sentence summary, then structured Args, RESPONSE, and LIMITS sections. It is front-loaded with purpose, and each section provides necessary detail for a tool with no output schema. Slightly verbose but 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?

Because there is no output schema, the description fully documents the response structure (tracked, expired, snapshot_dates) and their semantics, along with historical limits and data gaps. No important aspect of using the tool is left uncovered.

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

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

Schema coverage is 100% (both days and window are described in the input schema). The description mostly restates the same defaults (14 days, '1wk') and adds minimal nuance like 'max 30' versus schema's 'clamp 2-30'. This doesn't enrich understanding meaningfully beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers 'how long has this edge existed and is it shrinking?'. This differentiates it from sibling tools like polymarket_edges by focusing on tracking edges over time rather than just showing current edges.

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

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

The description gives clear context by explaining that 'a fresh wide edge and a 3-week-old wide edge are different trades', implying this tool is used when edge age matters. It stops short of explicitly naming alternatives or exclusions, but the use case is clear enough.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses critical behavioral traits: it walks the order-book ladder, may return a 'cannot_fill' verdict, warns that partial basket fills convert an arb into an unhedged directional position, and names forced_directional_risk legs. This is valuable context not encoded 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 long but highly structured with clear mode sections and return-value lists. It front-loads the core purpose and uses ALL CAPS for critical requirements, though the density of information makes it a heavy read. Every sentence adds necessary context, but it could be slightly more scannable.

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

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

With no output schema, the description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers prerequisites, defaults, and risk warnings, making it complete for the tool's complexity.

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

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

The description adds significant meaning beyond the 100% schema coverage. It explains that market and event are mutually exclusive modes, side auto-defaults based on partition sum (sell if >1, buy if <1), and size_usd is interpreted as settlement notional in basket mode vs spend/proceeds in single-market mode. These clarifications prevent parameter misuse.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by naming polymarket_arbitrage and polymarket_edges and positioning itself as the pre-trade risk check.

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

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

It explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the single-market vs basket mode choice and defaults, providing unambiguous usage 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing behavioral traits such as the compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the nuance that pre-mapped does not mean tradeable. This provides rich context about what the tool actively evaluates and warns the agent about.

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; every sentence adds information about the tool's modes, response fields, safety warnings, and edge cases. It could be better structured with headers or bullet lists, but the content justifies the length for a tool with no output schema and multiple failure modes.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: leg-by-leg prices, spread values, compatibility_warning scenarios, temporal alignment, and skip counters. It also covers error cases (non-equivalent bet shapes, unrelated events) and the practical caveat that most pre-mapped topics are not tradeable, making it comprehensive for an agent to set expectations 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%, so the baseline is 3. The description adds value by explaining the relationship between the three parameters (topic vs override behavior), listing all valid topic shortcuts inline, and clarifying that explicit tickers override the topic-mapped side. This makes parameter semantics more actionable than the schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb-resource relationship. It distinguishes itself from sibling tools by explaining its focus on cross-venue comparison, the two modes, and its safety fields.

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

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

The description provides explicit guidance on when to use which mode (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility_warning today, setting accurate expectations. It does not explicitly name alternative sibling tools, but the contextual caveats and scenarios ('when bet shapes are equivalent... when they aren't the tool says so') effectively guide an agent on appropriate usage.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds meaningful context: scoping to identifier (anonymous IP, BYO key hash, etc.) and the listing behavior when key is omitted. No contradictions. Slight gap in not describing return format, but that's not necessary given the tool's simplicity.

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 with no fluff. The main action is front-loaded, examples are concise, and every sentence adds relevant information. Perfect structure for quick comprehension.

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

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

For a tool with one optional parameter and no output schema, the description covers purpose, usage context, scope, and relationships to sibling tools. It is entirely sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with a clear description, so baseline is 3. The description goes beyond by explaining the key as a handle to a previously saved value and reinforces the optionality for listing all keys, adding context to the parameter's purpose.

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 ('Retrieve') and resource ('a value previously saved via remember'), and distinguishes itself from siblings by explaining the dual mode (retrieve by key or list all keys). It also provides concrete use examples, making its 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?

Explicitly says when to use ('Use to look up context the agent stored earlier') and pairs with alternatives ('Pair with remember to save, forget to delete'). This gives clear guidance on the tool's role within the sibling set.

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 explicitly discloses that mark_read:true flags events as read, which affects future calls. This contradicts the readOnlyHint annotation that implies no side effects, constituting an annotation 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 about four sentences, all substantive, front-loaded with the core action, and free of redundant information. Every sentence contributes meaningful guidance.

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

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

For a tool with 5 optional parameters and no output schema, the description explains return payload components (source, citation_uri, raw event payload), filtering options, mark_read behavior, and polling suitability. It also provides an HTTP endpoint for scripts/dashboards. The only gap is the annotation contradiction, but overall coverage is solid.

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 all 5 parameters with 100% descriptive coverage, giving a baseline of 3. The description adds value by explaining the practical effect of mark_read (next call only shows newer ones), providing a concrete filter example ('sec_8k'), and clarifying that type and since can be combined.

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 'Pull fired events from your subscription feed,' using a specific verb and resource. It distinguishes itself from siblings like list_subscriptions or recent_changes by specifying it returns alerts written to a persisted feed with citation_uri and raw event payload.

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: use for interactive polling of alerts, with filtering by type and since, and marking read. It also mentions the same feed via a public URL for scripts/dashboards, implying this tool is for interactive use. However, it does not explicitly name alternative tools or 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 discloses important operational behaviors: it fans out to multiple sources in one parallel call, describes the GDELT→GNews fallback with rate-limiting conditions, and notes the USPTO PatentsView API sunset causing a soft-fail. It also explains the return structure (changes[] grouped by source, total_changes, citation URIs), adding significant 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 each sentence contributes value. It opens with user-facing query examples, then explains the parallel call, sources, fallbacks, time format, and return structure. Slightly long, but given the tool's complexity, it is well-organized and free of 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?

Even without an output schema, the description explains the return fields and citations. It covers the full context: what sources are used, fallback behavior, time window interpretation, and provides an explicit alternative for static profiles. This is exceptionally 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?

The input schema already provides thorough descriptions for all three parameters, including examples for `since` and `value`. The tool description mostly reiterates these examples ('ISO date...relative shorthand', 'ticker or zero-padded CIK') without adding deeper semantic nuance beyond what the schema already offers.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and names concrete sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes itself from sibling tools like entity_profile, which is explicitly called out for static profiles, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool (e.g., for 'What's new with X' queries) and when to use an alternative: 'Use entity_profile instead when you want the static profile...'. This is a clear directive that helps an agent select between tools.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds context beyond these: persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('scoped by your identifier'). No contradiction with annotations.

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

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

The description is well-structured: first sentence states purpose, second gives usage guidance, third covers behavior and persistence. Every sentence earns its place with 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?

The tool is simple with only two parameters, full schema coverage, and annotations that cover the essential safety profile. The description adds persistence, scoping, and complementary tool guidance, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds the conceptual context that this is a key-value store but doesn't provide additional parameter-level syntax or format details beyond what the schema already includes. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with the specific resource being key-value memory. It distinguishes from siblings by mentioning 'recall' and 'forget' as complementary operations.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also explains how to use complementary tools: 'Pair with recall to retrieve later, forget to delete.'

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 read-only, idempotent, and non-destructive. The description adds behavioral context by explaining internal cascading lookups, auto-disambiguation, and the exact return structure including citation URIs. These details help the agent anticipate side effects and output.

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?

While longer than typical, every sentence adds value: examples, supported types, return details, and usage guidance. The structure front-loads the purpose and then systematically breaks down each type.

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 fully explains what each entity type returns, including field names and citation URIs. It also covers the internal lookup cascade and disambiguation, making it self-sufficient for the agent.

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

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

The input schema already covers both parameters with descriptions. The description enhances this by providing concrete examples for each type and clarifying acceptable input formats (e.g., ticker, CIK, or name for companies; brand or generic name for drugs). This goes beyond the schema's basic type hints.

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 resolves names to canonical identifiers, provides query examples, and lists supported entity types with their respective output identifiers. This clearly distinguishes it from sibling tools like entity_profile or compare_entities, which focus on different aspects.

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 instruction 'Use FIRST whenever you have a name but need an ID' provides direct usage guidance. It also notes that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention when not to use it or compare with alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and surfaces which entity is most/least recognized. It also discloses the return shape (ranked list with score, confidence, signal density), which goes well beyond the annotations.

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

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

The description is three sentences: core function, mechanism, and use case/output. It is front-loaded with the main verb, uses concrete examples, and contains zero filler. Every sentence contributes distinct information.

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

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

With no output schema, the description compensates by explicitly listing the returned fields (score, confidence, signal density). It covers what the tool does, how it works, when to use it, and what to expect—fully sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%: all parameters (entities, models, _apiKey, context) have meaningful descriptions. The description does not add any additional parameter semantics beyond the schema; it even repeats the 'subject vs competitors' notion already present in the schema's entities field. Thus, it meets the baseline without adding extra 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 opens with a specific verb-resource pair: 'Compare AI visibility across multiple entities side-by-side', which clearly distinguishes it from single-entity tools like ai_visibility_check. It further elaborates by naming the internal mechanism (probes via ai_visibility_check), ranking by score, and highlighting most/least recognized, making the purpose unmistakable.

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

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

The description states when to use it: 'Useful for competitive AI-marketing audits', and provides a concrete example. It references ai_visibility_check as the underlying probe, implying that single-entity checks are handled separately, but it does not explicitly say 'use this instead of X when comparing multiple entities' or list any when-not conditions.

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

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

Annotations already establish read-only, idempotent, safe behavior. Description adds valuable behavioral details: partial failure handling, first-measurement latency of 5-30s, sources_failed field, and NPM-only v1 scope. No contradiction with annotations.

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

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

Every sentence contributes unique information: purpose, data sources, return fields, ecosystem scope, and failure behavior. The text is front-loaded with the main promise and uses compact phrasing like 'Composite' and 'fans out across'.

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

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

With no output schema, the description fully compensates by enumerating exact return fields (is_latest, license, etc.) and describing links and alternative versions. It also addresses timing and failure behavior, making it complete for a composite tool.

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

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

Schema description coverage is 100% and already documents both parameters (package name with scoped packages, version defaulting to latest). The description adds no new parameter-level detail beyond what schema provides, so baseline 3 is appropriate.

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

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

Description opens with a specific verb+resource ('should I add this npm package to my project' check) and names the exact data sources (deps.dev, bundlephobia). It clearly distinguishes itself from unrelated sibling tools and states the composite one-call nature.

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

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

Explicitly provides trigger contexts ('whenever an agent asks...') and gives clear exclusions for other ecosystems, directing to deps.dev:version directly. This satisfies the when/when-not/alternatives requirement.

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

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

Annotations already declare read-only, non-destructive, idempotent, and open-world hints. The description adds valuable behavioral context: documents appear on committee websites within hours (unlike the printed record), and matching is against the headline/slug only, not full text — including the caveat that an empty result means no headline match, not absence of subject. This goes well beyond the annotations.

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

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

The description is dense but every sentence earns its place: scope and content, use-case examples, timing/alternative, and critical limitation. It is front-loaded with the main purpose and ends with an important caveat, with no fluff.

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

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

For a search tool with no output schema, the description provides sufficient context: what is searched, which committees are covered, timing relative to official records, and the interpretation of empty results. It orients the agent for correct invocation and result interpretation without needing to guess.

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

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

The input schema covers all 5 parameters with detailed descriptions and examples (100% coverage), so the baseline is 3. The description does not add parameter-level detail beyond reinforcing the query matching semantics, which is already stated in the schema's query description. No compensation needed.

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 documents published by a congressional committee on its own website') and enumerates concrete content types (press releases, oversight letters, etc.). It also distinguishes itself from the sibling tool by noting the alternative search_congressional_documents covers the official printed record that lags by months.

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 ('Use for "what has House Oversight said about X"...') and an explicit exclusion: the official printed record is handled by search_congressional_documents. It also warns about the headline-only matching limit with an instruction on interpreting empty results.

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

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

Beyond the readOnly/idempotent annotations, the description reveals the underlying algorithm ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), the 200K character limit with truncation flagging, and the output format (top-N passages with offsets and similarity scores). This enriches the agent's understanding of performance and edge cases.

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

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

The description is dense but every sentence contributes: purpose, input examples, output, use case, pairing, algorithm, and limits. It is front-loaded with the core action, and the structure flows logically from general to specific, making it easy to parse without redundancy.

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

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

Given the lack of an output schema, the description thoroughly explains return values (passages, offsets, similarity scores). It also covers performance characteristics (truncation, windowing) and integrates with sibling tool workflows. No critical operational aspect is missing for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% for all three parameters, so the baseline is 3. The description adds illustrative examples for 'text' ('SEC 10-K body, an article, a long tool result') and reinforces the natural-language nature of 'query', but these are qualitative refinements rather than essential clarifications beyond the schema's own 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 'Semantic search INSIDE a fetched record', which precisely identifies the verb (search), resource (record), and scope (inside a fetched record). It distinguishes this from sibling tools by emphasizing it operates on already-retrieved text and returns passages, contrasting with tools like ask_pipeworx_grounded that ground over documents.

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 when the record is too big to cram into the prompt' and it directly references an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly indicates both when to use and how it relates to a sibling tool.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds crucial behavioral details: requires OAuth account, anonymous/BYO cannot persist, SMS verification requirement and 10/day cap, webhook auto-disable after 10 failures, and one-time signing secret. These disclosures are not present in annotations and significantly aid the agent in understanding side effects and requirements.

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

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

The description is dense and covers many aspects (types, delivery channels, prerequisites, limits) in one paragraph. While it's not formatted with bullets, every sentence serves a purpose. It is longer than ideal but appropriate given the tool's complexity.

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

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

The description covers all major aspects: supported types, parameters, delivery channels, prerequisites, return value, and error-prone behaviors. It does not describe idempotency behavior explicitly, but the idempotentHint annotation already covers that. Given the detailed schema and annotations, the description is sufficiently complete for reliable tool 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?

The schema already provides 100% coverage with detailed descriptions and examples for each parameter. The description adds value by reinforcing type-specific examples (e.g., sec_8k items, polymarket_edge topic) and clarifying the delivery.webhook parameter's signing secret behavior, which goes beyond the schema's basic type description.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It also enumerates supported types and delivery channels, making its purpose unambiguous.

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

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

The description provides explicit usage context: prerequisites (Pipeworx OAuth account, verified phone for SMS), supported subscription types with examples, and alternative consumption methods (via recent_alerts or GET endpoint). It does not explicitly state when not to use the tool, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnly/idempotent/non-destructive; the description adds behavioral detail: output is drawn from a 'live catalog', returns exact tool + argument shapes, and categories are enumerated. 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 information-dense, containing eight example queries, category list, and usage guidance, but is front-loaded and every sentence contributes. It is slightly long but appropriate for an onboarding tool.

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

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

For a single-optional-parameter tool with no output schema, the description covers purpose, usage, parameter guidance, and return shape, making it fully self-contained.

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

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

The input schema fully describes the optional `topic` parameter with allowed values and behavior. The description merely repeats these values with examples, adding no new semantics beyond the schema.

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

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

The description opens with example user queries and explicitly defines the tool as 'the onboarding entry point', returning category-bucketed example questions with exact tool + argument shapes. This clearly distinguishes it from siblings like ask_pipeworx or discover_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 instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you', and names sibling tools to learn about (ask_pipeworx, entity_profile, compare_entities). Also describes call patterns: no args for full spread, topic for focus.

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 (which indicate a write operation that is not destructive and is idempotent), the description discloses the precise side effect: the row is deactivated, not deleted, and historical events remain accessible via recent_alerts. It also reveals the ownership enforcement behavior. This additional context materially improves the agent's understanding of consequences.

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 short, front-loaded sentences. The first states the primary purpose, the second adds an ownership constraint, and the third explains the side effect. Every sentence contributes unique value, with no redundancy or 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?

Given the tool's simplicity (one parameter, no output schema) and the rich annotations, the description provides all necessary context: the action, the ownership rule, the non-destructive nature, and the preservation of historical events. This is complete for the tool's scope.

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

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

The input schema already fully documents the only parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description merely repeats 'by id' without adding any new parameter-specific meaning. With 100% schema coverage, 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 opens with 'Cancel a subscription by id', which is a specific verb and resource. It further clarifies that the row is deactivated rather than deleted, distinguishing this tool from deletion and making its purpose unambiguous relative to siblings like subscribe and list_subscriptions.

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

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

The description provides clear context for when to use the tool: to cancel an existing subscription. It also includes ownership enforcement ('you can only cancel your own subscriptions') which serves as a usage constraint. However, it does not explicitly name alternative tools for related operations (e.g., list_subscriptions to find ids), 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?

The description discloses significant behavioral detail beyond the annotations: two distinct pipelines (SEC EDGAR+XBRL and grounded), exact percent-delta math, automatic fall-through for non-financial claims, and a list of possible verdicts. It also mentions returning a citation and reasoning, which greatly informs the agent of expected behavior.

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

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

The description is long but well-structured, starting with trigger phrases and a clear purpose. Each sentence contributes value: usage guidance, pipeline details, and return information. While somewhat dense, the complexity of the tool justifies the length and it is not redundant.

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 what the tool does, when to use it, how it routes different claim types, and what it returns (verdict, value, citation, reasoning). With no output schema, this description adequately substitutes by explicitly listing the return format and the two operational paths.

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

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

The input schema provides 100% coverage with detailed descriptions for both 'claim' and 'tolerance_pct', including an example and override semantics. The tool description does not add substantial parameter-level detail beyond the schema, so it meets the baseline without exceeding 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 defines the tool as natural-language claim verification with a specific outcome (verdict), using explicit trigger phrases like "fact check" and "verify the claim that...". It distinguishes itself by stating it replaces 4–6 sequential calls, implying a consolidated verification workflow.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing details for financial vs. other claims. However, it does not explicitly name sibling tools for when-not-to-use cases, only implicitly differentiating from sequential multi-call processes.

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