httpcat

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: default model, cost implications (free vs BYO key), and return structure (per-model scores, signals, raw_response, combined view). No contradictions.

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

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

Four sentences, front-loaded with purpose, no wasted words. Efficiently covers purpose, usage, parameters, and return format in a compact structure.

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

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

Given no output schema, description adequately explains return format (score, confidence, signals, raw_response per model + combined view). It covers default behavior, optional key, and context parameter. Sufficient for an agent to understand the tool's function and output.

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 4 parameters (100%). Description adds beyond schema by stating default model for 'models' parameter, explaining _apiKey is passed straight through, and suggesting use of 'context' to disambiguate. This extra context justifies a score above baseline 3.

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

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

Description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes from siblings like compare_entities and scan_competitor_ai_presence by focusing on per-model visibility scoring.

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?

Context of use is explicitly provided (AI-marketing audits, pre-launch brand checks, competitive monitoring). It explains default model and optional Anthropic key. While it doesn't explicitly list when not to use, the purpose is clear and the sibling list provides 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 false. The description adds value by explaining the routing mechanism ('routes the question to the right one of 3,775 tools'), argument filling, and output format with stable citation URIs. No contradiction.

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

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

The description is front-loaded with the key advice ('PREFER OVER WEB SEARCH') and is well-structured, but it is somewhat lengthy. Every sentence adds value, though a slightly more condensed version could achieve the same clarity.

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

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

Given the tool's complexity (routing to many tools) and lack of output schema, the description fully covers what the agent needs to know: how to use it, what it returns (structured answer with citations), and when to prefer it. No gaps.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description adds value through examples and clarification that the input is a natural language question, which goes beyond the schema's basic aliases. However, the schema already sufficiently defines parameters.

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

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

The description explicitly states 'Answer factual questions using authoritative structured data' with specific examples, clearly distinguishing itself from web search via 'PREFER OVER WEB SEARCH' and listing concrete question types (SEC filings, FDA data, economic stats, etc.).

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

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

Description explicitly tells when to prefer this tool over web search, provides a list of suitable topics, gives example queries, and implicitly suggests when not to use (non-factual or subjective queries). This meets the highest bar for 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?

Adds significant context beyond annotations: extra LLM call cost, routing behavior, extraction logic, and explicit refusal reasons. No contradictions with annotations (readOnlyHint, etc.).

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

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

Packed with information in a single paragraph, but front-loads key purpose. Slightly dense but efficient; no wasted sentences.

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

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

Despite no output schema, the description fully specifies return formats for success and failure, including refusal reasons and field names, making it complete for correct invocation.

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

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

Schema coverage is 100% with aliases documented. Description simply restates 'your question in natural language,' but schema already provides full detail. Baseline 3 is appropriate as no additional parameter insight is needed.

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

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

The description clearly states this is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, distinguishing it from ask_pipeworx with specific use cases.

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

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

Explicitly says to use when answers will be quoted/cited/acted on and facts must not be invented, and advises to prefer ask_pipeworx for casual lookups, providing clear when/when-not 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?

