Hal Fr

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

Annotations already mark the tool as read-only and idempotent. The description adds behavioral detail: it uses Workers AI by default and passes a user-supplied _apiKey to Anthropic, with the user paying directly for those calls. This discloses external API usage and cost implications, adding value beyond the annotations. No contradiction.

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

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

Three dense sentences with no filler. It front-loads the core purpose, then covers configuration, return format, and use cases efficiently. 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 no output schema, the description specifies the returned per-model structure ({score, confidence, signals, raw_response}) plus a combined view. It also covers default behavior, optional key, and practical applications, making it complete for a 4-parameter tool.

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

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

The input schema covers all 4 parameters at 100% coverage. The description reinforces semantics by noting that omitting models yields just workers-ai and that _apiKey is only needed for Anthropic, clarifying the relationship between models and _apiKey. This adds useful context beyond the schema.

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

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

The description uses the specific verb 'Probe' and clearly states it queries one or more LLMs to score visibility (0-100) per model. It distinguishes from sibling tools like search or ask_pipeworx by focusing on AI-model awareness and scoring. The scope (business/brand/product/topic) is 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?

The description provides clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model versus optional Anthropic probing. It does not explicitly name alternatives or exclusion criteria, but the context is sufficient for an agent to select 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. The description adds valuable behavioral context: routing across thousands of sources, filling arguments, returning structured answers with citation URIs, and working across tiers. It goes beyond annotations by describing the aggregation and routing behavior, though it does not detail failure modes or limitations.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and structured with domain lists, trigger phrases, examples, and strategic guidance about alternatives. Every sentence earns its place; despite length, it is dense with actionable information 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?

For a complex routing tool with no output schema, the description is quite complete: it covers scope (current/historical data, authoritative sources), output (structured answer with citations), operational notes (one fast call, works on every tier), and distinctions from siblings. It lacks explicit error handling or edge-case behavior, but overall provides strong context.

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

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

Schema description coverage is 100%, with the 'question' parameter already described as accepting natural language and aliases. The description adds examples and trigger phrases but does not introduce new parameter-level semantics. Baseline 3 is appropriate since the schema handles the parameter meaning.

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

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

The description clearly states what the tool does: 'Routes the question to the right one of 5,354 tools across 1395 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It is specific and distinguishes from siblings like ask_pipeworx_grounded and deep_research by naming them as alternatives.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with clear alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). It includes trigger phrases and examples, making when-to-use versus alternatives unambiguous.

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

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

The description adds significant behavioral context beyond the annotations: it reveals that the tool may have live routing improvements enabled during tests, that behavior can change over time (with a specific retirement date example), and that it is a full working router rather than a stub or fallback. This is valuable transparency about volatility and current state, which the annotations (readOnly, openWorld, idempotent, non-destructive) do not convey.

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

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

The description is concise but includes specific details (5,354 tools, retirement date, current state) that are relevant to usage and transparency. It is front-loaded with the core identity ('Beta version of ask_pipeworx') and all sentences contribute value. It could be slightly shorter, but the structure is logical and efficient.

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

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

Given no output schema, the description references 'same response shape' as ask_pipeworx, which provides a baseline for expected return values but relies on familiarity with the sibling tool. It covers purpose, usage, current behavior, and evaluation context, which is nearly complete for a complex router tool. A minor gap is not describing the response format independently, but the reference to ask_pipeworx fills this partially.

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

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

The input schema covers all 6 parameters with descriptions, including the 'question' field and five aliases, so schema coverage is 100%. The description does not add further parameter-specific semantics beyond stating 'same arguments' as ask_pipeworx, which adds little. Since the schema fully documents the parameters, a baseline score of 3 is appropriate without additional description contributions.

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, an identical universal router with the same 5,354 tools, arguments, and response shape. It distinguishes itself from the main ask_pipeworx by being the experimental edge with candidate routing improvements, and also implicitly differentiates from ask_pipeworx_grounded by its universality. The verb 'ask' and resource 'Pipeworx' are implied, and the scope is precisely stated.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide what merges, and notes that currently no candidate is active so it matches ask_pipeworx exactly. This gives clear context for choosing this tool over alternatives, including the experimental nature and evaluation purpose.

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?

Goes far beyond annotations by disclosing the extra LLM call cost, the refusal mechanism with specific refusal_reason enums, and the guarantee of using ONLY tool result content. Also specifies return structure including evidence verbatim quote. No contradiction with readOnly/openWorld/idempotent annotations.

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

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

Every sentence serves a distinct purpose: definition, routing/mechanism, success return, refusal return, use cases, cost comparison. The description is front-loaded with the core concept and structured logically, with 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?

Despite no output schema, the description fully specifies return values and refusal reasons. It covers when to use, how it routes, what it returns, and how it differs from siblings. For a complex tool with 6 parameters and rich behavior, 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% with all six parameters documented as aliases for 'question'. The description adds no extra parameter-level semantics beyond what the schema already provides, which meets the baseline but does not elevate above it.

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

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

The description provides a specific verb+resource: it's a 'hallucination-resistant answer mode' that routes like ask_pipeworx but grounds answers strictly in tool results. It clearly distinguishes from sibling ask_pipeworx by explaining the grounded extraction mechanism and the extra LLM call cost.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also gives an exclusion: 'prefer ask_pipeworx for casual lookups' due to extra cost. This directly addresses alternatives.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is well covered. The description adds the 'free-text query' behavior, which is a useful non-obvious trait not captured in the schema or annotations, though it remains minimal.

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

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

