Interpro

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

Annotations already declare read-only/idempotent, and description adds behavioral details: default model is free Workers AI, Anthropic requires BYO key with direct payment, and returns structured per-model results (score, confidence, signals, raw_response). 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?

Three sentences, front-loaded with the core action and output, followed by model option and use cases. No filler; formatting highlights key terms.

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 specifies the return structure and use cases, and given strong annotations plus full schema coverage, no significant gaps remain for selecting and invoking 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 already describes all 4 params, and description supplements with the default model selection, the meaning of `_apiKey` (BYO, direct billing), and clarifies `context` as disambiguation. This adds value beyond the schema, though schema was already strong.

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 tool probes one or more LLMs and scores visibility 0-100, naming specific resource types (business/brand/product/topic) and outcome (per-model score). This distinguishes it from sibling tools like ask_pipeworx that answer questions, while the mention of AI visibility makes the purpose explicit.

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 concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and optional Anthropic probing. Does not explicitly name sibling alternatives or exclusions, but the context is sufficient to know when 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds significant behavioral context beyond that: it routes to sub-tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and claims 'one fast call'. These are non-obvious traits that materially affect how an agent should invoke and handle 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 relatively long but information-dense. It is front-loaded with the key directive ('PREFER OVER WEB SEARCH'), then provides use-case categories, examples, and alternative guidance. Every sentence contributes value, though a slightly tighter structure could be even more scannable. It earns a 4 for being purposeful and well-organized.

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

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

Given the tool's complexity (a router over thousands of sources), the description is remarkably complete. It explains the core mechanism, gives concrete examples, provides clear usage boundaries, names alternatives, and even mentions the output format (structured answer with citation URIs). This is more than sufficient for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% and the schema itself provides a clear description of the main 'question' parameter plus all aliases. The tool description adds no further parameter-level information; it only shows examples of questions. Since the schema already does the heavy lifting, a 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 the tool as a question-answering router that pulls from 5,334 tools across 1,393 verified sources. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point. The verb 'routes' plus resource specification makes the purpose unmistakable.

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

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

The description is explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and whenever users ask factual questions with phrases like 'what is', 'look up', 'find', etc. It also names specific alternatives (ask_pipeworx_grounded, deep_research) with the exact conditions for stepping up, making the decision criteria unambiguous.

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

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

Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds valuable behavioral context: the beta/experimental nature, the live candidate mechanism, the current state (no candidate active), and the assurance that it is a full working router rather than a fallback. It also notes the shared response shape with ask_pipeworx. 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 uses four sentences, each serving a distinct purpose: identity (beta universal router), current state (no candidate active), usage guidance (use like ask_pipeworx for newest routing), and clarification (full working router). It is slightly verbose but contains 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?

Given the tool's complexity (router over 5,334 tools) and lack of output schema, the description covers the essentials: what it does, scope, current behavior, and relationship to the stable sibling. The reference to 'same response shape' as ask_pipeworx provides output expectations indirectly. It could be more explicit about return format, but the pointer to a known sibling makes it 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% and all 6 parameters are aliases for 'question', each with clear descriptions. The description adds no parameter-specific detail beyond saying 'same arguments' as ask_pipeworx. Since the schema fully documents parameters, the baseline of 3 applies; the description doesn't need to compensate.

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 a beta version of ask_pipeworx, a universal router with 5,334 tools and the same arguments/response shape. It explicitly differentiates itself from the stable ask_pipeworx sibling by being the experimental edge with candidate routing improvements. The verb+resource ('universal router') 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?

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also clarifies that results are compared against the stable router to decide what merges, and states there is currently no active candidate, so it behaves identically to ask_pipeworx. This gives the agent clear when-to-use context relative to the sibling.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that it routes to other tools, fills arguments, and uses only the tool result to extract answers. It also enumerates refusal reasons and notes the extra LLM call cost, adding significant behavioral context without contradicting annotations.

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

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

The description is front-loaded with the core purpose, then describes mechanics, return format, usage guidance, and cost tradeoff. Each sentence contributes distinct value without redundancy, making it efficient for its complexity.

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

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

With no output schema, the description thoroughly explains the return object ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and failure modes. It also covers the routing behavior and cost tradeoff, giving an agent enough context to invoke it correctly in high-stakes scenarios.

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

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

The schema fully documents the 'question' parameter and its aliases (100% coverage). The description does not add further parameter specifics but implies the question is a natural-language query. Baseline of 3 is appropriate since schema carries the semantic load.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' that extracts answers using only tool results, distinct from its sibling ask_pipeworx. It specifies the behavior, return shape, and relevance for high-stakes reads, unambiguously differentiating it.

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

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

It explicitly says to use when answers will be quoted, cited, or acted on, and to prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This provides both when-to-use and when-not-to-use guidance with a named alternative.

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

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

The description goes far beyond annotations, disclosing fan-out parallelism, response shapes, resolver contract semantics (market_match_confidence, market_match_score, alternatives), safety short-circuiting, market_closed_or_inactive status, illiquid spread warnings, and resolution-rule risk parsing. This is rich behavioral context that annotations alone (readOnly, idempotent, non-destructive) do not cover. 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 extensive but carefully structured with clear uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Every sentence introduces new behavioral information; none are redundant. While lengthy, the complexity of the tool justifies the length, and the main purpose is front-loaded in the first sentence.

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

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

