Open Fec

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by explaining default model free tier, optional API key for Anthropic, and return fields. No contradiction.

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

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

Two efficient sentences, front-loaded with purpose, no extraneous information. Every sentence adds value.

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

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

Despite no output schema, description adequately explains return shape (per-model fields + combined view). All parameters are well-described. Sufficient for a read-only query tool.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: clarifies default model, API key requirement, and context purpose for disambiguation.

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

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

Description clearly states verb ('probe'), resource ('LLMs'), and output ('score visibility 0-100 per model'). Distinguishes from siblings which are more Pipeworx-specific or different domains.

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 mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and default model behavior. Does not explicitly state exclusions or alternatives, but context is adequate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it routes to one of 5,474 tools, fills arguments, returns stable citation URIs, handles breaking news, and is a single fast call. No contradiction with annotations.

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

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

The description is longer than typical but dense with value: domain list, mechanism, trigger phrases, examples, and sibling comparisons. It is front-loaded with the 'PREFER OVER WEB SEARCH' directive and structured around clear sections. Minor redundancy between 'Use whenever' and 'START HERE' but each 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?

Given the tool's complexity (router over 5,474 tools) and absence of an output schema, the description adequately explains what is returned (structured answer with pipeworx:// citation URIs) and sets expectations about scope and speed. It also points to alternatives for specific needs. It does not discuss error handling or unmatched queries, but this is not critical for a natural-language query tool.

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

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

The input schema has 100% coverage for the single 'question' parameter and its aliases, so the description does not need to explain parameter syntax. The description adds usage-oriented meaning by listing trigger phrases and examples, but it does not introduce any semantic detail beyond the schema. 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 identifies ask_pipeworx as a universal factual question-answering tool that routes queries to thousands of verified sources and returns cited structured answers. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs, and it positions itself as the default entry point.

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

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

Usage guidance is exemplary: it explicitly says to prefer this over web search for a broad category of questions, provides trigger phrases ('what is', 'look up', 'find', 'get the latest'), gives concrete examples, and explicitly separates when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for fan-out). It also states it works on every tier and is the default start.

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, it discloses the beta/experimental nature, live candidate routing improvements, current inactive status, and exact equivalence to ask_pipeworx right now. It also states the response shape and full functionality, giving valuable behavioral context without contradicting the readOnly/idempotent hints.

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

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

The description is front-loaded with the tool's identity and purpose, and every sentence contributes: current beta status, usage guidance, and the no-fallback clarification. It is concise despite including a useful specific date and avoids unnecessary repetition.

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

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

The description covers the tool's current behavior, relationship to ask_pipeworx, and usage context. However, because there is no output schema, the phrase 'same response shape' depends on knowledge of ask_pipeworx; a fully self-contained description would briefly state what the response actually contains. 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?

Schema coverage is 100%, with all six parameters documented as aliases for `question`. The description only says 'same arguments' and does not add semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router (same 5,474 tools, same arguments, same response shape)' which precisely states what the tool does and its scope. It clearly distinguishes it from sibling ask_pipeworx as an experimental variant, making the purpose unambiguous.

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

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

It provides explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It also clarifies that it is not a fallback ('Falls back to nothing — this IS a full working router') and names ask_pipeworx as the stable alternative, covering when-to-use and alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses the structured return format, explicit refusal reasons, and the extra LLM call cost. It also explains the grounding behavior ('using ONLY what the tool result contains'), which goes beyond what annotations provide.

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

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

The description is information-dense but well-structured, with each sentence serving a distinct purpose: definition, routing behavior, response/refusal format, and usage guidance. It is slightly long but not wasteful, earning a strong score.

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

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

Since no output schema exists, the description compensates by fully specifying the return object and refusal reasons. It also covers usage trade-offs and contexts, making it complete for a complex tool that routes across many sources.

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

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

Input schema has 6 parameters, all documented aliases for 'question' with 100% description coverage. The description does not add parameter-specific semantics 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 identifies a specific verb+resource: 'Hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It explicitly contrasts with sibling ask_pipeworx ('Same routing... but...'), clearly differentiating the grounded mode from the casual alternative.

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

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

Provides explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also gives an exclusion with alternative: 'prefer ask_pipeworx for casual lookups.' This meets the highest bar for 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?