The description is extremely concise and front-loaded, using a short phrase that conveys the core function without any redundant information. It earns full marks for efficiency.

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

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

Given the tool's simplicity, rich annotations, and presence of an output schema, the description is minimally adequate. However, it does not differentiate this lookup from many similar sibling tools, and it lacks details about when to use it or what 'free-text' entails, leaving some gaps for an agent relying solely on the description.

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 only 50% (the 'rows' parameter has a description, but 'query' does not). The description's mention of 'free-text query' provides some semantic context for the otherwise undocumented query parameter, but it does not fully compensate for the coverage gap or add details about acceptable formats or 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 states a specific verb ('lookup') and resource ('author'), clearly identifying the tool's function as author retrieval. It is more specific than generic sibling tools like 'search' or 'get', but does not elaborate on what constitutes an 'author' or the exact scope, so it stops short of a 5.

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?

No guidance is provided on when to use this tool versus alternatives such as 'search', 'resolve_entity', or 'entity_profile'. The description lacks any indications of preferred scenarios, exclusions, or relationships to sibling tools.

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

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

Annotations declare readOnlyHint=true, which aligns with the description's research-only premise. Beyond annotations, the description discloses numerous behavioral traits: low-confidence short-circuit status, closed-market blocking, illiquid wide-spread warnings, cancellation-rule parsing, and news fallback details. This far exceeds the baseline.

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

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

The description is exceptionally long and dense, with many section headers and examples. It is structured logically (purpose, usage, classifiers, fan-out, response shapes, resolver, safety), but it is over-specified and could be shortened without losing core meaning. It fails the 'every sentence earns its place' test due to redundancy in fan-out examples.

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 the lack of an output schema, the description is remarkably complete. It covers return shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution-rule risk. An agent can confidently anticipate behavior in edge cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add some context (e.g., examples of market input, depth semantics, include_raw size implications), but these are already covered in the schema descriptions. No significant additional meaning is 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools (e.g., polymarket_edges, polymarket_arbitrage) by focusing on single-bet research with fan-out to data packs, and provides usage examples.

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

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

Explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't name direct alternatives or when-not-to-use, the context clearly signals when this tool is appropriate relative to other research 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?

Description goes beyond the readOnlyHint annotation by detailing data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). This rich context fully discloses behavior 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?

While dense, every sentence adds value: trigger phrases, usage mandate, data source details, and output format. The structure front-loads the most critical information and uses examples and line breaks effectively, with 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?

With no output schema, the description compensates by specifying return content ('paired data + pipeworx:// citation URIs'). It covers input constraints, data provenance, sorting, and scope, making the tool fully understandable for a complex comparison operation.

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

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

The input schema already covers both parameters with descriptions and examples. The description adds meaningful semantic detail by explaining what each 'type' value does (company vs drug) and the nature of the data pulled, going 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 defines the tool as a side-by-side comparison of 2–5 companies or drugs in one parallel call, using specific verb phrases like 'compare' and 'rank'. It distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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

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

The description provides explicit trigger examples ('Compare X and Y', 'X vs Y', 'rank these companies') and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. This gives clear when-to-use guidance and names an alternative approach to avoid.

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

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

The description discloses extensive behavioral traits beyond the annotations: account/auth requirements, depth-specific execution (gap recovery, lead chasing), latency expectations, return packet structure (verbatim evidence, confidence, citation_uri, gaps[], contradictions[]), semantic excerpting rather than head-truncation, and the fact that it never invents data. It provides a complete behavioral picture without contradicting 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 packed with high-value information and no filler, but it's a long, dense single paragraph that mixes account requirements, use-case guidance, internal mechanics, and latency expectations. It earns its place sentence-by-sentence, but the lack of structure makes it harder to scan. Slightly above average, but not the cleanest for such 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?

For a tool with no output schema, the description thoroughly explains the return packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field) and covers authentication, usage boundaries, depth semantics, and expected latency. This is complete enough for an agent to select and invoke it correctly and interpret results.

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

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

The input schema already provides 100% coverage of both parameters with detailed descriptions (question, depth enum explaining quick/standard/thorough behaviors). The description reiterates some of this but adds minimal new parameter semantics, mostly mentioning the paid plan constraint on 'thorough' and overall timing. Thus the description adds little beyond the schema, warranting a baseline 3.

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

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

The description clearly states that deep_research performs grounded multi-source research across Pipeworx's structured data sources in a single call, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from open-web search and names ask_pipeworx as an alternative for single lookups, making its unique purpose clear.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to (single lookups, breaking/current news), naming ask_pipeworx as the alternative. Also notes that deep_research returns empty gaps for topics not in the structured catalog, giving clear selection guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain the output format and self-containedness.

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 a single sentence but every part serves a purpose: a summary, a usage trigger, a domain list, and a return-format clarification. It is front-loaded with the key verb 'Find tools.' The list of domains is a bit extensive but informative for an agent deciding whether to call this tool.

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

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

For a discovery tool with 6 parameters and no output schema, the description covers the essential context: what it does, when to use it, what it returns (including that results include full schemas), and that it's a first-step tool. It doesn't discuss pagination or error handling, but those are not critical for this tool's simplicity. The rich description compensates for the missing output schema.

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

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

Schema coverage is 100%, and the schema already documents all parameters including aliases. The description adds minimal new meaning—'describing the data or task' aligns with query, and 'top-N' hints at the limit parameter—but does not significantly enhance what the schema already provides. It stays at baseline.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings by explaining it returns a set of tools rather than a single answer. The phrase 'Call this FIRST' reinforces its unique role as a discovery meta-tool.

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

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

Explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It does not explicitly name alternatives or say 'don't use this for X,' but the context is clear enough to guide selection.

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

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

The description reveals substantial behavioral detail beyond the annotations: it fans out across multiple sources in parallel, returns specific fields (up to 5 filings with pipeworx URIs, latest 10-K fundamentals sorted by period_end), mentions the USPTO PatentsView API sunset and soft-fail behavior, and notes the GDELT→GNews fallback for news. These are non-obvious traits that help an agent anticipate results and failure modes.

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

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

The description is long, but it is densely packed with necessary information: examples, purpose, source fan-out, return structure, and parameter constraints. It is front-loaded with relatable query examples and is reasonably efficient given the tool's complexity. It could be improved with bullet points, but every sentence contributes substantive 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?

Since there is no output schema, the description thoroughly explains the return payload, including specific fields (cik, company_name, recent_filings with accessions, fundamentals, patents, news, LEI) and their caveats. It also covers edge cases like unsupported names and soft-failure of patents, making it well-suited for an agent to invoke the tool without needing external documentation.

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

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

The input schema already provides 100% coverage, with detailed descriptions for both parameters including enum constraint and the ticker/CIK format restriction. The description largely restates this information ('Pass ticker "AAPL" or zero-padded CIK "0000320193"'), adding no new semantic meaning beyond the schema. A baseline score of 3 is appropriate because the schema does the heavy lifting.

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

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

The description is explicit and specific: 'full cross-source profile of a US public company in ONE parallel call.' It lists concrete sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, clearly distinguishing it from sibling tools like resolve_entity or compare_entities. The opening examples ('Tell me about X', 'research Acme') immediately convey the intended use case.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells when not to use it: names are not supported, and advises to 'use resolve_entity first if you only have a name.' This directly addresses alternatives and prerequisites.

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 minimal context by specifying deletion target ('memory') and mechanism ('by key'), but no additional behavioral details like reversibility or error cases.

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

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

Two clear sentences: the first states the core action, the second provides usage cues and related tools. No superfluous content; front-loaded and efficient.

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

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

For a one-parameter delete operation, the description covers purpose, usage, and complementary tools. Annotations provide safety and idempotency. Lacks mention of return behavior or error cases, but not critical for such a simple 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 fully describes the 'key' parameter (100% coverage). Description mentions 'by key' but adds no new format, access, or lifecycle information beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb, resource, and mechanism. It distinguishes from sibling tools remember (store) and recall (retrieve) by focusing specifically on deletion.

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 triggers: stale context, completed task, clearing sensitive data. Mentions pairing with remember and recall, but lacks explicit when-not cases or direct alternative naming.

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, idempotent, and non-destructive behavior. The description adds valuable process detail: it fetches the page, extracts key elements, and outputs a single text blob in llms.txt format. This gives the agent a clear mental model of the tool's behavior and output, going beyond the annotation hints.

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

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

The description is three sentences long, front-loaded with the core action, followed by a brief process breakdown, and ends with practical use cases. There is no redundant information or jargon, making it highly scannable and efficient.

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

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

The description fully covers the tool's behavior, including what it does (fetches, extracts, emits), the output format (a text blob ready for site-root/llms.txt), and typical use cases. With annotations providing safety hints and the schema covering parameters, the description is complete for an agent to select and invoke this tool 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?

The input schema describes both parameters (url, max_links) with clear descriptions and defaults, giving 100% schema coverage. The description adds no extra parameter-specific details beyond the schema. Since the schema already handles the semantics, 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 begins with a specific verb-resource pair: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes itself from sibling tools by detailing the exact process: fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. This is a unique function not implied by any other tool name.

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

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

Explicitly lists three concrete use cases: indexing a client's site, drafting one's own project, and auditing a competitor's AI visibility. This provides clear context for when to reach for this tool. However, it does not explicitly name alternative tools or provide 'when not to use' guidance, so it falls just short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds that it returns a single document rather than a list, which is minor context. 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 a single sentence with no unnecessary words. It is front-loaded and perfectly concise for the tool's simplicity.

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

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

Given the tool's simplicity, one parameter, strong annotations, and an output schema, the description is complete enough. It could mention error behavior, but that's often covered by schema; thus it does not feel lacking.

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 explicitly mentions 'by HAL id,' which directly explains the hal_id parameter's meaning. Even though schema description coverage is 0%, the description compensates by identifying the parameter's purpose clearly.

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

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

The description clearly states the tool retrieves a single document by HAL id, which is a specific verb+resource and differentiates from search-like tools. However, it doesn't explicitly name alternative tools or contrast 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 implies usage when you have a HAL id and want one document, but it doesn't provide explicit guidance on when not to use it or alternatives to consider. It is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is known. The description adds value by disclosing that only active subscriptions are returned by default and enumerating the response fields, giving the agent a concrete expectation of the output.

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

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

The description is two sentences: the first states purpose and output fields, the second gives usage guidance. Every word earns its place, with no redundancy or filler.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers what the tool does, what it returns, and when to use it. It could mention pagination or call scope (caller-only) more explicitly, but the core context is sufficient.

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

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