Despite annotations already signaling read-only, idempotent, and non-destructive behavior, the description adds immense behavioral detail: resolution pipeline, classifier enumeration, fan-out logic, response shapes (market_match_confidence, parent_event, news fallback fields), safety mechanisms (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and resolution-rule risk (cancellation_rule parsing). This far exceeds annotation coverage.

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

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

The description is lengthy but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose and gradually adds detail. While every sentence adds value, the density might overwhelm some agents; a more concise version could exist without losing essential guidance.

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

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

Given the tool's complexity (3 parameters, no output schema, many edge cases), the description is remarkably complete. It explains not only the default behavior but also error states (low confidence, closed markets), data shapes (market, analysis, evidence), and rare scenarios (cancellation rules, news fallback). This compensates fully for the missing output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds substantial context: for 'market' it explicitly accepts slug, URL, or question text; for 'depth' it contrasts 'quick' (2-3 sources) vs 'thorough' (full fan-out); for 'include_raw' it explains size implications and when to use. This extra guidance justifies above baseline.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies input types (slug, URL, question text) and the pipeline (resolve, classify, fan-out, return evidence). This uniquely positions the tool vs siblings like polymarket_edges or polymarket_arbitrage, which address different aspects of Polymarket analysis.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides numerous fan-out examples mapping bet types to data sources. However, it lacks explicit when-not-to-use guidance or alternatives among sibling tools, which would push it to a 5.

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

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

Beyond annotations (read-only, idempotent, etc.), the description adds behavioral details: parallel calls, handles off-calendar fiscal years, returns sorted results, and provides citation URIs. 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?

Well-structured with front-loaded examples, but slightly verbose. Could tighten phrasing without losing key 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?

Despite no output schema, the description covers return format (sorted, paired data, citation URIs) and handles edge cases (off-calendar fiscal years). Comprehensive 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%, but description enriches parameters: explains what data each type pulls (10-K metrics for company, FAERS counts for drug) and specifies input format (tickers/CIKs vs drug names) with constraints.

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 starts with specific example queries and clearly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from sequential lookups and details what data is retrieved for each entity type.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' provides examples of when to use (comparing, ranking), and specifies constraints (2–5 entities, one type).

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, openWorldHint, idempotentHint, and non-destructive. The description adds key behaviors: 15-60s execution time, returns gaps[] for unanswered facets, never invents facts, and requires authentication/paid plan. No contradiction with annotations.

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

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

The description is well-structured with front-loaded key benefits, but slightly verbose. Each sentence adds value, though some details (e.g., 'never invented') could be integrated more concisely.

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 and absence of output schema, the description thoroughly explains the return format (findings packet with citations, confidence, sources, gaps) and expected behavior. It fully prepares an agent for correct invocation.

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

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

Schema coverage is 100% for both parameters. The description adds meaningful context: explains depth values (quick=3, standard=5, thorough=8) and links 'thorough' to paid plans. It also clarifies that the question parameter supports broad/multi-part queries.

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

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

The description clearly states the tool performs 'Grounded multi-source research in ONE call', decomposes questions into sub-questions, and returns structured findings. It distinguishes itself from sibling tool ask_pipeworx by contrasting multi-step research vs. single 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 for broad/multi-part questions and names ask_pipeworx for single lookups. Also mentions prerequisites: Pipeworx account and paid plan for 'thorough' depth.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral details: returns top-N most relevant tools with full schemas and curated examples, ready to call directly. 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 concise with no wasted words. Front-loaded with main purpose, followed by usage context and return details. 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?

Given annotations cover safety, and no output schema, the description fully explains the tool's purpose, usage, and output format. It provides sufficient context for an agent to decide when and how 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 description coverage is 100%, so baseline is 3. The description does not add new parameter meaning beyond what schema provides (e.g., alias mentions are already in schema). Minimal extra value, but adequate.

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's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and distinguishes from siblings by being the tool for discovering available tools. The list of domains provides concrete context.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by examples. It also advises to call this FIRST when many tools are available, implying when not to use (i.e., when you already know 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: fans across multiple sources, returns specific fields, mentions patent soft-failure, provides URIs for filings. 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?

Description is a single paragraph but front-loaded with example queries. Every sentence is informative, but length is slightly high. Still, no repetition or fluff.

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

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

Given the tool's complexity and no output schema, description adequately explains return fields (CIK, filings, fundamentals, patents, news, LEI) and limitations (patent sunset, name unsupported). Covers all necessary context for the tool.

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

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

Schema descriptions are comprehensive (100% coverage). Description adds constraint that only 'company' type is supported, value must be ticker or zero-padded CIK, and names are forbidden. This adds meaningful context 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 provides a cross-source profile for US public companies, specifying sources like SEC, XBRL, USPTO, news, GLEIF, and returned fields. It distinguishes from siblings by instructing to prefer over chaining single-pack lookups and mentions sibling tool resolve_entity for name resolution.

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 (holistic view of a company) and when not to (for names only, must use resolve_entity first). Provides alternative for names and notes patents soft-fails until reactivated. Includes example queries to guide usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the destructive nature and idempotency. The description adds context by explaining why one might use it (clear sensitive data), which is consistent with annotations. No contradiction.

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

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

The description is extremely concise at two sentences, front-loaded with the core action. Every sentence adds value, with no unnecessary 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 simplicity of the tool (one required param, no output schema, clear annotations), the description provides sufficient information: action, usage guidelines, and related tools. It is complete for effective use.

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

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

The input schema covers the single required parameter 'key' with a description. The description adds 'by key' but does not provide additional meaning beyond the schema, such as how to obtain keys or format constraints. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key. It specifies the verb 'delete' and the resource 'memory', distinguishing it from siblings like remember and recall by mentioning pairing.

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 scenarios: when context is stale, task is done, or to clear sensitive data. It recommends pairing with remember and recall, offering guidance on related tools, but does not explicitly state when not to use.

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 read-only, idempotent, non-destructive behavior. The description adds context by explaining the extraction process (fetches page, extracts title/desc/links, outputs markdown) and the output format, 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 concise (three sentences), front-loaded with the primary purpose, and well-structured with no wasted words.

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

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

For a simple tool with two parameters and no output schema, the description covers what it does, how it works, and use cases comprehensively. No missing 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 coverage is 100% with clear descriptions for both parameters (url and max_links). The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and target AI crawlers. It distinguishes from siblings by its unique function of generating llms.txt files.

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, drafting for own project, auditing competitor) but does not explicitly state when not to use or mention alternatives, though none are obvious.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns an image URL, which is useful context. No contradictory or missing behavioral traits.

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 long, front-loading the action and resource, with no redundant words. 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?