With no output schema, the description must fully explain return values, and it does: result.market fields, analysis shape, evidence keying, resolver contract fields, parent_event structure, news fallback semantics, safety/blocking states, and cancellation-rule risk. Given the tool's high complexity and many edge cases, this description is exceptionally complete; an agent can reliably anticipate what will come back and how to interpret it.

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

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

Schema coverage is 100% with each parameter described in the input schema, giving a baseline of 3. The description adds extra value by explaining the practical implications of depth (quick vs thorough sources) and include_raw (response size trade-offs), as well as giving examples of acceptable market strings. This goes beyond bare schema descriptions and helps agents select appropriate values.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the specific resource (Polymarket market), the action (research with data fan-out), and distinguishes itself from siblings like polymarket_edges by focusing on evidence gathering and market-vs-model comparison. The explicit use-case examples ('should I bet on X', 'what does the data say about Y') further anchor its unique role.

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

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

The description gives explicit 'Use for' scenarios and multiple concrete examples of when to invoke the tool. It also explains behaviors like low-confidence matches and closed-market handling, which guide appropriate usage. However, it never explicitly names sibling tools as alternatives or states when not to use this tool, so it misses the highest bar for exclusionary guidance.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This adds significant behavioral context and does not contradict annotations.

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

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

The description is dense but every sentence earns its place: trigger phrases, usage preference, data source details, sorting behavior, and return format. It is front-loaded with query patterns for immediate recognition, and despite its length, it contains 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 complexity (two entity types, multiple data sources, sorting) and absence of an output schema, the description adequately explains what data is pulled, how results are sorted, and the return format (paired data + citation URIs). It provides enough context for an agent to select and use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds valuable context: type='company' maps to specific financial metrics and type='drug' to adverse-event and trial counts, plus examples for the values array. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, using trigger phrases like 'Compare X and Y' and 'head to head'. It distinguishes itself from sibling tools by focusing on multi-entity comparison rather than single lookups.

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

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

Explicitly instructs to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and notes it replaces 8–15 sequential lookups. This provides clear when-to-use guidance and points to the alternative (sequential lookups), though it doesn't name specific 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?

Beyond the annotations (readOnly, non-destructive, idempotent), the description discloses account/auth requirements (free tier vs paid thorough plan), parallel execution across 5,334 tools, full return packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), semantic excerpting behavior, timing expectations (15-90s), and the fact that it never invents data. This is rich behavioral context far exceeding 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 long but densely packed with necessary operational detail. It front-loads the critical account requirement and immediately distinguishes from open-web search. A few redundancies exist (e.g., gap recovery and contradiction scan are described both in the depth parameter schema and the main description, and 'NOT open-web search' is repeated), but each sentence generally contributes unique value for a tool of this complexity.

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

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

Given the tool's complexity and lack of an output schema, the description fully compensates: it explains the findings packet structure, the gaps[] mechanism, contradictions[], hop field, citation_uri semantics, handling of large records via semantic excerpting, timing, auth tiers, and when results will be empty. There is no meaningful behavioral or output aspect left unexplained.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining how depth values translate to facet counts (quick=3, standard=5, thorough=8) and the behavioral consequences (gap-recovery hop, contradiction scan, iterative lead-chasing). It also clarifies that 'question' should be natural language and broad/multi-part is acceptable.

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-resource pairing: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call' and explains the tool decomposes questions into facets, routes to parallel tools, and returns a findings packet. It clearly distinguishes this from open-web search and from sibling ask_pipeworx, making the purpose unmistakable.

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

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

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking/current-news topics 'prefer ask_pipeworx' because deep_research returns empty gaps. It also gives depth-level guidance (quick/standard/thorough) tied to question complexity, leaving no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat safety traits. It adds valuable behavioral context: returns top-N tools with full schemas and 'ready to call directly, no second schema lookup needed,' which clarifies the output and immediate usability. This goes beyond the structured annotations.

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

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

The description is composed of four efficient sentences, each adding distinct value: core purpose, usage scenarios, output format, and priority guidance. It is front-loaded with the main verb and resource, and there is no redundant or irrelevant content.

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

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

For a simple discovery tool with a well-documented schema, the description fully covers the tool's role, output, and usage context. It explains what the return value looks like (top-N tools with schemas) even in the absence of an output schema, and it appropriately positions the tool within the broader tool ecosystem (call first when exploring options).

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 schema already provides rich descriptions for 'query' with examples and alias definitions. The tool description lists many domains, which gives context for valid query topics but doesn't add syntax or format details beyond what the schema already provides. No extra parameter-level semantics are introduced.

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

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

The description explicitly states the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It also lists the domains it covers (SEC filings, FDA drugs, etc.) and clearly differentiates itself from sibling tools by positioning itself as a discovery gateway rather than an analysis tool. The title 'Discover Tools' reinforces this purpose.

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

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

Provides explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This also implies when not to use (when you want a specific answer), giving clear context for tool selection.

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

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

Annotations already establish read-only, idempotent, non-destructive safety, but the description goes further by detailing fan-out across sources, specific return fields, URI formats, patent soft-failure, GDELT→GNews fallback, and the requirement for ticker/CIK input. This is consistent with annotations and adds behavioral context beyond the structured fields.

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

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