Schema coverage is 100% for the single parameter include_inactive, which is fully described. The description adds no additional parameter-specific semantics beyond the schema baseline, so a score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), distinguishing it from sibling subscribe/unsubscribe tools.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to call the tool, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations are neutral (all false), so the description carries the burden. It discloses rate limiting (5/day), cost (free, no quota), and roadmap impact. It also gives content formatting guidance. Not everything is disclosed (e.g., whether a confirmation is returned), but for a feedback tool, the added context is strong.

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

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

Every sentence serves a purpose: purpose, when-to-use, content guidelines, team read cadence, rate limit, and cost. It is information-dense but not bloated, with the most important details front-loaded. No wasted words.

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

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

For a low-complexity feedback tool with no output schema, the description covers all necessary context: what to submit, how to structure it, constraints, and downstream impact. The sibling tools are all query/research, so this description clearly delineates its role. The lack of return-value explanation is acceptable given the simple nature.

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 (e.g., type enum with meanings). The description adds value by explaining the feedback categories and emphasizing message specificity ('1-2 sentences typical'), plus the 'Don't paste end-user prompt' rule. This goes beyond the schema, earning a 4.

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

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

The description opens with a clear action verb ('Tell the Pipeworx team') and specifies the resource (feedback about broken/missing/needed tools). It distinguishes this tool from siblings by explicitly framing it as feedback rather than a query/research tool, with concrete use cases listed.

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: bugs, feature/data gaps, and praise. It also advises against pasting end-user prompts and explains the team's digest/roadmap impact. It lacks an explicit 'when NOT to use' or alternative tool, but given the unique purpose, the guidance is sufficient.

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 adds valuable behavioral traits: it notes the data comes from 'CF analytics-engine', contains 'no PII', and that results are 'cached 5min-1h depending on window'. This enriches the agent's understanding without contradicting 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 compact and well-structured: a one-sentence purpose, a bulleted list of use cases, and a final sentence on aggregation and caching. Every sentence contributes, and no irrelevant details are included.

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 no output schema, the description covers the essential aspects: what it returns, when to use it, how the data is sourced, and caching behavior. The output isn't detailed as a schema, but the description lists the return components ('top tools, top packs, and total call volume'), which is sufficient for an agent to understand the outcome.

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 single parameter 'window' is fully described in the input schema, including enum values and semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only repeats the window options without adding new parameter-level detail, 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 returns trending call data ('top tools, top packs, and total call volume') and frames it as 'what other AI agents are calling on Pipeworx right now'. This distinguishes it from sibling tools like discover_tools or recent_alerts, which are about discovery or alerts rather than aggregated call volume.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and aligning with typical agent needs. However, it does not mention any exclusions or alternative tools, so it falls short of the highest bar.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior, but the description goes far beyond that by explaining threshold behavior (>3pp), placeholder filtering, Jaccard similarity gating, and the fill-check pricing against live CLOB depth. It also discloses failure modes like skipped_low_similarity and null arb signals, which is valuable behavioral context not captured 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 densely packed but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. It is long, but every section provides necessary operational detail for a domain-specific arbitrage tool; it is front-loaded with the purpose and usage, and the later sections add depth rather than 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?

There is no output schema, so the description carries the burden of explaining return values, and it does so explicitly for both modes (opportunities[] fields and partition_check object), plus fill-check outputs. It also addresses complex edge cases (partitions with placeholders, low similarity, thin legs) and provides the necessary domain logic, making it fully 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 has 100% coverage with clear parameter descriptions, so the baseline is 3; the description adds extra meaning by explaining the full mode semantics, the types of slugs accepted, and the cross-event scan behavior. It reinforces and expands on the schema without being redundant, though the schema already carries most of the param-level meaning.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and references related tools like polymarket_fill_risk, making the tool's purpose and scope unambiguous relative to 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?

Explicit guidance covers when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names alternatives and caveats, such as using polymarket_fill_risk for custom sizing and warning not to trade when realizable_edge_pp <= 0, providing clear when-to and when-not-to instructions.

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, but the description goes far beyond: it details model families, response segments, diagnostic funnel counters, edge computation (net of slippage), Kelly caps, placeholder filters, caching at KV level, and a caveat about Fed signals. This provides rich behavioral context that the annotations cannot convey.

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

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

The description is information-dense but delivered as a large, run-on paragraph with heavy use of CAPS and semicolons. It lacks clear visual structure (e.g., bullets or line breaks) and is quite long, making it harder to parse despite containing unique content. It's adequately sized for the tool's complexity but not concise.

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

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

With no output schema, the description carries full responsibility for explaining the return shape. It enumerates top-level segments, per-opportunity fields, diagnostics keys, fed_candidates/fed_note, and caching behavior. It also explains why segments might be empty and includes limitation notes, making it highly complete for a complex 9-parameter tool.

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

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

The schema provides 100% parameter descriptions, earning a baseline of 3. The description adds significant semantic value by explaining how parameters interact, e.g., min_partition_leg_kelly applies to per-leg Kelly because parent-level kelly_fraction_half is always 0 for partition arbs, and how tradeable-edge knobs (min_liquidity/max_spread_pp) drop opportunities that aren't realizable.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today'), which clearly differentiates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx disagreement rather than generic arbitrage or tracking.

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 targets the 'what should I bet on today' scenario and notes that agents discover opportunities without paging hundreds of markets, giving clear usage context. However, it does not explicitly name alternative tools or exclusion conditions, falling short of the highest bar for 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 (readOnlyHint, openWorldHint, etc.), the description discloses rich behavioral details: how snapshots are written on cache-miss, why date gaps occur, that decay is computed on |edge_pp_net| rather than signed value, and the meaning of negative edges. It clearly explains the 60-day TTL limit and daily-close basis for decay, adding substantial context over annotations alone.

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, then details the response structure and limitations. Every sentence adds valuable information, though the heavy use of semicolons and inline clarifications makes it less scannable. It earns its length given the tool's complexity, but a slightly tighter structure would improve 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?