For a simple tool with one parameter, thorough annotations, and an output schema, the description fully covers what the tool does and returns. No gaps.

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

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

Schema coverage is 100% and the description adds no additional meaning beyond what the input schema provides for the single parameter. It merely repeats the example values. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: getting a cat image for a given HTTP status code. The verb 'Get' and resource 'cat image representing an HTTP status code' are specific and unambiguous. No similar sibling tools exist, so no differentiation 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?

The description explains when to use the tool by providing an HTTP status code. It gives examples (200, 404, 500). However, it does not explicitly mention when not to use it or provide alternatives, but given no conflicting siblings, this 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 indicate readOnly, idempotent, and not destructive, so the description carries a lower burden. It adds value by disclosing that the tool returns descriptions and cat image URLs, which provides behavioral context beyond the safety profile.

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

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

The description is extremely concise, consisting of two sentences that directly state the purpose and usage. It is front-loaded with the action and waste-free.

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 parameters, documented output schema, and comprehensive annotations, the description fully covers the necessary context. It clearly states what the tool does and when to use it, making it complete for an agent.

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

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

The tool has zero parameters, so schema coverage is effectively 100%. The description does not need to add parameter details, and no parameter information is missing. A baseline of 4 is appropriate.

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

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

The description clearly states the tool lists all HTTP status codes with descriptions and cat image URLs, using specific verbs 'browse' and 'find'. It distinguishes itself from similar tools like get_status_cat by implying this is for browsing all codes while the sibling is for a specific one.

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

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

The description explicitly states when to use the tool ('to find the right code for your status or explore available options'), which is clear for this simple tool. While it does not mention alternatives or when not to use, the context of sibling tools like get_status_cat provides implicit distinction.

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. Description adds minor detail about returned fields but no additional 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 concise sentences: first states purpose and return fields, second gives usage 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?

Simple tool with one optional parameter and no output schema. Description adequately covers purpose, return data, and usage context. Lacks explanation of subscription concept but clear from sibling names.

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

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

Schema coverage is 100% for the single parameter include_inactive. Description does not add meaning beyond the schema, meeting baseline but not exceeding.

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 'List the caller's active subscriptions' and lists the returned fields. Distinguishes from sibling tools like subscribe/unsubscribe as a read operation.

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

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

Provides explicit usage scenarios: reviewing monitoring before adding more subscriptions or finding an id to cancel. Does not specify when not to use, but context is clear.

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

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

The description adds significant behavioral context beyond annotations: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also explains the impact ('signal directly affects roadmap'). This is excellent for an agent deciding to use the tool.

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

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

The description is succinct at five sentences, front-loaded with the core purpose. Every sentence adds unique value—scenarios, guidance, rate limits—with no redundancy or fluff.

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

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

Despite no output schema, the description covers the feedback lifecycle: submission, review cadence ('digests daily'), and influence on roadmap. It lacks explicit return format, but for a feedback tool, this is adequately complete.

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

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