The description extensively covers behavioral traits beyond annotations: low-confidence resolution handling, closed market behavior, wide spread warnings, cancellation rule parsing, and fallback mechanisms for news sources. No contradictions with annotations.

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

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

The description is lengthy but well-organized with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loaded purpose. Every sentence adds value, though some repetition exists (e.g., explanation of output fields).

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

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

Given the tool's complexity (3 parameters, no output schema), the description provides comprehensive detail on response shapes, error conditions, and edge cases (closed markets, low confidence, wide spreads). It is complete for an agent to use effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds little parameter-specific meaning beyond the schema, though it reinforces the 'market' parameter's flexibility. Acceptable for high coverage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, and specifies input formats (slug, URL, question text). It provides concrete examples and distinguishes its purpose from potential sibling tools through its specific 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?

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It does not explicitly exclude use cases or compare to sibling tools, but the usage context is clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that it returns specific fields like receipts and disbursements, but doesn't disclose additional behavioral traits such as rate limits or authentication details.

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

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

The description is two sentences, front-loaded with action and example, and includes workflow guidance. 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?

Given the rich schema and output schema, the description is complete: it states the purpose, return values, prerequisite step, and example. No gaps remain.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description provides an example of the candidate_id format, adding marginal value 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 retrieves a campaign finance summary for a candidate via FEC candidate ID, lists key return fields, and distinguishes from sibling tools like committee_financials and search_candidates.

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 advises using search_candidates first to find the candidate ID, which is valuable usage guidance. It does not list exclusions, but the context 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns specific fields (receipts, disbursements, etc.) and is cycle-specific, which adds behavioral context 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?

Two sentences: first states purpose and input, second gives usage guidance. Every sentence is necessary and succinct. 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?

Given the tool's simplicity (3 parameters, no output schema), the description covers purpose, input, and a usage hint. It could optionally mention return format more explicitly, but it's 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 description coverage is 100%, so the baseline is 3. The description adds marginal value (e.g., cycle defaults to most recent) but largely repeats schema information.

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

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

The description clearly states the verb 'Get', the resource 'campaign-finance totals for a committee / PAC', and the method 'by its FEC committee ID'. It also distinguishes from sibling 'candidate_financials' by specifying the entity type (committee/PAC) and referencing 'search_committees' for ID lookup.

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 search_committees first to find the committee ID', providing clear context for when to use this tool. However, it does not mention alternatives like 'candidate_financials' or explicitly state when not to use it.

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

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

Details data sources and metrics (10-K financials for companies, FAERS and FDA data for drugs), explains handling of off-calendar fiscal years, and mentions output includes paired data with citation URIs. This goes well beyond the read-only and idempotent annotations, providing rich behavioral context.

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

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

Three sentences with high information density, front-loaded with example queries. Efficient but could slightly improve readability by separating the different entity types.

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

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

Covers purpose, usage, data sources, and output summary. Without an output schema, the description mentions paired data and citation URIs but lacks detail on the exact structure. However, this is acceptable given the complexity is moderate and the rest is well-covered.

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

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

Schema coverage is 100%, but description adds value by explaining the meaning of each enum value for 'type' and specifying that 'values' are tickers/CIKs for companies and drug names. This contextualizes the parameters beyond the schema definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific examples of user queries. It distinguishes itself from sequential single-entity lookups, 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool over alternatives. Also indicates the entity type and count constraints.

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 (which already declare readOnly/openWorld/idempotent): account requirements, paid plan limits, parallel decomposition, gaps[] never invented, contradictions[], citation resolvability conditions, semantic excerpting, and expected timing. It also clarifies that the openWorldHint does not mean open-web search, preventing misinterpretation. No contradiction with annotations.

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

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

The description is long but dense, with nearly every sentence providing unique operational guidance. However, the structure is a bit stream-of-consciousness—jumping from account requirements to core functionality, alternatives, depth details, citations, excerpting, and timing—which makes it less scannable. It earns a 4 rather than 5 due to this organization issue, though it is 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?