Although long, every sentence carries necessary operational detail: examples, exclusive preference guidance, source fan-out, return field summaries, fallback logic, and input constraints. It is densely packed with useful information and avoids redundancy, making it an efficient and well-structured description.

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

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

With no output schema, the description fully compensates by enumerating the return payload (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and providing specifics like 'up to 5 filings,' 'LATEST 10-K,' and the patent API sunset. It also covers edge cases (soft-fail, fallback, name rejection) and thus is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for both parameters, so the baseline is 3. The description adds value by giving concrete examples ('AAPL', '0000320193'), explaining the zero-padded CIK format, and reiterating the 'names not supported' constraint with a pointer to resolve_entity. This slightly exceeds the schema's own descriptions.

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

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

The description opens with concrete example queries and then states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates from siblings like resolve_entity (name resolution) and compare_entities (comparison) by focusing on holistic, aggregated profiling.

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 chaining single-pack SEC/XBRL/news lookups' for holistic requests and warns that names are not supported, directing to 'use resolve_entity first if you only have a name.' It also notes the patent API sunset and fallback behavior, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior. The description adds 'Keyless' (no authentication required) and explicitly states the return shape (accession, name, type), which is valuable given the lack of an output schema. It does not contradict the annotations.

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

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

The description is concise and front-loaded. The main action is stated first, followed by the return format, use case, and a note on authentication. Each sentence is informative and there is no filler.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, return fields, authentication, and functional context. It does not mention potential limitations (e.g., what happens if the accession is invalid), but given the simplicity and annotation support, it 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?

The schema already provides full coverage for the single parameter 'uniprot' with an example. The description reiterates the same example and clarifies the role as an accession for a protein, but adds no new semantic detail beyond what the schema already states.

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

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

The description clearly states a specific verb and resource: 'List all InterPro entries (families, domains, sites) found on a given UniProt protein'. It also specifies the lookup method (UniProt accession) and the return contents (accession, name, type), making it distinct from sibling tools like search_entries or get_entry.

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 this tool is appropriate: 'Useful to functionally annotate a protein' and 'Complements UniProt/AlphaFold'. However, it does not explicitly exclude alternative tools or mention when not to use it, so it stops short of full guidance with 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 destructiveHint=true and idempotentHint=true. The description adds context about the types of memories to delete (stale, task-complete, sensitive) and implies it only affects previously stored data. No contradiction with annotations, and the additional nuance about sensitive data is valuable.

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 plus a short pairing note. It is front-loaded with the action and usage, with no filler or redundant 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?

For a simple one-parameter tool with annotations covering destructiveness and idempotency, the description is complete. It covers usage cases, pairing, and the nature of the operation. The lack of an output schema is acceptable for a delete operation, and the description does not need to explain return values. Minor gap: it doesn't explicitly state behavior for missing keys, but idempotentHint implies safe repetition.

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 fully covers the single parameter 'key' with description 'Memory key to delete' and an example. The description mentions 'by key' but does not add deeper semantics about key format, naming conventions, or deletion behavior on missing keys. Baseline 3 is appropriate since schema coverage is 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?

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from sibling tools like remember and recall by focusing on deletion. The action is unambiguous and not a tautology.

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

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

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pairing with remember and recall, which helps the agent understand the tool's role in the memory workflow.

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?

With annotations already declaring readOnly/idempotent/non-destructive, the description adds the fetch behavior ('Fetches the page'), extraction step, and output format. This is valuable context beyond annotations and does not contradict them.

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

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

Three sentences with distinct roles: purpose, process/output, and use cases. Front-loaded and free of filler.

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

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

For a 2-param tool with no output schema, the description explains input (any URL), process (fetch/extract/emit), output (text blob ready for site-root), and use cases. It is sufficient but could mention edge cases like URL accessibility or error handling.

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

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

Schema coverage is 100%, with both url and max_links described in the schema. The description adds no new parameter-specific semantics beyond noting that it extracts 'key links,' which loosely relates to max_links.

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'), names target AI crawlers, and explicitly distinguishes from siblings by focusing on file generation rather than scanning or visibility checks.

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

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

The 'Useful for' list provides clear scenarios (client indexing, own project, competitor audit), giving explicit when-to-use context. However, it does not name alternative tools or exclusions, so it stops short of fully 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 cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond these annotations by specifying the exact return fields (name, type, description, counters, GO terms) and the 'Keyless' access requirement, which is valuable operational information. It doesn't conflict with any annotation.

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

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

The description is compact and front-loaded: the first sentence names the action and target, the second lists return contents, the third gives usage context, and the fourth notes keyless access. Every sentence adds value, with no redundancy.

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

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

For a single-parameter lookup tool with no output schema, the description is complete: it states what the tool does, what it returns, when to use it, and a key access constraint. The annotations cover safety and idempotency, so no additional behavior disclosure is required.

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 provides full coverage of the single parameter (accession) with an example and type. The description echoes the example and notes it's for a single entry but doesn't add substantive semantic details (e.g., regex format, case sensitivity). Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's specific purpose: fetching full details for a single InterPro entry by accession. It distinguishes from related tools like search_entries and entries_for_protein by emphasizing it retrieves comprehensive details for one known entry, rather than searching or listing.

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 after search_entries or entries_for_protein to learn what a family/domain actually is,' giving clear context for when to use this tool versus alternatives. No exclusions are needed beyond this because the tool's role is well-scoped.

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 read-only, idempotent, and non-destructive. The description adds useful context about caller scoping, the 'active subscriptions' default filter, and the exact returned fields, which is valuable behavioral detail beyond the annotations.

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

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

Two concise sentences front-load the purpose and then provide essential details about return fields and use cases. Every sentence earns its place with no redundant wording.

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

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

For a simple one-optional-parameter read-only list tool, the description and schema together cover scope, output shape, and intended usage. The annotations cover safety, and no output schema is needed given the explicit field list.

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

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

The only parameter, include_inactive, is fully documented in the input schema with a default value. The description does not mention it, but because schema coverage is 100%, the baseline score of 3 applies.

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

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

The description uses a specific verb-noun pair ('List the caller's active subscriptions') and clearly distinguishes this read-only tool from mutation siblings like subscribe and unsubscribe. It also specifies the resource scope and enumerates return fields, making the purpose unmistakable.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This implies when to use it versus subscribe/unsubscribe, though it does not name an alternative tool explicitly.

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?

With annotations all false and providing no safety or side-effect hints, the description fully discloses behavioral traits: 'Rate-limited to 5 per identifier per day,' 'Free; doesn't count against your tool-call quota,' and 'The team reads digests daily and signal directly affects roadmap.' This gives the agent concrete knowledge about limits and impact beyond what annotations offer.

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

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

The description is three sentences, front-loaded with the core purpose, then usage triggers, then key constraints. Every sentence provides value, no filler or repetition of schema 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 feedback tool with one enum and a nested optional context object, the description covers purpose, when-to-use, content guidelines, rate limits, and quota impact. No output schema is needed for a feedback tool, and the description is self-sufficient given the rich schema descriptions.

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

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

Schema coverage is 100% with detailed descriptions for type, context, and message, so baseline is 3. The description adds extra guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and reinforces the type enum terms (bug, feature/data_gap, praise), elevating it to a 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' giving a clear verb (tell), resource (Pipeworx team), and purpose (feedback). It distinctly separates this from siblings like ask_pipeworx or research tools by focusing on reporting issues/praise rather than retrieving information.

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 lists when to use the tool: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a negative guideline ('don't paste the end-user's prompt'). However, it doesn't name alternative tools or explicitly state when not to use feedback in favor of another tool, so it falls short of a perfect 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds meaningful context: no PII, aggregate (pack, tool, count) data, derivation from CF analytics-engine, and caching behavior varying by window. This goes beyond the annotations.

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

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

The description is front-loaded with the core return information and uses a brief bulleted list for use cases. While slightly verbose, it is well-organized and each sentence contributes to understanding the tool's function and applicability.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers return contents, window semantics, privacy (no PII), aggregation details, and caching. It is fully self-contained for an agent to invoke correctly.

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

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

The schema provides 100% coverage for the single optional 'window' parameter with enum values and per-window semantics. The description supplements this by noting that cache duration varies by window, adding a behavioral nuance not present in the schema.

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

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

The description clearly states the tool returns aggregate trending data (top tools, top packs, total call volume) over configurable windows, distinguishing it from sibling tools like discover_tools and recent_alerts. The verb 'returns' is specific and the resource is precisely defined.

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 lists three concrete use cases (discovering hot data sources, confirming canonical tools, alignment checking) which imply when to use. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a full 5.

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

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

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by detailing the internal checks (partition-sum >3pp, Jaccard similarity ≥0.30, placeholder filters) and the critical fill-check caveat: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This level of nuance is essential for safe use and is fully consistent with the annotations.

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

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

The description is dense and information-rich, but it is somewhat long and could benefit from clearer paragraph separation. Each sentence does contribute unique value—mode guidance, semantic anchors, partition filter, fill check—so it avoids fluff. The use of ALL CAPS section headers aids scanning, earning it a 4 rather than a 3.

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

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

With no output schema, the description fully compensates by detailing the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and the event-mode partition_check fields. It also explains the fill-check pricing mechanism and its interpretation. This is a complex tool, and the description leaves little ambiguity about its operation and 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?

Although the schema already provides 100% parameter coverage, the description adds substantial meaning. It explains that 'event' triggers a child-market walk and partition_check, while 'topic' performs a cross-event search with semantic anchoring. Concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and the mode-specific output structures give the agent a deeper understanding of how each parameter changes behavior.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges (which focuses on edges) and polymarket_fill_risk (which handles fill risk), ensuring the agent knows exactly what this tool does.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It even recommends event mode for a specific market and explains how cross-event mode catches patterns single-event misses. It also directs users to polymarket_fill_risk for custom sizing, effectively stating when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes far beyond: it details model families, edge calculation net of slippage, Kelly caps at 0.25, the 24h-move warning, tradeable-edge knobs, partition arb Kelly behavior, diagnostics funnel, and 1h KV caching. This is exceptionally 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?

The description is long but information-dense, with a logical flow from purpose to segments to knobs to response structure and caching. Every sentence earns its place, though the 'FIVE MODEL FAMILIES' claim lists only four families (crypto_price, news_momentum, partition_overround, longshot_basket), a minor inaccuracy that forces the reader to reconcile.

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 9 parameters, no output schema, and a complex response structure, the description fully covers what the agent receives: by_segment segmentation, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), diagnostics for empty segments, and caching behavior. This is complete enough for an agent to invoke confidently without additional discovery.

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 critical context for each knob: slippage assumptions (20-50bp typical), min_partition_leg_kelly 'why parent-level Kelly is 0 by design,' and how min_liquidity/max_spread_pp drop unrealizable edges. This exceeds the schema descriptions significantly.

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+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage (arbitrage between markets) and polymarket_edge_tracker (tracking edges over time).

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

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

Explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when Fed signals are excluded and why. However, it does not explicitly contrast with alternative tools (e.g., 'use polymarket_arbitrage for pure cross-market arb'), so it falls short of full 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?

Beyond the annotations (read-only, idempotent), the description enriches the agent's understanding with detailed response semantics: tracked[] includes full time-series, trend classification, decay computation on absolute edge, signed edge_pp_net convention, expired[] with lifespan, snapshot_dates[] with gap reasons, and limits (60-day TTL, daily closes not intraday). This goes far beyond the annotations and makes the tool's behavior predictable.

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 structured into clear sections (Args, RESPONSE, LIMITS) and front-loads the purpose. While it is longer than the calibrated high example, the tool's complex time-series output and edge-case explanations justify every sentence. No fluff, but it could be tightened slightly.

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 (no output schema, two params, rich telemetry), the description is remarkably complete. It explains each output field, the meaning of trend values, the sign convention, why snapshots might be missing, and the practical interpretation of median lifespan. This covers all information an agent would need to invoke and interpret results correctly.

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

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

The schema already fully documents both parameters: days with lookback and default/clamp, window with allowed families. The description's Args section mostly restates this (default 14, max 30, default 1wk) without adding deeper meaning. With 100% schema coverage, the baseline is 3, and the description does not meaningfully elevate parameter understanding.

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 'Edge persistence and decay telemetry' and clarifies the purpose with 'Answers "how long has this edge existed and is it shrinking?"'. This clearly identifies a specific analytical capability that distinguishes it from sibling tools like polymarket_edges (which presumably shows current edges). The verb-like framing and resource (edge snapshots) make the purpose unambiguous.

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

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

The description provides clear context on when to use the tool: when you need edge persistence/decay telemetry rather than a fresh snapshot. It even gives a practical example (a 3-week-old wide edge vs a fresh one) and warns about data gaps and TTL limits. However, it does not explicitly name alternatives or state 'don't use this for current edge values', so it stops short of full 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?

The description discloses internal behavior: 'walks the ladder' and returns a verdict (clean|degraded|cannot_fill), per-leg fill detail, thin_legs[], and forced_directional_risk. It warns about partial fills converting arbs into unhedged directional positions, which is meaningful behavioral context beyond what annotations (readOnlyHint, idempotentHint) already state. 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 every sentence carries operational significance—mode distinctions, size interpretation, output enumerations, and risk warnings. It is front-loaded with the core purpose and uses clear mode headings. Some clauses are dense, but for a tool with two distinct modes and many return fields, the length is warranted, and there is 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?

With no output schema, the description compensates by listing all major return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers prerequisites (one of market or event) and explains the risk scenario that motivates the tool, making it contextually complete for an agent to decide and invoke it appropriately.

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 all 4 parameters at 100%, the description adds crucial semantic nuances: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional — shares per leg, each paying $1' in basket mode. It also explains the default basket side auto-selection based on partition sum, adding value beyond the schema's parameter descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource combination that immediately distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges. It explicitly names both modes (single-market, basket) and enumerates the specific outputs returned in each mode, making the tool's purpose unmistakable.

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

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

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clearly explains when to use single-market vs basket mode ('REQUIRES one of market or event') and defines the side and size semantics for each mode. No alternative tools are mentioned, but the decision context is concrete.

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 details behavioral traits beyond the readOnlyHint and other annotations: two modes, response structure, compatibility_warning logic with two distinct cases, temporal alignment field, and skipped_cross_type counters. This far exceeds the annotations, explaining exactly when and why results may be unreliable or meaningless.

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 comprehensive but verbose, running several hundred words. It is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), but the level of detail, particularly around skipped_cross_type subtypes, could be trimmed without losing essential meaning.

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

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