Schema coverage is 100%, but the description adds value by advising to 'Describe the issue in terms of Pipeworx tools/packs,' which guides message content. The schema itself already has clear descriptions for type and message.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifically distinguishes between bug, feature/data_gap, and praise scenarios, making it distinct from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit usage scenarios ('Use when a tool returns wrong/stale data...') and includes negative guidance ('don't paste the end-user's prompt'). However, it does not explicitly contrast with alternatives, though the scenarios are clear enough to guide correct usage.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, and caching behavior (5min-1h depending on window). 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 4 sentences, well-structured with function first, then use cases, then implementation details. No fluff; 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, the description explains what is returned (top tools, top packs, total call volume) and mentions caching. For a simple aggregation tool, this is complete and 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?

Only one parameter (window) with enum and description in schema. The description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances 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 it returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, distinguishing itself from siblings like discover_tools and bet_research.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment with agent needs). While it lacks explicit 'when not to use' or alternatives, the given guidance is clear and actionable.

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

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

Annotations (readOnlyHint, idempotentHint) indicate safe, idempotent behavior. The description adds rich behavioral context: required arg out of two, similarity filtering, partition checks, fill-check step. 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 separate sections for modes, semantic anchor, partition filter, and fill check. Every sentence adds value, though some could be tightened without loss of clarity.

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

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

Given the tool's complexity (two modes, multiple checks), the description is thorough. It explains the algorithms, thresholds, response structure, and even references another tool for deeper fill risk analysis. No output schema, but the textual description of response is sufficient.

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

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

Schema coverage is 100% with basic descriptions. The tool definition adds significant meaning by explaining how each parameter is used (event slug examples, topic seed questions), and how they affect the analysis (single-event vs cross-event mode).

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 on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection with two specific modes (event and topic).

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

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

Explicit guidance is given for when to use event mode vs topic mode, with examples. It notes that calling with no arguments fails. It also references polymarket_fill_risk for custom sizing. While it doesn't list exhaustive when-not-to-use scenarios, 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?

The description goes far beyond the annotations, which already indicate a safe, read-only, idempotent tool. It explains caching behavior, response structure (by_segment with diagnostics), mathematical formulas for edge and Kelly, exclusion rules (Fed bets, gate conditions), and dependencies on external data sources. This provides complete transparency for an 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 lengthy and dense, covering models, response fields, and knobs. While every sentence adds value, it could be more concise without losing essential information. The structure is logical but not minimal.

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

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

Given the tool's complexity (9 parameters, no output schema), the description thoroughly explains the response format (by_segment, diagnostics, Fed section) and the meaning of each field. It leaves no critical gaps for an agent to interpret results.

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

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

All 9 parameters have descriptions in the input schema (100% coverage), and the tool description adds extra context for several, such as explaining why min_kelly does not filter partition arbs and when to adjust slippage. This adds meaningful 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage by detailing its unique model families and opportunity segments.

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 (discovering edge opportunities) and includes details on tradeable-edge knobs. However, it does not explicitly state when not to use it or directly compare with alternatives, though the context implies differentiation from related tools.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds rich behavioral details: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), decay computation on |edge_pp_net|, and limitations. No contradiction.

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

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

The description is dense yet well-structured: one-line summary, motivating question, args, response breakdown, and limits. Every sentence serves a purpose 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?

Despite no output schema, the description fully details the response fields (tracked, expired, snapshot_dates) with explanations. It covers purpose, usage, parameters, behavior, and limitations, making it complete for a complex tool.

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

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

Schema description coverage is 100%, but the tool description adds meaning: explains 'days' as lookback with default/clamp, 'window' as snapshot family with examples. This surpasses the schema's descriptions.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge longevity and distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical trends rather than current edges.

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

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

The description gives clear context: use it to differentiate between fresh and old edges. It mentions limits (60-day TTL, snapshot start date) but does not explicitly name alternatives or say 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?

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context: walks the ladder, returns fill details, warns about forced directional risk and partial fills. 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 long but well-structured with clear mode separation and bullet points. Some redundancy could be trimmed, but complexity justifies 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 complexity (two modes, many outputs, no output schema), description is very complete. Lists return fields for each mode, covers edge cases (thin legs, forced directional risk), and provides comprehensive guidance.

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

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