With no output schema, the description fully explains the response semantics: tracked[], expired[], and snapshot_dates[], including field meanings, trend categories, and the interpretation of median lifespan. It also covers limitations (TTL, daily closes, slippage) that are essential for correct usage, making it outstandingly complete for an analyst tool.

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

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

The input schema already describes both parameters fully (days and window with defaults and ranges). The description adds minimal extra semantics, mentioning 'snapshot family' for window and restating the default. Since schema coverage is 100%, the baseline is 3, and the description does not meaningfully elevate parameter understanding beyond what's already in the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb ('answers how long has this edge existed') and resource (polymarket_edges snapshots), immediately distinguishing it from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides strong usage context: 'a fresh wide edge and a 3-week-old wide edge are different trades' implies when this tool is valuable. It also gives practical constraints (days lookback, max 30, TTL limits). However, it doesn't explicitly name sibling alternatives or state when NOT to use it, 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 adds significant behavioral detail beyond the readOnlyHint, openWorldHint, and idempotentHint annotations. It explains that the tool walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and explicitly warns about forced_directional_risk and the dominant loss mode of partial basket fills. This complements the annotations without contradiction.

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

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

The description is long but well-structured and front-loaded: purpose, required mode, single-market details, basket details, then usage guidance. Every sentence earns its place, covering important nuances such as per-leg fill detail and the risk of partial fills. The length is appropriate for the tool's complexity.

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

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

With no output schema, the description compensates thoroughly by listing return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, per-leg fill detail, thin_legs[], etc.). A minor gap is the lack of explicit error-handling guidance for cases where neither `market` nor `event` is provided, and the precise distinction between the 'degraded' and 'cannot_fill' verdicts is not elaborated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds interpretive value by explaining how `size_usd` is treated differently in single-market mode (max spend / target proceeds) versus basket mode (settlement notional), and how `side` auto-selects in basket mode based on partition sum. However, much of this is already in the schema, so the added value is modest rather than substantial.

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 and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as the pre-trade validation step. The two operating modes (single-market and basket) are explicitly scoped.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical edge on thin books is not capturable; partial basket fills create unhedged directional risk). The requirement that exactly one of `market` or `event` must be supplied is stated up front.

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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond by explaining the matching logic, compatibility warning conditions, skipped cross types/subtypes, and temporal alignment fields. This prepares the agent for edge cases and gives a realistic picture of tool behavior.

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

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

The description is long but information-dense, covering purpose, modes, response format, safety fields, and limitations. It uses clear labels like 'TWO MODES' and 'SAFETY FIELDS' to organize content, though it could be slightly more concise without losing essential detail.

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

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

Since there is no output schema, the description thoroughly explains the response structure including leg-by-leg prices, top_spreads_pp, compatibility_warning, and temporal_alignment. It also covers rare cases where spreads are not meaningful, making it complete for an agent to understand expected outputs and caveats.

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 describes all three parameters and their defaults, but the description adds significant meaning by clarifying the interaction between 'topic' and the explicit overrides. It explains that 'topic' is a pre-mapped shortcut and that the other two parameters override the mapped sides, which is not obvious from the schema alone.

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

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

The description clearly identifies the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verbs like 'spread' and detailing the two execution modes. It differentiates from sibling tools like polymarket_arbitrage by focusing on spread analysis rather than arbitrage or edge detection.

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

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

The description offers explicit guidance on when to use the 'topic' shortcuts versus explicit tickers, and warns that pre-mapped topics often result in compatibility warnings and may not be tradeable. It explains when spreads are meaningless due to temporal misalignment or non-equivalent bet shapes, but it does not directly name alternative tools for comparison.

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 and idempotent behavior. The description adds valuable scoping context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and clarifies data origin ('previously saved via remember'). This exceeds the annotation baseline without contradicting it.

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

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

Two sentences, front-loaded with the core operation, then usage context and sibling integration. Every sentence contributes useful information without redundancy or fluff.

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

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

For a simple one-parameter tool with strong annotations, the description covers purpose, usage, scoping, and sibling relationships. No output schema is needed, and the description is complete for reliable tool selection and invocation.

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

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

Schema coverage is 100% with the 'key' parameter documented. The description enriches semantics by providing concrete examples of key values ('target ticker, an address, prior research notes') and reinforcing the omission behavior for listing, which goes beyond the schema's minimal description.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys'. It specifies the resource (memory keys) and distinguishes from siblings by explicitly pairing with 'remember' and 'forget'.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier' and contrasts with 'without re-deriving it from scratch'. Names alternatives: 'Pair with remember to save, forget to delete'. Also indicates the omit-key behavior for listing.

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 mutating behavior: "Set mark_read:true to flag returned events read so the next call only shows newer ones." This directly contradicts the annotation readOnlyHint: true, which indicates the tool should not modify state. Because the description contradicts an annotation, the transparency score is a 1.

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 first sentence immediately states the primary action. Each subsequent sentence adds distinct information: return format, filtering options, state change, and an alternative access method. There is no redundant or filler 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 tool with no required parameters and no output schema, the description covers key aspects: what is returned, how to filter, the mark_read side effect, and a script-friendly alternative. It does not explain error handling or auth, but given the annotations (openWorldHint, readOnlyHint) and the schema, it is fairly complete. The annotation contradiction slightly reduces completeness, but the description itself is strong.

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 parameters (100% coverage), the description adds value beyond the schema. It gives a concrete example for the type parameter ("sec_8k"), explains the effect of 'since' as 'ISO timestamp', and clarifies the state-changing behavior of mark_read:true. This enriches the schema descriptions and helps the agent understand the interplay between parameters.

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

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