With no output schema, the description thoroughly explains the return packet (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, citation_uri conditions, and semantic excerpting. It covers prerequisites, alternatives, depth semantics, error behavior, and timing. For a complex tool with no output schema, this is exceptionally complete.

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

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

Although the schema covers both parameters with descriptions, the tool description adds significant extra meaning for the 'depth' parameter by explaining quick=3, standard=5 with gap recovery and contradictions, thorough=8 paid with lead-chasing, plus timing implications. It also reinforces that 'question' can be broad/multi-part, which is more than the schema states. This far surpasses the baseline for 100% schema coverage.

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

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

The description has a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1429 STRUCTURED data sources' in 'ONE call'. It explicitly distinguishes this tool from open-web search and from ask_pipeworx, making the purpose and differentiation clear.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also names the alternative tool directly and mentions the account-required prerequisite. 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 indicate read-only and idempotent. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly. No contradiction.

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

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

Description is a single paragraph but well-organized with upfront purpose and usage context. Slightly long list of topics but remains readable.

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

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

For a discovery tool with 6 params and no output schema, description explains what tools are returned (names, descriptions, schemas) and that they are callable. Sufficient for the task.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions query aliases and provides examples in schema but adds minimal new semantic meaning 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 finds tools by describing data or task, and lists many example topics. It distinguishes from sibling search tools that query data rather than 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use, though not when to avoid.

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 read-only, idempotent, non-destructive behavior, and the description aligns with that (returns data, no mutations). The description adds valuable context beyond annotations, such as patents soft-failing after May 2025, news fallback chain, and the parallel call nature. 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 relatively long but efficient; it front-loads with use-case examples then concisely details the tool's capabilities and limitations. Every sentence serves a purpose, with no redundancy. Slightly more structured formatting (e.g., bullet list) could improve scanability, but it remains clear and earns its length.

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

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

Given the tool's complexity (multiple data sources) and absence of an output schema, the description fairly thoroughly enumerates returned fields: CIK, company name, filings (with URIs), fundamentals (specific fields), patents (with caveat), news, LEI. Minor gaps (e.g., no mention of result count limits or potential latency) prevent a perfect score, but it is highly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this with concrete examples ('AAPL', '0000320193'), confirms the restricted enum for type, and reiterates the constraint on names. This adds practical guidance 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 clear example queries ('Tell me about X', 'brief me on Tesla') and defines the tool as 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by specifying it replaces chaining of single-pack lookups, making the purpose and scope 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion: names are not supported; advises to use resolve_entity first. This gives both when-to-use and when-not-to-use guidance with a specific 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 indicate destructiveHint=true and idempotentHint=true, which the description's 'Delete' aligns with, no contradiction. The description adds useful context about use cases (stale context, sensitive data) but does not elaborate on behavior like what happens on non-existent keys, which is acceptable given annotations.

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

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

The description is two sentences, front-loaded with the primary action, and contains zero irrelevant information. Every sentence earns its place.

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

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

For a simple tool with one parameter and annotations covering destructive and idempotent hints, the description is complete. It covers purpose, usage guidelines, and pairing advice. No output schema is needed for a delete operation.

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

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

Schema coverage is 100% with a clear description for 'key'. The description only adds 'by key', which does not add substantial meaning beyond the schema. 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 verb 'Delete' and the resource 'memory by key', making the action unmistakable. It also distinguishes from siblings 'remember' and 'recall'.

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 provides when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with related tools 'remember' and 'recall', guiding the agent on alternatives.

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

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

The description discloses the tool's behavior (fetches page, extracts title/description/key links, emits standard format) beyond the annotations. The annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds process details without contradicting them.

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

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

The description is concise with three sentences, front-loading the primary action and output format. Every sentence adds value without wasting words.

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

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

Given the tool has 2 params, no output schema, and full schema coverage, the description explains the output format ('single text blob ready to drop at site-root/llms.txt'), which is sufficient. A slight deduction because it doesn't mention error handling or edge cases, but overall complete.

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

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

Schema coverage is 100%, so the schema fully documents both parameters. The description does not add semantic value beyond what is in the schema (e.g., 'max_links' default and max are already described). 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 ('Generate') and resource ('llms.txt file for any URL'), and distinguishes this tool from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than scanning or checking.

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 ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which clearly indicate when to use the tool. It does not, however, explicitly state when not to use it or compare directly to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the return structure (id, type, params, timestamps, fire_count) and the effect of the 'include_inactive' parameter, going beyond the schema.

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

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

Two sentences with no waste. The first sentence states the primary purpose and returns, the second provides usage guidance. Concise and 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?

Given the simplicity of the tool (no output schema, one optional boolean parameter), the description covers the return fields, usage intent, and parameter effect, making it complete for the context.

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

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

Schema coverage is 100% and the parameter 'include_inactive' is well-described in the schema. The description only implies it by mentioning 'active subscriptions' but doesn't add new semantic value, 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 it lists the caller's active subscriptions and specifies returned fields (id, type, params, etc.). This distinguishes it from sibling tools like subscribe/unsubscribe by focusing on reviewing existing subscriptions.

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

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

Explicitly advises using the tool to review monitored subscriptions before adding more or to find an id to cancel. While it doesn't mention when not to use, the context with siblings is implied.

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?

Discloses the claim_token flow, rate limiting ('5 per identifier per day'), quota independence ('doesn't count against your tool-call quota'), and roadmap impact. These go far beyond the annotations, which only state readOnlyHint=false and destructiveHint=false. The description aligns with the write nature of the tool and adds concrete operational behavior.

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

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

The description is longer than average but every sentence contributes: purpose, use cases, exclusions, operational details. It is front-loaded with the core purpose and all sentences are information-dense, so no waste.

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

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

Given the 4 parameters, nested context object, and absence of an output schema, the description fully explains the tool's purpose, return-token mechanism, exclusions, rate limits, and usage guidance. It leaves no significant gaps for the agent to interpret.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining the claim_token parameter's lifecycle ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed') and by advising users to focus on Pipeworx tools/packs rather than pasting end-user prompts, which clarifies the message parameter.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback types (bug, feature/data_gap, praise) and clearly distinguishes this feedback tool from sibling query/research tools like ask_pipeworx or deep_research.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides a clear when-not: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds significant context: self-aggregating signal, no PII, derived from CF analytics-engine, cached 5min-1h depending on window. 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?

Description is well-structured with bullet points for use cases, but slightly verbose. Every sentence adds value; no wasted words. Could be slightly trimmed but remains effective.

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

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

Given a single optional parameter, no output schema, and comprehensive annotations, the description provides sufficient context for usage, behavior, and expected output. Covers caching, privacy, and aggregation source.

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 description for the 'window' parameter. Description adds nuance about shorter vs. longer windows and defaults. Adds value beyond 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?

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', using a specific verb-resource combination. It differentiates from siblings like discover_tools by focusing on trending/current demand.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Provides guidance on window selection with context on shorter vs. longer windows. Lacks explicit when-not-to-use but adequate.

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 readOnly, idempotent, and non-destructive. The description goes far beyond, detailing the scanning logic, partition checks, fill checks with realizable edge, thresholds, and filters. It alerts users that realizable_edge_pp <= 0 means the opportunity is not actionable. 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 fairly long but well-structured, with clear sections for each mode and additional checks. It is front-loaded with the core purpose. While every sentence adds value, some technical details could be slightly condensed. Overall, it balances completeness and clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure including opportunities fields and partition_check fields. It also covers edge cases like fill check and placeholder filters. Given the tool's complexity, this is remarkably 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 descriptions for both parameters. The description adds substantial extra meaning: examples of event slugs and topic seed questions, explains the modes, and clarifies behavior. This significantly enriches the schema beyond the basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It immediately distinguishes its three modes (no args, event, topic) and explains each. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly guides when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. It also advises using polymarket_fill_risk for custom sizing, indicating when not to use this tool. This provides clear usage context and alternatives.

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

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

The annotations indicate a safe, read-only, idempotent operation. The description goes far beyond annotations by detailing the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge computation details, caching behavior ('Cached 1h at the KV level'), and diagnostics for empty segments. No contradictions with annotations.

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

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

The description is verbose (over 500 words) and includes extensive technical details about model families and knobs. While well-structured with segments, it could be more concise. The first sentence front-loads the main purpose, but subsequent sentences may overwhelm an agent with unnecessary depth for initial selection.

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

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

For a complex tool with 9 parameters and no output schema, the description is exceptionally complete. It explains the three response segments, edge computation, tradeable-edge knobs, diagnostics, caching, and special cases (Fed bets, filter skips). An agent has sufficient information to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context beyond the schema (e.g., explaining why min_partition_leg_kelly is needed for partition arbs), but it does not provide significant additional insight for most parameters. The schema already adequately describes each 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 the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the use case ('what should I bet on today') and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx-driven edge discovery.

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

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

The description provides explicit usage context: 'agents discover opportunities without paging hundreds of markets' and notes that Fed bets are excluded from ranking. However, it does not explicitly compare when to use this tool versus sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which would be helpful for an agent deciding among alternatives.

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

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

The description extensively supplements the annotations (readOnlyHint, etc.) by detailing the use of daily snapshots, response fields (tracked, expired, snapshot_dates), trend and decay computation, and limitations (60-day TTL from snapshot enablement). 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 appropriately structured with a clear opening sentence and detailed breakdown. While somewhat lengthy, every sentence adds useful information. Could be slightly trimmed, but effective overall.

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

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

Despite no output schema, the description thoroughly explains all response fields and their meanings. Parameters are fully explained, limitations noted, and context about snapshot frequency and data coverage provided. Complete for the tool's complexity.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining the response structure and the meaning of returned fields, going beyond the schema descriptions. Baseline 3 is exceeded.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge duration, distinguishing it from the sibling tool 'polymarket_edges' which likely provides raw edge data.

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

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

The description explains when to use the tool (to differentiate fresh vs. old wide edges) and provides context like 'a 3-week-old wide edge is wide for a reason'. It does not explicitly state when not to use it or mention alternatives, but the context is strong 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?

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds behavioral context beyond annotations: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), warns about partial fills leading to unhedged positions, and describes clamping of size_usd. It does not contradict annotations, and the added value justifies a score above the baseline.

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

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

The description is relatively long but well-structured and front-loaded with the purpose. It uses clear sections and bullet-like points. Every sentence adds value, but it could be slightly more concise without losing clarity. Still, it earns a 4 for effective structure and minimal waste.

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

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

Given the complexity (two modes, exchange mechanics), no output schema, and related sibling tools, the description is highly complete. It explains return fields for both modes, edge cases (thin legs, forced directional risk), and references the broader context of arb bot P&L. The agent can use this tool correctly without additional information.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning: single-market vs basket mode explained, side defaults, auto-detection for basket, size_usd interpretation differences (spend vs proceeds vs settlement notional). This goes beyond the schema descriptions, which are already present but less detailed.

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

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

The description clearly states the tool's purpose as performing a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It uses specific verbs and resources, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-check before acting on signals from those tools.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills cause directional risk) and states the requirement of one of `market` or `event`. This is excellent guidance for agent 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 indicate readOnlyHint, openWorldHint, idempotentHint; the description elaborates on behavior beyond annotations, such as how bet shape equivalence affects signal validity, the meaning of compatibility_warning cases, temporal alignment impact, and skipped cross-type counters. 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 detailed but well-structured with sections (overview, modes, response, safety fields). Each sentence adds necessary context given the tool's complexity. Slightly longer than minimal, but justified by the need to explain nuanced behavior.

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

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

Despite no output schema, the description thoroughly explains the response format: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. This covers all necessary context for the agent to interpret results and handle edge cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the two usage modes, listing the 10 pre-mapped topics, and clarifying that explicit tickers override topic mapping. Examples are also provided, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (pre-mapped topics and explicit pairing) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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 pre-mapped topics vs explicit tickers, explains the meaning of safety fields (compatibility_warning, temporal_alignment), and warns that most pre-mapped topics return warnings, indicating when spreads are not tradeable. This helps the agent decide when to use this tool over alternatives.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. Description adds scoping (anonymous IP, BYO key hash, account ID) and list-all behavior, providing useful context 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?

Two sentences, front-loaded with purpose, no redundant words. Efficient and well-structured.

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

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

Given simplicity (1 optional param, no output schema), description covers usage, behavior, scoping, and relationships to other tools. Complete for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter description. Description reinforces schema but adds context about pairing with remember, but does not add significantly new semantics.

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

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

Description clearly states the verb (retrieve/list) and resource (previously saved values/keys), distinguishing from siblings like remember and forget. It specifies scope and behavior (omit key to list all).

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 'Use to look up context the agent stored earlier' and pairs with remember/forget. Lacks explicit when-not-to-use but context is clear among sibling tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: mark_read flagging behavior, field contents (source, citation_uri, raw payload), and filter effects, all beyond what annotations provide.

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

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

Three sentences, each purposeful: purpose, field details, filters and mark_read, then alternative access. Front-loaded, no fluff. 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?

No output schema, but description explains return fields (source, citation_uri, raw payload). Covers filtering, limit, mark_read, and alternative endpoint. Lacks ordering/sort details and error behavior, but adequate for a read-only 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 all 5 parameters with descriptions (100% coverage). Description reinforces parameter meaning with examples (e.g., filter type 'sec_8k', ISO timestamp) and explains mark_read effect, adding value beyond 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?

Description begins with 'Pull fired events from your subscription feed,' a specific verb-resource pair. It details returned fields and filters, clearly distinguishing from sibling tools like list_subscriptions or search_within by focusing on subscription feed events.

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?

Mentions polling works fine and an alternative REST endpoint for scripts/dashboards, providing some context. However, it does not explicitly contrast with sibling tools or state when not to use this tool, leaving usage guidance implicit.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond by detailing the multi-source fan-out, fallback logic, soft-fail for USPTO, and return format (changes grouped by source, total_changes count, citation URIs). No contradictions with annotations.

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

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

Description is moderately long but well-structured, starting with example queries and then methodically explaining sources, parameters, and return structure. Every sentence adds value; no redundancy. Slightly verbose but justified by 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 adequately covers return fields (structured changes, total_changes, URIs). It explains the multi-source architecture and fallback behavior. Could mention maximum window size or pagination, but overall complete for a change-feed tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful context: explains the `since` parameter's accepted formats (ISO date or relative shorthand like '30d'), clarifies `value` accepts ticker or CIK, and notes `type` is currently limited to 'company'. This elevates understanding beyond 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?

Description starts with concrete example queries ('What's new with X', 'latest on Y') and clearly states the tool provides a change feed for a company in a given time window. It explicitly distinguishes from sibling entity_profile, saying when to use that instead. Verb+resource is specific and unambiguous.

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

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

Explicitly directs users to entity_profile for static profiles without a time window, providing clear context when not to use this tool. Also explains fallback behavior (GDELT→GNews) and limitations (USPTO soft-fail). No explicit 'when-not' beyond the alternative, but the guidance is strong.

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?

Discloses scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours). Adds context that annotations (idempotentHint=true, destructiveHint=false) do not cover, such as session-specific 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?

Four sentences, front-loaded with purpose. Efficient but could be slightly trimmed of redundancy. Still well-structured.

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

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

Given no output schema, description adequately covers storage behavior, persistence, and pairing with other tools. No missing critical information for an agent to use it effectively.

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 with good descriptions. The description adds value by explaining the key-value pair nature and scoping, reinforcing usage. Slight extra context beyond schema warrants 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 saves data for reuse across conversations, with a specific verb 'Save' and resource 'data'. It distinguishes from siblings like recall and forget by explicitly mentioning them.

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: 'when you discover something worth carrying forward' and provides examples. Also mentions pairing with recall and forget for retrieval and deletion, giving clear 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?

Annotations already disclose read-only, idempotent, and non-destructive behavior. The description adds valuable context about internal cascading lookups, auto-disambiguation for companies, and citation URIs, going beyond the annotations without contradiction.

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

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

The description is packed with useful information—examples, usage guidance, supported types, and return details—with no wasted words. It is front-loaded with example queries and structured by entity type, making each sentence earn 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?

Despite lacking an output schema, the description fully explains what the tool returns for each type, the accepted input formats, citation URIs, and the internal cascade behavior. It gives an agent everything needed 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 schema covers 100% of parameters with detailed descriptions. The description further elaborates on expected outputs (ticker, CIK, RxCUI, etc.) and the auto-disambiguation behavior, adding meaning beyond the schema fields.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It provides concrete examples (ticker, CIK, RxCUI) and distinguishes itself from sibling tools by explicitly noting it replaces manual lookups and should be used first when an ID is needed.

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

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

It gives strong when-to-use guidance: "Use FIRST whenever you have a name but need an ID" and explains the supported entity types with input formats. However, it does not explicitly mention when not to use the tool or name specific alternative tools for exclusions, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds details: it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. 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 concise with three sentences, front-loaded with the core action. Each sentence serves a purpose without any fluff.

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

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

Given the tool has 4 parameters and no output schema, the description adequately explains the output structure (ranked list with score, confidence, signal density). It covers the use case and behavior, though it could mention error handling or limits.

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

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

The input schema has 100% parameter description coverage. The description adds extra meaning by noting that the first entity is treated as the 'subject' for narrative and that context is for disambiguation, which goes 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's purpose: compare AI visibility across multiple entities side-by-side. It distinguishes itself from sibling tools like ai_visibility_check by focusing on multi-entity comparison and ranking.

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 (competitive AI-marketing audits) with an example question. However, it does not explicitly state when not to use it or name alternatives, though the sibling tool ai_visibility_check is implied for single entity checks.

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

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

Description adds substantial behavioral context beyond annotations: it's a composite call that fans out across services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. Annotations already indicate readOnly, idempotent, and non-destructive; description enriches with real usage nuances.

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

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

The description is somewhat long but front-loaded with key purpose. Every sentence provides necessary context. Could be slightly more concise, but structure is logical: purpose, usage, ecosystem limitations, and behavioral notes.

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?

Although there is no output schema, the description thoroughly explains what the tool returns: summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min/gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and alternative versions. It also covers partial failure behavior. Complete for a complex 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?

Input schema already covers both parameters with descriptions (package name, version with default). Description adds that scoped packages like @types/node are accepted and that version defaults to latest. This adds value beyond schema but schema coverage is already high (100%).

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 composite nature of the tool: it checks npm packages across deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependency count, ESM/tree-shake support). It distinguishes from sibling tools by specifying the npm ecosystem scope and mentioning alternative tools for other ecosystems.

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

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