Schema coverage is 100%, but description significantly adds meaning: explains side defaults and auto behavior, size_usd interpretation for each mode (max spend vs target proceeds vs settlement notional), and clamping. Goes well 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' distinguishing two modes (single-market and basket). It is specific and distinguishes from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why it's necessary, including risks of partial fills and unhedged positions.

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 readOnly, idempotent, and non-destructive. The description adds significant behavioral context: compatibility_warning fires in two specific cases, temporal alignment flag, and skipped counters. This goes well beyond annotations to disclose edge cases and limitations.

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

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

The description is lengthy but well-structured with bold headings and clear sections for modes, response, and safety fields. Every sentence adds value, though a more bulleted layout could improve scanability. It is not overly verbose given the complexity.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety checks, no output schema), the description thoroughly explains inputs, behavior, and output fields. It covers return structure (raw probabilities, matched spreads, safety fields) and potential pitfalls, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by listing the exact topic shortcuts, explaining that explicit tickers override topic-mapped sides, and describing the interaction between parameters. This aids correct usage 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 computes the spread between Kalshi and Polymarket for the same question. It distinguishes two modes (topic shortcuts vs. explicit tickers) and describes the response structure. This differentiates it from sibling tools like polymarket_arbitrage (which is venue-internal) and polymarket_edges.

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

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

The description explicitly explains when to use topic shortcuts vs. explicit tickers, and details safety fields that warn when spreads are not meaningful (compatibility_warning, temporal_alignment). However, it could more directly state 'use this when you need cross-venue spreads' and contrast with alternatives 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?

Annotations declare readOnlyHint true and destructiveHint false. Description adds scoping details and the behavior of omitting the key argument. No contradictions. Could mention response format or error handling, but sufficient.

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

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

Two sentences, front-loaded with the main action. Every sentence adds value with no redundancy. Efficiently covers core function, examples, scoping, and pairing.

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?

Complete for a simple retrieval tool with one optional parameter and annotations. The description explains what the tool does, when to use it, and how it interacts with siblings. Missing output format details, but reasonable given simplicity.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description reinforces that omitting key lists all keys and provides usage context beyond the schema.

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

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

The description uses specific verbs 'retrieve' and 'list' with clear resources ('value saved via remember', 'all saved keys'). It distinguishes from siblings by explicitly naming 'remember' and 'forget' in context.

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

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

Describes when to use: 'to look up context the agent stored earlier' and provides examples. Mentions scoping and pairing with remember/forget. However, does not explicitly state when not to use or compare to other retrieval tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: mark_read flags events read, and the feed is persisted. 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?

Four sentences with front-loaded purpose. Every sentence adds value without redundancy. Structure is clear and efficient.

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

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

Despite no output schema, description states return fields (source, citation_uri, raw payload). All 5 parameters covered with behavior. Annotations provide safety context. Complete for intended use.

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 examples ('sec_8k' for type, ISO timestamp for since) and explains mark_read's effect, going beyond schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It mentions return fields (source, citation_uri, raw payload) and distinguishes from the GET endpoint 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?

Explicitly says 'Polls work fine' and provides alternative endpoint for scripts/dashboards. Explains mark_read behavior for controlling what appears next, giving clear context on when to use this tool.

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

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

Beyond annotations, the description discloses the tool's fan-out behavior to multiple sources, fallback from GDELT to GNews, USPTO API sunset status, and that it soft-fails. It also describes the output structure including changes[], total_changes, and citation URIs. 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 slightly verbose but every sentence adds value. It is front-loaded with examples, uses clear structure, and efficiently conveys complex behavior. Minor verbosity prevents a perfect score.

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

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

Given the tool's complexity (multiple sources, fallback, parameter details, and output description) and the absence of an output schema, the description is complete. It explains input parameters, behavior, output format, and even acknowledges limitations (USPTO soft-fail).

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

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

With 100% schema coverage, the description adds significant value beyond the schema by explaining the 'since' parameter with both ISO date and relative shorthand examples, recommending typical values, and clarifying that 'value' can be a ticker or CIK. It also explains that 'type' only supports 'company'.

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 a change feed for companies, listing multiple natural language query examples and specifying the data sources (SEC, GDELT/GNews, USPTO). It explicitly distinguishes itself from the sibling tool entity_profile, which is for static profiles.

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

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