Despite the absence of an output schema, the description thoroughly covers return values, edge cases, safety fields, and practical limitations, making it self-sufficient for an agent to understand 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 already documents all three parameters, but the description adds critical semantic context: the topic parameter auto-fetches matching events via pre-mapped shortcuts, explicit tickers override the topic-mapped side, and the response semantics (spread direction Kalshi - Polymarket). This adds meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explicitly noting when bet shapes are non-equivalent.

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

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

The description provides clear context on two usage modes (topic shortcuts vs explicit tickers) and includes a strong caveat that most pre-mapped topics currently return compatibility warnings, implying when NOT to rely on the tool. However, it does not explicitly compare against alternative tools like polymarket_arbitrage, so it stops short of a full when-to-use vs alternatives 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the special behavior of omitting the key parameter to list all keys. 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 at three sentences, each earning its place: first states the primary action, second provides a use case, third covers scoping and companion tools. It is front-loaded with the action verb and avoids redundancy with structured 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?

For a simple tool with one optional parameter, the description is complete: it covers both invocation modes (retrieve a key, list all keys), gives concrete use examples, explains scoping, and mentions companion tools. No output schema is present, but the return type is implicit from 'Retrieve a value' and 'list all saved keys', which is sufficient for this complexity.

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

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

Schema description coverage is 100%, so the parameter is fully documented in the input schema. The description adds real-world examples of key values (user's target ticker, address, prior research notes) and reinforces the 'omit to list all' behavior, which goes slightly 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 a specific verb 'Retrieve' and clearly identifies the resource ('a value previously saved via remember') and the alternative action ('list all saved keys'). It distinguishes itself from sibling tools like remember, forget, and get_entry by explicitly referencing 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?

The description states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names companion tools and their relationship ('Pair with remember to save, forget to delete'), 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?

The description discloses a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This implies a persistent state change, which directly contradicts the annotation readOnlyHint=true, which claims the tool is read-only. This is a serious annotation contradiction.

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

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

The description is three sentences long, front-loaded with the primary action, and includes essential details without fluff. It also adds an alternative endpoint, which is useful and 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?

The description explains the return structure (source, citation_uri, raw payload), filtering, mark_read behavior, and even mentions polling and an alternative HTTP endpoint. With no output schema, this is a complete picture. Minor omission: no mention of limit/unread_only, but schema covers those.

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

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

The description adds concrete meaning beyond the schema by giving examples like filtering by type (e.g., 'sec_8k') and since with ISO timestamp, and explaining the behavioral effect of mark_read on subsequent calls. The schema covers all parameters, but the description enriches the key ones.

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' and details that it returns the most recent alerts with source, citation_uri, and raw payload. This distinguishes it from siblings like list_subscriptions and recent_changes, which serve different purposes.

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 context by noting 'Polls work fine' and points to an alternative HTTP endpoint at registry.pipeworx.io/alerts.json for scripts and dashboards, giving a clear alternative method. It doesn't explicitly exclude other tools, but it gives enough context for when to use this tool.

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

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

The description reveals specific behavioral traits beyond the readOnlyHint, including fan-out to SEC EDGAR, GDELT→GNews fallback with conditions, and USPTO patent soft-failure due to API sunset. It clearly states the return format (structured changes[], total_changes, citation URIs), adding significant transparency not present in annotations.

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

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

The description is dense but well-structured, leading with concrete user phrases, then explaining data sources, parameter formats, and return objects, all in a compact block. Every sentence adds value—there is no filler or redundancy, making it highly efficient for an AI agent 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?

Given the absence of an output schema, the description compensates by explicitly listing the return structure (changes[], total_changes, citation URIs) and the fallback logic. It also covers all required inputs, the supported entity type, and provides an alternative tool reference, making the description fully self-contained for effective tool invocation.

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

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

While the input schema already covers all three parameters (100% coverage), the description enriches them with practical examples and guidance: `since` accepts ISO dates or relative shorthand, `value` can be a ticker like 'AAPL' or zero-padded CIK, and `type` is restricted to 'company.' It also advises typical usage like '30d' for monitoring, surpassing 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 identifies the tool as a change feed for a company over a specified time window, using natural-language examples like 'What's new with X' and 'updates on Acme.' It explicitly distinguishes itself from the sibling entity_profile tool by noting the latter provides static profiles regardless of window.

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 instruction on when to use the tool (e.g., for 'latest on Y' or 'what happened to Z'), and directly suggests an alternative (entity_profile) when a static profile is needed. It also explains the `since` parameter with recommended formats like '30d' or '1m', giving clear usage direction.

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 write, idempotent, and non-destructive behavior. The description adds crucial context beyond those hints: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions (24-hour retention), and the companion tools for retrieval and deletion. 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?

Three sentences, each earning its place: purpose + usage, storage semantics + retention, companion tools. Front-loaded with the core action, followed by when-to-use and contextual details. Zero 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 two-parameter write tool with no output schema, this description is complete. It covers storage semantics, persistence, scoping, retention, and integration with sibling tools. No significant gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100% with both parameters described and examples provided. The description adds semantic value by explaining the key-value relationship and scoping ('Stored as a key-value pair scoped by your identifier'), which reinforces how the parameters relate. This goes slightly beyond the schema's individual field descriptions, though the schema already carries most of the burden.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It distinguishes from siblings by naming complementary operations: 'Pair with recall to retrieve later, forget to delete.' This clearly sets it apart from memory retrieval and deletion 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 when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)...' This tells the agent exactly when to invoke the tool. It also names sibling tools recall and forget as complementary alternatives for later stages.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses detailed behavior: the exact output fields per entity type, the data sources (SEC EDGAR, RxNorm), citation URIs, accepted input forms, auto-disambiguation, and the internal cascade of lookups. This gives the agent a clear mental model of what happens when invoked.

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 earns its length by packing in essential details for two entity types. It is front-loaded with conversational examples and a clear usage directive, then structured by entity type. Every clause contributes, though a bit more brevity would tighten it.

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 entity types, multiple input forms, varied outputs) and the absence of an output schema, the description thoroughly covers return values, data sources, and behavior. Combined with rich annotations and full parameter descriptions, the agent has everything needed to select and invoke this 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?