The description clearly states the tool's purpose: "Pull fired events from your subscription feed." It specifies the resource (subscription feed) and the action (pull events/alerts), and distinguishes itself from siblings like 'recent_changes' or 'recall' by focusing on alerts from a persisted feed. The mention of 'source, citation_uri, and raw event payload' further clarifies the return value.

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 how to use the tool: filter by type and since, set mark_read, and poll. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, which implies when the tool is not needed. However, it does not explicitly compare with sibling tools or state 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 mark this as read-only, open-world, and idempotent, but the description adds substantial context: it fans out to SEC EDGAR, GDELT→GNews (with GDELT preferred and GNews as fallback on rate limit/5xx), and USPTO (with PatentsView API sunset May 2025 causing a soft-fail). It also states the parallel call behavior and the return structure. No contradictions.

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

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

Despite its length, every sentence earns its place: examples, source list with fallbacks, parameter shorthand, return structure, and alternative tool guidance. The description is front-loaded with example queries and remains dense without redundancy.

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

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

The tool has no output schema, but the description explains what the return looks like (structured changes[] grouped by source, total_changes count, and citation URIs). It also covers edge cases like the USPTO soft-fail and gives usage guidance for `since`. This is complete for a tool of this complexity.

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

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

Input schema provides 100% coverage with descriptions for all three parameters, including enums and examples. The description repeats the `since` shorthand examples but adds no new parameter-level information; it does add context about the parallel fan-out, but that's not parameter-specific. Therefore 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 opens with concrete user queries like "What's new with X" and explicitly states it's a "change feed for a company in the last N days/weeks/months in ONE parallel call," naming three data sources and the structured output. It clearly distinguishes from sibling entity_profile by contrasting the change feed vs static profile.

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

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

The description explicitly tells the agent when to use this tool vs entity_profile: 'Use entity_profile instead when you want the static profile... regardless of window.' It also provides typical `since` values ('Use "30d" or "1m" for typical monitoring') and notes fallback behavior and soft-fails, giving clear context for when this tool is appropriate.

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

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

The description adds meaningful behavioral context beyond the annotations: memory is scoped by agent identifier, authenticated users get persistent storage, and anonymous sessions have a 24-hour retention. It also clarifies persistence semantics with the idempotent hint that repeated saves are safe, 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 compact and front-loaded, with no extraneous detail. It delivers purpose, usage, persistence, and related tools in under 50 words, each sentence earning its place.

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

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

For a simple two-string-parameter tool with no output schema, the description fully covers purpose, when to use, persistence, scoping, and related tools. It is complete for the tool's complexity and leaves no major gaps.

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

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

Schema coverage is 100% for both key and value, which already includes examples and types. The description reinforces the key-value nature and mentions 'any text' for values but does not add significant new parameter-level detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Save data the agent will need to reuse later,' which clearly states the tool's core function. It distinguishes from siblings by explicitly naming recall and forget as complementary tools, and highlights the key-value pair scoping.

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)...' It also explains when to use related tools via 'Pair with recall to retrieve later, forget to delete,' providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it cascades through multiple lookup endpoints internally, returns specific citation URIs (pipeworx://...), and auto-disambiguates inputs. These are not captured in annotations and substantially enrich the agent's understanding.

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 with useful information and clearly structured: example queries, a general statement, a usage rule, then per-type details. Every sentence conveys a distinct piece of information (input variants, return fields, source systems, citation URIs, internal behavior). Despite its length, 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 carries the responsibility of explaining return values. It does this thoroughly for both supported types (company returns ticker + CIK + company_name; drug returns RxCUI + ingredient + brand) and also covers input variations and disambiguation. The tool's complexity (two entity types, two external sources) is fully addressed.

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 is already thorough: the 'type' parameter has an enum with descriptions, and the 'value' parameter is explained with examples for both entity types. The description reinforces this but does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description is exceptionally clear: it opens with concrete example queries ('What's the ticker for…'), then states the precise action: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This immediately distinguishes it from sibling tools like search or entity_profile by focusing on identifier lookup. It even lists supported entity types (company, drug) with exact output formats.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the value proposition ('replaces 2-3 manual lookups') and clarifies that other tools require these IDs as input. This effectively situates the tool in the decision workflow relative to others.

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

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

The description adds useful behavioral details beyond the annotations: it reveals that the tool internally calls ai_visibility_check for each entity, ranks results by score, and returns a ranked list with score/confidence/signal density. These details are not present in the annotations, which only cover read-only/idempotent/destructive traits. 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 four sentences, each adding a distinct piece of information: what it does, how it works, when to use it, and what it returns. It is front-loaded with a clear purpose and avoids redundancy or filler.

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

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

Given the tool's complexity (4 parameters, no output schema) and rich annotations, the description covers the essential missing pieces: return format (ranked list), methodology (probes with ai_visibility_check), and a concrete use case. It does not explain all parameters, but the schema already covers those. This is well-rounded, though not exhaustive.

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 documents all parameters with 100% coverage, including the nuance that the first entity is treated as the subject. The description adds minimal paramet - level guidance (e.g., 'your brand + N competitors') which largely mirrors the schema. Thus, it meets the baseline but does not significantly augment the schema's clarity.

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 ('Compare') and a clear resource ('AI visibility across multiple entities'), directly distinguishing it from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic comparison). The mention of ranking by score and surfacing most/least recognized further clarifies the tool's specific function.

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

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