The description provides explicit guidance on when to use this tool versus entity_profile, stating 'Use entity_profile instead when you want the static profile'. It also gives example queries and recommends typical monitoring windows like '30d' or '1m'.

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

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

Description adds value beyond annotations: scoped by identifier, authenticated persistence vs 24-hour anonymous retention, and idempotent nature (store key-value). No contradiction with annotations; fully transparent.

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

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

Three sentences, front-loaded with purpose, then usage, then details. No waffle; every sentence serves a purpose.

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

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

For a simple 2-param tool with no output schema, the description covers purpose, usage, behavioral traits, and pairing with siblings. No gaps.

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

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

Schema covers 100% of parameter descriptions, but description adds naming conventions (e.g., 'subject_property') and value types (findings, addresses). Enhances beyond bare schema.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, with concrete examples (resolved ticker, address, preference). It distinguishes from sibling tools recall and forget, making 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 tells when to use ('when you discover something worth carrying forward') and mentions paired retrieval/deletion tools. No explicit when-not, but the context and examples imply boundaries. Adequate guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description doesn't need to cover safety. It adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups,' informing the agent of potential latency or multi-step operation.

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

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

The description is well front-loaded with examples and clearly structured. At ~140 words, every sentence contributes value. A slight trim could be possible, but it is still efficient and easy to parse.

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

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