Although the schema already has 100% description coverage, the tool description adds significant value by explaining how each parameter behaves in context—e.g., that 'value' can be a ticker, CIK, or name for companies, with auto-disambiguation, and what the returned fields will be. This goes beyond the schema's terse descriptions.

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

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

The description opens with concrete user phrases and clearly states the tool's purpose: resolving a user-spoken name to the canonical identifier required by other tools. It explicitly differentiates from siblings by positioning itself as the go-to when you have a name but need an ID, and it outlines two specific entity 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?

It gives an explicit directive 'Use FIRST whenever you have a name but need an ID,' which is clear when-to-use guidance. It does not name specific alternative tools for when not to use it, though the phrase 'other tools require as input' implies its role relative to other tools. It also notes that it replaces 2-3 manual lookups, providing practical context.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral detail: it explains that each entity is probed with ai_visibility_check, results are ranked by score, and the output includes most/least recognized entities. This provides transparency about internal mechanics and output structure beyond the annotations.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence adds value. It avoids redundancy with the schema and annotations, making it concise 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?

The tool has no output schema, so the description appropriately explains what is returned ('ranked list with score, confidence, signal density per entity'). It covers the core functionality, usage context, and internal behavior. Minor gaps like explaining 'signal density' or error handling are not critical for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so all parameters are already well-documented. The description adds some context (e.g., 'your brand + N competitors' for entities), but this is marginal since the schema already explains the parameter roles. No additional parameter semantics are needed beyond what the schema 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 tool compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare') and resource ('AI visibility'). It differentiates from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking, making its purpose unambiguous.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example query, indicating when to use the tool. It does not explicitly state exclusions or name alternatives (e.g., for single entity use ai_visibility_check), but the context strongly implies this is for multi-entity comparisons.

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, idempotent, and non-destructive. The description adds valuable behavioral context: composite fan-out to external services, bundlephobia's first measurement may take 5-30s, partial failures degrade gracefully with sources_failed listing timeouts, and NPM-only scope. No contradiction with annotations.

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

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