It provides a clear use case ('competitive AI-marketing audits') and implicitly contrasts with ai_visibility_check by stating that this tool probes each entity with that tool. However, it does not explicitly state when not to use this tool or mention alternatives like compare_entities, so it falls short of an explicit when/when-not guide.

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?

Goes beyond the read-only/idempotent annotations by disclosing partial failure degradation, the 5-30s timeout on bundlephobia's first measurement, and the sources_failed field. 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 well-organized: purpose, use case, return structure, ecosystem scope, and failure behavior are all covered in a compact block. Slightly long but every sentence earns its place.

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

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

With no output schema, the description lists the summary fields and return contents, covers ecosystem limitations, and explains timeout/partial failure. This is sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, and the description adds minimal new meaning: it references the version example and default but these already appear in the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'scan' plus resource 'dependency' and clearly explains it's a composite check for evaluating npm packages across deps.dev and bundlephobia. This distinguishes it from sibling tools like scan_competitor_ai_presence or deep_research.

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

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

Explicitly states 'Use whenever an agent asks "is X safe / popular / small"' and provides an alternative for non-npm ecosystems via 'deps.dev:version directly'. Gives 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds the Solr-style query syntax and HAL scope, but no behavioral details like rate limits or return size limitations. 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 a single efficient sentence that front-loads the key information: search type and scope. No filler words; every word contributes.

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 is minimal but sufficient for a search tool with a rich schema and output schema. However, it lacks usage context and doesn't address when to prefer this over search_within or other search-related siblings, leaving a gap in 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 provides full descriptions for all six parameters, so the schema already carries the parameter semantics. The description adds minimal extra meaning beyond the 'Solr-style' hint, which slightly clarifies the query parameter syntax.

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 'Solr-style search across HAL' clearly identifies the tool as a search operation over HAL using Solr query syntax. It does not explicitly distinguish from sibling tools like 'search_within', but the scope and Solr-style hint differentiate it from non-search 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?

No guidance is provided for when to use this tool versus alternatives such as 'search_within' or 'get'. The description simply states what the tool does, with no exclusions, prerequisites, or recommendation of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral details beyond these: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings, 500-char overlapping windows, a 200K char cap with truncation and flagging. These are important runtime behaviors that annotations do not capture.

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 five sentences, but every sentence contributes unique information: what it does, what to pass, when to use it, how it pairs with siblings, and technical implementation. There is no fluff or repetition. The opening sentence front-loads the core purpose.

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

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

Despite having no output schema, the description explains the return format (passages with offsets and similarity scores) and key limiting behaviors (200K cap, truncation flag). It covers the full context needed for an agent to decide when and how to invoke the tool, including pairing with another tool. The description is complete for this tool's complexity.

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

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

Schema coverage is 100%, so the description need not repeat parameter descriptions. It adds value by giving concrete examples of what to pass (SEC 10-K body, article, long tool result) and sample queries (supply-chain risk, fiscal year 2024 revenue). It also clarifies the truncation cap in relation to the 'text' parameter. This exceeds the baseline, though it doesn't exhaustively detail every 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 starts with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by contrasting with 'ask_pipeworx_grounded' and the idea of grounding over the whole document. It also specifies the output (passages with offsets and similarity scores), making the tool's function unambiguous.

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

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

Explicitly states when to use it: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names an alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This goes beyond implied usage to give actionable 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, destructiveHint=false, and idempotentHint=true, so the safe read-only nature is known. However, the description adds no additional behavioral context—such as whether results are paginated, how to interpret the output, or any rate limiting. It simply restates the tool's function without enriching the annotation-provided safety profile.

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

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

The description is a single, concise sentence, which is appropriate for a simple tool. It wastes no words and is easy to parse. However, it is slightly under-specified, bordering on terse, but the structure itself is perfectly fine.

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 output schema exists and the tool is simple, this could be complete with just the basic info. But the description does not explain how to interact with the tool effectively—no mention of query format, result count defaults, or whether the output is a list or single entity. The annotations cover safety but not usage, and the description leaves out practical details.

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 50%: the 'rows' parameter has a description, but 'query' is only typed as string with examples. The tool description adds no parameter-level explanation beyond the schema, and the examples don't clarify query semantics beyond 'CNRS' or 'Laboratoire d'Informatique'—the description fails to compensate for the low coverage.

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

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

The description clearly states the tool performs a lookup for research structures (labs/departments). The verb 'lookup' and resource 'research-structure' are specific, and the parenthetical clarifies the domain. However, it doesn't differentiate from sibling lookup tools like entity_profile or search, lacking explicit distinction.

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?

No guidance is provided on when to use this tool versus alternatives. The description only implies it's for research-structure lookup, but there are no when-to-use or when-not-to-use instructions, and no mention of alternative tools. This leaves the agent to guess based on the tool name alone.

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 behaviors well beyond annotations: OAuth account requirement, anonymous users cannot persist subscriptions, phone verification prerequisite for SMS, 10/day SMS cap, webhook signing secret returned once, auto-disable after consecutive failures, and always-on feed. These add valuable context without contradicting the annotation (readOnlyHint=false, openWorldHint=true, idempotentHint=true).

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

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