Provides explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also tells when not to use: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly helps an agent decide when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false/true, indicating a safe read operation. The description adds value by listing specific return fields (ID, name, party, office, state, district, election years) and providing an example, which 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 extremely concise with two sentences and an example, no wasted words. It front-loads the purpose and provides immediate actionable information.

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

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

Given the presence of an output schema (not provided but indicated), the description adequately covers the tool's functionality, return fields, and usage pattern. The example further clarifies invocation. No gaps remain for a well-understood search tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add additional semantic meaning beyond what is in the schema, but the example provides a concrete usage scenario, which is modestly helpful.

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

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

The description clearly states the verb 'Search' and the resource 'federal election candidates', specifying filters by name, state, or party. It distinguishes from sibling tools like 'search_committees' and 'search_contributions' by focusing on candidates.

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

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

The description implies usage by listing filters but does not explicitly state when to use this tool vs alternatives or when not to use it. The context signals and sibling list help, but the description itself lacks explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it returns specific fields and gives an example, but does not add significant behavioral context beyond what annotations provide.

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

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

Two sentences plus an example, front-loaded with the core purpose, 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?

Given the simple tool with 2 parameters and an output schema, the description covers the necessary information. Lists return fields, provides an example, and is complete for typical usage.

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

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

Schema description coverage is 100%, so both parameters are already described. The description provides an example usage but does not add new meaning 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?