The description is information-dense and well-structured. Every sentence serves a purpose: purpose, usage triggers, return fields, ecosystem scope, and failure behavior. It is front-loaded with the main use case and does not waste 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?

Even without an output schema, the description lists all returned fields, explains latency and timeout behavior, and scopes the tool to NPM. This fully equips an agent to invoke the tool correctly and interpret results, making it contextually 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 description coverage is 100%, documenting 'package' as an npm package name with scoped package examples and 'version' with default-to-latest behavior. The description adds no new parameter-specific information beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool is a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It specifies a distinct verb+resource and differentiates from sibling tools by noting NPM-only scope in v1.

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 triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also tells when NOT to use it—for non-NPM ecosystems—and points to deps.dev:version directly as the alternative.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds valuable context beyond annotations: return fields (accession, name, type, member databases), the type enum, and the fact that it is keyless. No contradictions.

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

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

Three concise sentences: purpose, context, and return format. No filler, front-loaded with the main verb and resource. The background on InterPro is brief and useful for context.

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

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

For a simple search tool with two well-documented parameters and no output schema, the description is quite complete. It lists the return fields and keyless requirement. It lacks explicit alternative routing, but that is covered by usage guidelines.

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 meaning by clarifying that the query searches over 'entry names/accessions', which is not explicitly in the schema description. This helps the agent understand the semantic scope of the query 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 specifies a clear verb+resource+scope: 'Search InterPro for protein families, domains, repeats and functional sites by keyword'. It distinguishes from siblings like get_entry (specific entry lookup) and entries_for_protein (protein-centric) by emphasizing keyword text search over entry names/accessions.

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 clearly implies when to use this tool: when searching by keyword rather than by accession or protein. It also notes 'Keyless' for accessibility. However, it does not explicitly name alternatives or exclusions, so it lacks explicit 'when-not-to-use' guidance.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses concrete behavior: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation, and return format with offsets and similarity scores. This adds substantial value and shows no contradiction with annotations.

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

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