Despite no output schema, the description fully explains return values for each entity type (including citation URIs), covers input formats, and positions the tool as the first step. It is complete for a lookup tool with rich annotations.

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. The description adds significant meaning beyond the schema by providing concrete input examples (ticker, CIK, name for 'company'; brand/generic name for 'drug') and specifying return fields for each type, helping the agent format parameters correctly.

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 starts with concrete examples (e.g., 'What's the ticker for…') and clearly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It uses a specific verb+resource and hints at its place in the workflow ('Use FIRST whenever you have a name but need an ID'), distinguishing it from siblings like entity_profile that consume IDs.

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 FIRST whenever you have a name but need an ID' and enumerates supported types with details on what each returns. While it doesn't explicitly state when not to use or name alternatives, the context is clear enough that an agent can infer the appropriate scenario.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density, which is 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?

Three sentences, front-loaded with the core action, no wasted words. Every sentence adds essential information.

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

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

Given no output schema, description explains return format (ranked list with score, confidence, signal density). Sufficient for a read-only tool to be used correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that first entity is treated as subject for narrative, which is not in schema, providing additional semantic value.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, ranks them, and returns a ranked list. Distinguishes from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (likely general comparison).

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

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

Explicitly gives a use case (competitive AI-marketing audits) and implies when to use (multiple entities). Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details like partial failures and bundlephobia's measurement delay (5-30s), and lists return structure. 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 concise but dense; it packs multiple details into two sentences. Front-loaded with purpose. Could be improved with bullet points for readability, but still clear and 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?

Despite no output schema, the description enumerates all returned fields (summary block, advisory details, links, alternative versions) and explains partial failure behavior. Provides sufficient context for an agent to understand what to expect.

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 does not add extra meaning beyond schema; it mentions version defaults and scoped packages, which are already in schema. No missing parameter context.

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

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

The description clearly defines the tool as a composite check for npm packages, specifying exactly what it evaluates (deps.dev and bundlephobia data). It distinguishes itself from siblings by stating it's for 'should I add this npm package' queries and notes limitations to NPM ecosystem.

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: whenever an agent asks about safety, popularity, or size cost. Also provides alternatives for non-NPM ecosystems (deps.dev:version). This gives clear when-to and when-not 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?

Discloses technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. Mentions character offsets for verification. No contradiction with annotations (which declare readOnly, openWorld, idempotent, non-destructive).

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?

One paragraph with clear flow: purpose, use case, technical details. Every sentence is informative with no redundancy.

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

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

Covers purpose, usage, technical implementation (embeddings, windows), limitations (truncation), and output features. Adequate for an agent to decide invocation without additional context.

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

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

All 3 parameters have schema descriptions (100% coverage). Description adds value: explains that text is 'already pulled', query is natural-language, and limit is implied as top-N. Mentions output features (offsets, similarity scores) not in schema (no output 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 'Semantic search INSIDE a fetched record', specifying the verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching whole documents.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' Provides alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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?

Adds significant behavioral details beyond annotations: SMS cap of 10/day, webhook auto-disable after 10 failures, HMAC signing for webhooks, and that the webhook secret is returned only once. Annotations declare idempotentHint true, but description does not explicitly confirm idempotency behavior. 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?

Dense but well-organized: opening sentence, authentication note, type list with examples, then delivery channels. Slightly verbose in delivery details but all information earns its place. Could be tightened by grouping SMS/email/webhook constraints.

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

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

For a tool with 3 parameters, nested objects, no output schema, and moderate complexity, the description covers all critical aspects: authentication, type-specific parameters, delivery options with constraints, and expected return (subscription ID). No gaps evident.

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 greatly enriches meaning by providing concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topic) and detailed delivery object semantics including webhook signing algorithm and auto-disable condition.

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?

Explicitly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. Clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and listing specific subscription types.

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

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

Provides explicit usage context: requires a Pipeworx OAuth account, states that anonymous and BYO cannot persist subscriptions. Lists supported types with examples and delivery constraints (SMS cap, webhook auto-disable). However, does not explicitly contrast with sibling tools for when to use this versus list_subscriptions or other monitoring tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns 'each with the exact tool + argument shape that answers it', which is a notable behavioral trait beyond annotations. 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 well-structured with trigger phrases first, then purpose, behavior, and usage. It is slightly lengthy but every sentence adds value. Could be marginally 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's simplicity (one optional parameter, rich annotations), the description is complete: it covers what the tool does, when to use it, what it returns, and how to vary the output. No gaps are apparent.

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

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

With 100% schema coverage, the description adds meaning by listing example values for topic ('finance', 'pharma', etc.) and explaining the effect of omission vs. providing a topic. This enriches the schema definition.

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 the tool as the onboarding entry point for new agents, specifying that it returns category-bucketed example questions with exact tool+argument shapes. It distinguishes from sibling tools like ask_pipeworx by stating its role as a first-use discovery mechanism.

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 for you' and explains two usage modes: omit topic for full spread or pass a specific topic to focus. Lacks explicit when-not-to-use but provides clear context for appropriate invocation.

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

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

Annotations declare non-read-only, idempotent, and non-destructive. The description adds that deactivation (not deletion) preserves historical data, which is valuable behavioral context beyond annotations. 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?

Two sentences, front-loaded with action ('Cancel a subscription by id.'), no waste. Every sentence contributes meaningful information.

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

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

For a simple tool with one required param and no output schema, the description fully explains behavior, ownership, and consequences. Annotations provide safety and idempotency hints, making the description complete.

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

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

Schema covers the single parameter 'id' with clear description. The tool description adds no further semantic value beyond restating 'by id', but schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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 mentions ownership enforcement, guiding the agent to only cancel own subscriptions. It also notes historical events remain accessible via 'recent_alerts', providing context for post-cancellation behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so description doesn't need to cover safety. It adds value by detailing output components (verdict, structured form, actual value with citation, percent delta) and the data sources used, exceeding annotation coverage.

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

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

Description is well-structured and front-loaded with purpose and usage examples. While it is somewhat lengthy, each sentence contributes meaningful information and is organized logically. Minor redundancy could be trimmed but overall 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?

For a tool with a single required parameter and no output schema, the description adequately explains the return values (verdict types, actual value with citation, delta) and data sources. It does not detail error scenarios or all possible verdict conditions, but is sufficiently complete for typical use.

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

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

Schema description coverage is 100% and the schema already describes the 'claim' parameter well with examples. The tool description does not add significant new information about the parameter beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool verifies natural-language claims against authoritative sources, with specific examples of query patterns. It distinguishes itself from sibling tools by focusing on fact-checking and claim verification, and explicitly mentions it replaces multiple sequential calls.

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

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

Provides clear guidance on when to use ('whenever the agent needs to check factually correctness') and includes examples of input patterns. Limitations are given (v1 supports company-financial claims via SEC EDGAR + XBRL), but does not explicitly state when not to use or suggest alternative tools.

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