Clearly states it searches political committees by name, lists returned fields (ID, name, type, etc.), and distinguishes from sibling tools like search_candidates which searches candidates.

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 'by name' and provides an example usage. Does not explicitly state when not to use or mention alternatives, but the context of siblings implies this is for committee name searches.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the constraint that at least one of committee_id or contributor_name is required, which is a behavioral detail beyond the schema. 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 a single sentence that conveys purpose, fields, filters, use cases, and constraints. Every word is efficient, and it is front-loaded with the main action.

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

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

The description covers purpose, filters, and constraints. It mentions returned fields (donor, amount, employer, city/state, date). It lacks mention of pagination or result limits, but for a search tool with 100% schema coverage, it is nearly complete.

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

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

Schema coverage is 100%, so the description does not need to repeat parameter details. It adds value by summarizing filters and highlighting the required constraint (committee_id or contributor_name) not present in the schema's required list.

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

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

The description clearly states the tool searches itemized individual contributions and lists the fields returned (donor, amount, employer, etc.). It distinguishes from sibling tools like search_committees and search_candidates by focusing on contributions and providing use-case examples.

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 prefer scenarios ('who donated to committee', 'person's donations') and a requirement (at least one of committee_id or contributor_name). It does not explicitly state when not to use it, but the context implies alternatives exist among siblings.

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

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

The description adds behavioral details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' Annotations already indicate readOnlyHint and idempotentHint, and the description adds useful technical context without contradiction.

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

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

The description is three sentences: first states the core purpose, second explains when to use and benefits, third gives technical details. Every sentence is useful and front-loaded.

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

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

For a tool with 3 parameters, no output schema, and comprehensive annotations, the description covers purpose, usage, technical details, and limitations (200K cap, truncation). It is sufficient for correct selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some extra context, such as the character limit for text (200K) and example queries, but does not significantly extend beyond the schema definitions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' specifies the verb and resource, and provides examples. It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded and is for large records.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains that search_within saves context. It suggests pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use the 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?

ReadOnlyHint=false matches 'create' action. Discloses behavioral traits: authentication requirement, type-specific behavior, delivery channel capabilities and limits (10/day SMS cap, webhook auto-disable). Idempotency hint not explicitly addressed but no contradiction.

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

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

Front-loaded with purpose, well-structured with sections. About 200 words, every sentence adds value. Slightly verbose but fully informative, no waste.

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

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

Covers types, required auth, delivery options, output (id). Missing error handling or rate limit details beyond SMS cap. For a complex tool with 5 types and nested objects, this is mostly 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%, but the description adds significant value with concrete examples for each type (e.g., sec_8k with items, polymarket_edge with topic), and detailed delivery options with constraints. Greatly enhances understanding beyond 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?

Clearly states the action (create a proactive monitoring subscription), the resource (live-data event stream), and the output (returns subscription id). Differentiates from siblings like unsubscribe and list_subscriptions by specifying creation.

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

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

Provides explicit context: requires Pipeworx OAuth account (not for anonymous/BYO). Details type-specific parameters and delivery constraints (verification, daily cap). Does not directly contrast with pull-based alternatives but gives enough context for proper 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: it explains the output structure (category-bucketed examples) and that calling with no arguments gives a full spread, which is consistent 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 somewhat verbose, listing many example queries and categories in a single sentence. While front-loaded with key phrases, it could be more concise. However, it is well-structured and relevant.

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 all needed context: purpose, usage, output format, and when to use. It is complete and 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?

Schema coverage is 100% (parameter documented). The description adds meaning by explaining that topic is a focus area with examples (e.g., 'finance'), and omitting gives full spread. This is useful beyond the schema's field description.

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

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

The description clearly states the tool's purpose: it returns example questions categorized by topic, with tool+argument shapes. It explicitly distinguishes itself from siblings like ask_pipeworx and discover_tools as the onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains when to pass the topic argument. Provides clear guidance on how to use it vs. alternatives.

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

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

The description discloses key behaviors: ownership enforcement, that the row is deactivated (not deleted), and that historical events remain available via recent_alerts. These details go beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) and add valuable context for the agent.

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, highly efficient, and front-loaded. Every sentence adds essential information without redundancy.

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

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