The description is dense but front-loaded with purpose, and every sentence contributes new information—usage scenario, return format, pairing, and technical details. No filler or redundancy.

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

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

Even without an output schema, the description fully discloses return values (passages, offsets, similarity scores) and limitations (truncation at 200K chars). Combined with the annotations, the agent has enough context to invoke and interpret results correctly.

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

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

Schema coverage is 100% with thorough parameter descriptions, so the baseline is 3. The description only adds minor context (e.g., 'text you already pulled') without introducing new parameter semantics or examples beyond the schema.

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

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

The description opens with a specific action 'Semantic search INSIDE a fetched record' and resource, clearly distinguishing it from siblings like ask_pipeworx_grounded. It names the exact scenario and what the tool returns, making its purpose unambiguous.

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

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

Provides explicit guidance: 'Use when the record is too big to cram into the prompt' and explains the pairing with ask_pipeworx_grounded for grounded retrieval. This clearly communicates when to use 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?

The description discloses important requirements (OAuth, phone verification, SMS caps, webhook auto-disable) beyond the annotations, but it contradicts the idempotentHint=true annotation by promising 'Returns the new subscription id', implying every call creates a distinct subscription. This is a direct annotation contradiction.

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

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

The description is a single dense paragraph but front-loaded with the main action and then consistently organized by type and delivery channel. Concrete examples and caveats justify the length, though bullet points would improve scannability.

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—three subscription types with nested parameters, multiple delivery channels, and no output schema—the description covers auth requirements, channel behaviors, rate limits, verification steps, response format, and failure handling. It is sufficiently complete for correct tool invocation aside from the idempotency contradiction.

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 100% description coverage, so the baseline is 3. The description reinforces schema details (e.g., items:['5.02'], min_spread_bps, phone verification) without adding genuinely new parameter semantics beyond what the schema already explains.

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 'Create a proactive monitoring subscription to a live-data event stream', giving a specific verb (create), resource (subscription), and domain (live-data event stream). It distinguishes the tool from siblings like list_subscriptions and unsubscribe by clearly stating it creates a new subscription.

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 clearly states when to use the tool (to monitor types like sec_8k, polymarket_edge, fred_series) and prerequisites (Pipeworx OAuth account). However, it does not explicitly mention when not to use it or point to alternatives such as recent_alerts for one-off pulls, so it lacks exclusions.

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

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