The description is long but well-structured: one opening purpose sentence, then requirements, type explanations, and delivery channel details. Some details could be delegated to the schema, but they are presented in a readable, front-loaded manner. Not overly repetitive.

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

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

The description covers most key aspects (types, delivery, prerequisites), but it omits two of the five enum types (patent_grant, clinical_trial) from its 'Supported types' list, even though they appear in the schema. This creates a gap for an agent relying on the description alone to understand all options. Other context, like output schema, is absent but not 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?

Schema coverage is 100%, but the description adds extra meaning: concrete examples for each type (e.g., items:['5.02'] = officer change), delivery channel semantics, constraints (phone must be verified, webhook HTTPS-only), and the useful detail that the webhook signing secret is shown once. This goes well 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 clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' The verb 'Create' and concrete resource 'subscription' make it distinct from siblings like list_subscriptions (listing) and unsubscribe (removing). Supported types and delivery channels are also specified.

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 (to create monitoring subscriptions) and mentions related actions like pulling alerts via recent_alerts or the feed URL. It does not explicitly state 'when not to use' or compare to alternatives, but the context is strong enough for an agent to differentiate from list_subscriptions and unsubscribe.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful behavioral context beyond those: it returns category-bucketed example questions with exact tool+argument shapes, draws from a live catalog, and filters by topic. This gives the agent a clear model of what the tool will do without contradicting annotations.

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

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

The description is dense but front-loaded with example user queries, then explains purpose, behavior, and usage. It's longer than a two-sentence description, but every clause carries useful information (scope, return shape, live catalog, argument usage). No wasted words, though 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?

Despite having no output schema, the description explicitly states the return value: category-bucketed example questions with exact tool+argument shape. It covers the input parameter, use case, and relationship to meta-tools. For an onboarding tool, this is complete; no missing critical information about behavior or prerequisites.

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

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

Schema coverage is 100%: the only parameter 'topic' is fully documented with allowed values and behavior when omitted. The description adds examples ('finance', 'pharma', 'betting') and the concept of 'focus', but these are redundant with the schema's own list and 'Omit for a cross-category spread'. No additional semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that suggests example questions about what Pipeworx can do, returning category-bucketed examples with matching tools. It distinguishes from siblings like ask_pipeworx and discover_tools by explicitly positioning it as the 'FIRST' tool to use when unfamiliar with Pipeworx's capabilities.

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?

Strong usage guidance: it says to use this FIRST when you don't know what Pipeworx can do or to learn how to call meta-tools. It also explains the no-argument vs. topic argument behavior. It doesn't explicitly state when NOT to use it (e.g., when you already know the exact question), but the 'FIRST' phrasing implies 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?

The description adds important behavioral details beyond the annotations: ownership enforcement and the deactivation mechanism that keeps historical events available via recent_alerts. This gives an agent crucial context for side effects.

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

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

The description is concise, front-loaded with the core action, and each sentence earns its place by adding relevant constraints or side effects. No fluff 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?

For a simple tool with one parameter, the description covers purpose, ownership, behavior, and side effects. It references related tools (recent_alerts) and provides enough context for an agent to use it correctly without needing output schema information.

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

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

Since the input schema already fully describes the id parameter (uuid returned by subscribe), the description's 'by id' adds little additional meaning. It does not compensate with new parameter-specific semantics, so baseline 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription by id', specifying the verb and resource. It distinguishes the tool from siblings like 'subscribe' and 'list_subscriptions', and clarifies that it deactivates rather than deletes.

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

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

The description implies when to use the tool (canceling an owned subscription) and provides context about ownership and non-destructive deactivation. However, it does not explicitly name alternatives or exclude scenarios, so it lacks full 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds significant behavioral context without contradiction. It discloses the internal routing logic, that answers are grounded with verbatim evidence, and that the tool returns a verdict, actual value with a pipeworx:// citation, and reasoning. This fully informs the agent of what happens and what to expect, going well beyond the annotations.

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

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

The description is dense but every sentence earns its place: trigger phrases, usage directive, pipeline breakdown, return value list, and the efficiency benefit. It is front-loaded with the most important info (what and when to use) and logically structured. Despite its length, it avoids fluff and remains highly scannable.

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

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

Given the tool's complexity—two divergent pipelines and a dual-parameter schema—the description covers all necessary context: what claims are supported, how outputs are structured, and why it's a one-call replacement. There is no output schema, so the description rightly explains the return format (verdict, value, citation, reasoning), making it fully self-contained.

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

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

Schema coverage is 100% for both parameters, and the description adds substantial meaning. It explains that 'claim' is a natural-language factual statement with concrete examples. It also clarifies 'tolerance_pct' semantics, including how it overrides the wording-implied tolerance, its default cap of 5, and gives a usage scenario (1–2 for hallucination detection). This adds value beyond the schema's field descriptions.

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

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

The description opens with clear trigger phrases ('Is it true that…' / 'fact check') and states the core purpose: natural-language claim verification against authoritative sources. It explicitly distinguishes this tool from siblings by describing the two distinct pipelines (SEC EDGAR for company-financial claims, grounded pipeline for everything else), making it unambiguous what the tool does and how it differs from search or ask_pipeworx.

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.' It further provides decision criteria: company-financial claims go the structured SEC EDGAR path, all other factual claims automatically fall through to the grounded pipeline. This gives clear when-to-use guidance and even explains that it replaces 4–6 sequential calls, which is a strong usage directive.

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