Given the tool's simplicity (1 required param, no output schema, clear annotations), the description is complete. It explains the effect (deactivation), side-effects (historical data available), and ownership constraint. No additional information is needed for correct usage.

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

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

With 100% schema description coverage, the baseline is 3. The description only says 'Cancel a subscription by id', which echoes the schema. It does not add new meaning or clarify the format or constraints beyond what the schema already provides.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes itself from sibling tools like subscribe (which creates) and list_subscriptions (which lists). The verb 'cancel' is specific and appropriate.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), which serves as a usage guideline. It also implies when not to use (others' subscriptions) and references recent_alerts for historical data. However, it does not explicitly compare to other tools or state when not to use this tool beyond ownership.

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

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

Annotations declare readOnly, openWorld, idempotent. The description adds significant detail: two processing paths, return values (verdict, citation, reasoning), and replacement of multiple calls. 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 relatively long (6 sentences) but each sentence adds value. It front-loads with examples and then provides technical details. Could be slightly more concise.

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

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

Given the tool has 2 parameters, no output schema, and annotations present, the description provides complete context for an agent to use the tool: what it does, how it works, what it returns, and when to use it.

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

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

Schema coverage is 100%, but the description enriches both parameters with examples (claim) and behavior details (tolerance_pct default and usage). This goes beyond the schema alone.

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

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

The description clearly states the tool is for verifying factual claims, with explicit natural-language triggers. It distinguishes between financial and other claims but does not explicitly differentiate from sibling 'ask_pipeworx_grounded' or similar tools.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. However, it does not explicitly state when not to use it or mention alternative tools.

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