Annotations already declare it read-only and non-destructive, so the description adds context about output nature (category-bucketed example questions, drawn from the live catalog) and the topic parameter's effect. This goes beyond the annotations and provides valuable behavioral detail 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 a single dense paragraph, but it is well-organized: purpose, output, calling convention, and when-to-use guidance. Every sentence contributes value, though it could be slightly tighter. It earns a 4 for being information-rich without being bloated.

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

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

There is no output schema, so the description must explain return values, and it does: 'Returns category-bucketed example questions... each with the exact tool + argument shape.' It also explains the optional topic parameter and the 'use first' context. With simple parameters and strong annotations, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the topic parameter's purpose and adds examples ('finance', 'pharma', 'betting') and 'Omit for a cross-category spread,' but these do not add significant meaning beyond the already detailed schema description. No additional parameter semantics are provided.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape that answers it. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the 'use first' tool for learning what Pipeworx can do, with specific verb and resource.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and names alternatives (ask_pipeworx, entity_profile, compare_entities). It also provides calling guidance: call with no arguments for full spread or pass topic to focus. This fully covers when and how 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?

An annotation does not exist for the 'deactivate vs delete' semantics, and ownership enforcement is not captured in the schema or annotations. The description provides crucial behavioral context: the row is deactivated (not deleted), ownership is checked, and historical events remain available via recent_alerts. This exceeds what the readOnlyHint/idempotentHint annotations imply.

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 short sentences, front-loaded with the primary action and then the key constraints and side effects. Every word earns its place; there is no redundant phrasing or filler.

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

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

For a single-parameter tool with no output schema and good annotations, the description covers the core purpose, ownership rules, and non-destructive side effects. It even ties to recent_alerts for historical events. No significant missing information detracts from completeness.

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

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

The schema already documents 'id' as 'Subscription id (uuid) returned by subscribe.' The description adds the ownership constraint ('you can only cancel your own subscriptions'), which is critical to understanding that the 'id' must belong to the caller. This goes beyond the schema's parameter description and justifies a score above the baseline of 3.

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

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

The description 'Cancel a subscription by id' uses a specific verb and resource (subscription) with an explicit identifier. It clearly distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by stating the cancellation action. Ownership enforcement further refines the scope.

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: ownership is enforced, so only the user's own subscriptions can be canceled. It also clarifies the non-destructive nature ('deactivated, not deleted') and its relationship to 'recent_alerts.' However, it does not explicitly name alternative tools or state when not to use it, missing the full '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?

Beyond the annotations, the description discloses the dual-path execution (SEC EDGAR fast path vs. grounded pipeline), the specific verdict types, the inclusion of a pipeworx:// citation, and that it replaces 4-6 sequential calls. This adds substantial behavioral context about what happens internally and what the user can expect, exceeding the safety-only info from annotations.

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

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

The description is a single dense paragraph that front-loads usage examples and clearly explains the tool's function. It is efficient in that every sentence contributes to understanding, but it is longer than strictly necessary, containing some redundancy in the claim verification phrasing.

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

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

Despite lacking an output schema, the description fully explains the return values (verdict, actual value, citation, reasoning), covers the two routing paths, and clarifies the scope of claims handled. This gives an agent all necessary context to decide when and how to invoke the tool, making it comprehensive for its complexity.

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

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

The input schema already provides thorough descriptions for both parameters (claim examples and tolerance_pct behavior), achieving 100% coverage. The description text mentions tolerance-related math concepts but does not add meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with specific verbs like 'fact check' and 'verify the claim' and provides concrete examples. It distinguishes itself from sibling tools by focusing on judging factual correctness against authoritative sources, which is a unique function among the listed siblings.

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 whenever the agent needs to check whether something a user said is factually correct,' giving a clear usage context. It explains the internal routing for company-financial vs. other claims, effectively describing when this tool is the right choice, though it does not name alternative tools or provide explicit when-not-to-use scenarios.

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