Ror

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds context about the fuzzy nature of the match and the return of candidates with confidence scores, which is useful. However, it does not disclose any limitations or specifics about the matching algorithm, but the strong annotations reduce the burden on the description.

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

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

The description is extremely concise, consisting of two short sentences that front-load the core purpose and outcome. There is no fluff or redundancy; every word contributes to the description's value.

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

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

Given the tool's simplicity (one parameter, output schema present) and strong annotations, the description covers the basic purpose and a hint of the return format. However, it lacks usage context, such as when to choose this tool over alternatives and what constitutes a valid affiliation string. It is adequate for a straightforward tool but not fully 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 0%, so the description must compensate. It mentions 'affiliation-string' which implies the 'text' parameter is an affiliation string, but this is minimal and largely tautological given the tool name. It does not elaborate on input format, examples, or accepted variations, leaving the agent with little additional semantic insight.

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

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

The description clearly states a specific verb ('match') and resource ('affiliation-string'), indicating the tool performs fuzzy matching on affiliation strings and returns candidates with confidence scores. It distinguishes itself from generic search or entity resolution tools, though it could more explicitly differentiate from sibling tools like resolve_entity.

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 states what it does, not when it should be invoked, prerequisites, or exclusions. This is a significant gap given the array of similar 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 already establish read-only, idempotent, non-destructive behavior. The description adds valuable extra context: the default model is free (Workers AI), passing _apiKey involves direct payment to Anthropic, and the return structure is disclosed. This goes beyond annotations without contradicting them.

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

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

The description is concise (three sentences), front-loaded with the primary action, and includes only necessary details: default model, cost implication, return format, and use cases. Every sentence adds value with no redundancy.

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

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

For a tool with no output schema, this description is remarkably complete: it explains what the tool does, how to invoke it (default vs paid), what it returns (per-model score/confidence/signals/raw_response + combined view), and when it is useful. Combined with rich annotations and full schema coverage, the agent has all necessary context.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reiterates the relationship between models and _apiKey ('pass _apiKey to also probe Anthropic') which is already in the schema. It adds minor clarity about defaults but does not significantly extend schema 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 tool's function: probing LLMs for knowledge about an entity and scoring visibility 0-100 per model. It specifies the resource (business/brand/product/topic), the output shape, and the default model, making it easily distinguishable from sibling tools like ask_pipeworx or deep_research.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use the tool but does not explicitly mention alternatives or when not to use it, such as compared to scan_competitor_ai_presence or ask_pipeworx. Clear context, but no exclusions.

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

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

Annotations already establish that the tool is read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context by revealing that it routes through many underlying tools, automatically fills arguments, and returns results with stable pipeworx:// citation URIs. It does not discuss latency or failure modes, but nothing contradicts the annotations.

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

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

The description is longer than average but every section earns its place: the front-loaded 'PREFER OVER WEB SEARCH' instruction, the domain list, the trigger-phrase guidance, the concrete examples, and the explicit exceptions. The structure moves from highest-priority guidance to supporting details, making it easy for an agent to parse.

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

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

Given that there is no output schema, the description usefully states that the tool returns a structured answer with citation URIs. It covers domain scope, usage triggers, and important exclusions. The only minor gap is not addressing the ask_pipeworx_beta and ask_pipeworx_grounded sibling variants, but that does not undermine the core contract.

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 six parameters at 100%, including the main 'question' parameter and five aliases (q, text, input, query, prompt). The description provides examples of valid questions but does not add new parameter syntax or constraints beyond what the schema already documents, so the schema-carries-the-burden baseline of 3 is appropriate.

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

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

The description clearly states that ask_pipeworx answers natural-language factual questions by routing them to one of 5,767 tools across 1,506 verified sources and returning structured answers with citation URIs. It also explicitly distinguishes itself from deep_research and web search, helping an agent avoid the most likely confusing 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?

The description is explicit about when to prefer this tool ('PREFER OVER WEB SEARCH'), lists trigger phrases and concrete examples, and gives a clear exclusion: use deep_research for broad/multi-part questions. It even handles the breaking-news edge case by noting that ask_pipeworx already routes to live news feeds.

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

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

While annotations already mark this as read-only, idempotent, and non-destructive, the description adds meaningful context: it explains that candidate routing improvements may be live, that no candidate is currently active, that behavior currently matches ask_pipeworx, and that it is a fully working router with no fallback. This is exactly the kind of behavioral nuance the annotations 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 dense but every sentence earns its place: identity, current state, usage instruction, comparison purpose, and reassurance that it is fully functional. The key beta-vs-stable distinction is front-loaded.

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

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

For a router with no output schema, the description covers what the tool does, its current experimental status, how it relates to the stable version, and how its results are evaluated. An agent can correctly decide when and how to call it without ambiguity.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter plus all aliases. The description adds only that arguments are the same as ask_pipeworx but does not need to repeat schema content; the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, an identical universal router with the same 5,767 tools, arguments, and response shape. This distinguishes it from the stable ask_pipeworx and grounded variants by emphasizing its experimental routing edge.

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

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

It explicitly says to use it exactly like ask_pipeworx when wanting the newest routing and notes that results are compared against the stable router. It does not list explicit exclusions or when to prefer ask_pipeworx over the beta, but the experimental edge and comparison context provide clear usage direction.

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

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

The description goes far beyond the annotations: it discloses the refusal behavior, the exact success and error return shapes, the refusal reason enum, and the additional LLM call cost. It also clarifies that answers are extracted strictly from tool results, which is critical behavioral context for a grounded mode.

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: mode identity, routing behavior, return contract, refusal reasons, usage guidance, and trade-off vs the sibling. Critical information is front-loaded, and the actionable 'use/prefer' guidance is placed at the end for decision-making.

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 fully specifies the return format for both success and refusal paths, including field names and refusal reason values. Combined with the sibling routing context and annotations, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema coverage is 100%, so the parameter is already fully documented. The description adds no new parameter-level semantics beyond saying the routing logic fills arguments internally, which is behavioral rather than parameter-specific. Baseline 3 is appropriate because the schema carries the burden.

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

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

The description names a specific mode ('Hallucination-resistant answer mode for high-stakes reads') and clearly differentiates from ask_pipeworx by emphasizing grounded extraction using only tool results. It establishes the tool's role and scope, and the return contract makes the purpose concrete.

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 ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the sibling relationship and the extra cost trade-off, leaving no ambiguity about 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 goes far beyond the annotations by detailing fan-out behavior, classifier mapping, resolver confidence levels, fallback handling for GDELT 429s, low-confidence short-circuits, closed-market status, wide-spread flagging, and cancellation-rule risk. These are all additional behavioral traits not covered by readOnlyHint/openWorldHint/idempotentHint. No contradiction.

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

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

The description is long but extremely well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK) and front-loaded with purpose and usage. Every sentence adds a distinct, needed behavioral detail; there is no filler or repetition.

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

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

With no output schema, the description fully documents return values (result.market, result.analysis, result.evidence, match confidence fields), statuses, and edge cases (closed markets, wide spreads, cancellation rules, fallback behavior). It leaves virtually no behavioral gaps and provides all necessary context for correct invocation.

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

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

Schema coverage is 100% but the description enhances every parameter: concrete examples for market (slug/URL/question), depth semantics ('quick = 2-3 evidence sources, thorough = full fan-out'), and include_raw's impact on response size and use cases. This adds significant practical meaning beyond the bare schema.

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

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

The first sentence states the exact function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings by focusing on Polymarket bet research with evidence fan-out and explicitly names use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 use-case guidance ('Use for...') and strong operational instructions like 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing...'. However, it does not name alternative tools or state when NOT to use this tool, so it falls short of a full 5.

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

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

The description enriches the read-only/idempotent annotations with specific behavioral details: it pulls 10-K financial metrics from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This goes well beyond the annotations and provides actionable expectations.

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

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

The description is dense yet efficient. It front-loads with user intent examples, then covers data sources, behavior, and output, finishing with an ROI statement ('Replaces 8–15 sequential lookups'). Every sentence adds value without redundancy.

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

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

Given the moderate complexity (2 params, no output schema), the description fully compensates by stating what is returned (paired data, citation URIs), how results are sorted, and the data source specifics. This is sufficient for an agent to invoke the tool and interpret results correctly.

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

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

The input schema already covers both parameters with descriptions, enumeration for 'type', and constraints for 'values'. The description adds some context (e.g., what metrics are pulled for each type) but does not significantly change parameter understanding. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call. It uses specific verbs like 'compare', 'rank', and 'head to head', and explicitly distinguishes itself from sequential single-pack lookups, making its purpose and scope 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 example queries ('Compare X and Y', 'which is bigger/better', 'rank these companies') and specifies when this tool should be preferred over sequential lookups. It also differentiates behavior between company and drug types, offering clear usage context.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond them: auth tiers and the paid-plan gate on 'thorough', latency expectations (15-60s, up to ~90s), the never-invents guarantee via gaps[], the resolvable-citation guarantee, contradictions[] behavior per depth, semantic excerpting of large records, and the hop field. No statement contradicts 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?

Every sentence earns its place — there is no filler and the front-loading is good (auth gate first, then routing to the alternative). However, the entire definition is one dense, unbroken paragraph with heavy parentheticals and semicolons, making parsing harder than necessary. Structure is the clear weakness despite excellent information density.

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 high-complexity tool with no output schema, the description must carry the return-format burden — and it does thoroughly: findings packet structure (verbatim evidence + confidence + source + fetched_at + citation), gaps[] and contradictions[] semantics, citation fetchability, hop field, excerpting behavior, auth requirements, latency, and sibling routing. Nothing required for correct invocation is missing.

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's depth description is already very rich, so baseline is 3. The description adds meaningful extra semantics: latency expectations tied to depth, the 'multi-step questions resolve in one call' rationale for the iterative hops, and concrete question-phrasing examples for the question parameter ('compare X and Y's regulatory + financial exposure'). This exceeds what the schema alone provides.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call', and immediately distinguishes itself with 'this is NOT open-web search'. It also names sibling ask_pipeworx as the alternative for single lookups and current news, making the tool's identity and scope 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?

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and explicit when-not-to-use exclusions ('For a single lookup use ask_pipeworx instead', 'For BREAKING or colloquial current-news... prefer ask_pipeworx'). It even covers the auth edge case: 'If you are not signed in, use ask_pipeworx instead'. Alternatives are named precisely.

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 idempotentHint=true, so safety is covered. The description adds valuable behavioral details: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This clarifies the response format and the tool's role as a self-contained discovery mechanism.

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, each earning its place: the first states the core action, the second details the output and its readiness for direct use, and the third gives usage context ('Call this FIRST'). The domain list is extensive but directly informs the user of the searchable space, with no filler or redundancy.

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

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

The description fully covers what an agent needs: what the tool does, when to use it (including the 'first step' directive), what it returns (names, descriptions, schemas, examples), and why that is sufficient (no subsequent schema lookup). With no output schema defined, the description's explanation of the return payload is critical and well delivered. The limit parameter is documented in the schema, so nothing essential is missing.

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 six parameters with descriptions, and the query parameter includes rich examples. The description provides only a high-level nod to query semantics ('describing the data or task') and does not explain the alias parameters (q, task, search, description) beyond what the schema already says. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource pair that clearly distinguishes this tool from data-retrieval siblings like 'search' or 'get.' It further clarifies scope by listing concrete domains and emphasizes that it returns tool metadata ('what tools exist'), making its role as a meta-search over tools unambiguous.

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

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

The description explicitly states when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name specific alternative tools to avoid, the 'first step' guidance and contrast with 'not just one answer' effectively positions it against direct data lookups.

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

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

The description discloses behavior far beyond the annotations: it enumerates the fanned-out data sources, explains that empty sections are real 'no data' rather than bugs, notes the USPTO PatentsView API sunset with soft-fail behavior, and describes the resolved:false path. This exceeds what readOnlyHint/openWorldHint/idempotentHint 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 long but densely packed with useful information for a complex tool with no output schema. It front-loads the core purpose and preference guidance, then systematically details return fields and failure modes. A little trimming is possible, but every section earns its place.

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

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

Given the tool's complexity and the absence of an output schema, the description meticulously documents the return shape, source-by-source behavior, failure modes, and input resolution. An agent is well equipped to call this tool correctly and interpret its results. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters in detail. The description adds helpful examples and resolution semantics (resolved_from/resolved_to), but this is marginal enrichment rather than essential compensation. 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 states a clear verb and resource: produces a 'full cross-source profile of a US public company in ONE parallel call.' It differentiates itself from chained single-pack SEC/XBRL/news lookups and provides concrete user-phrase examples. This makes the tool's purpose immediately identifiable.

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

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

The description explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers input variants (ticker, CIK, company name) and expected behavior for private companies. This is strong usage guidance with clear alternatives and conditions.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true, so the deletion behavior is known. The description adds minimal extra behavioral context beyond that, such as 'previously stored' and 'clear sensitive data.' It does not disclose, for example, whether deletion is permanent or impacts related records, but the annotation coverage lowers the bar.

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

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

The description is two sentences long, front-loads the action, then provides usage guidance and tool relationships. Every sentence 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 one-parameter tool with good annotations (destructive, idempotent), the description covers purpose, when to use, and related tools. No output schema is needed for a delete operation, and the combination of schema and annotations makes the tool's behavior fully understandable.

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

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

The input schema provides 100% coverage with a clear description for the single 'key' parameter: 'Memory key to delete.' The tool description adds no extra meaning about key format or behavior; the schema already carries the full burden.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' The verb 'Delete' plus the resource 'memory' precisely identifies the action, and the opening phrase distinguishes it from sibling tools like recall (which retrieves) and remember (which stores).

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

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

It explicitly lists conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools: 'Pair with remember and recall.' This gives the agent actionable guidance on when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds process details (fetches page, extracts title/description/key links, emits markdown) and output format. It discloses the network fetch behavior and the nature of the result without contradicting annotations, providing meaningful context beyond the safe-operation 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 efficiently structured: purpose, process, output, and use cases are each covered in a few sentences. It is slightly verbose with the 'Useful for' list, but every sentence adds value and the key information appears early.

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

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

Given a simple 2-parameter tool with rich annotations and no output schema, the description fully covers the tool's behavior, output format, and appropriate use cases. It also implicitly differentiates from the many sibling tools by focusing on llms.txt generation, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with clear descriptions for 'url' and 'max_links' (including default and max). The description adds the notion of 'key links' and the purpose of the file, but does not materially enhance understanding of the parameters beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Generate a production-ready llms.txt file') and clearly distinguishes from siblings by focusing on generating the standard llms.txt format. It also details the process (fetch, extract, emit) and the target output, 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?

The description provides clear use cases ('getting a client's site indexed...', 'drafting llms.txt...', 'auditing how an AI crawler would see a competitor') which strongly implies when to use it. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient for an agent to select it appropriately.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds no extra behavioral context (e.g., caching, errors), but for a simple get operation, the annotations are sufficient.

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

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

Two short sentences with no unnecessary words. The description is front-loaded and every word earns its place.

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

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

For a single-parameter, read-only tool with output schema, the description is sufficient. It lacks usage guidance, but otherwise covers the essential semantics.

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 explains that ror_id can be either the trailing identifier or the full URL, adding crucial format information not present in the bare string schema. This fully clarifies the one 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 says 'Full ROR record,' which implies retrieval of a ROR record by identifier. It is clear in verb+resource but does not explicitly distinguish itself from sibling tools like resolve_entity or entity_profile.

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

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

No explicit guidance on when to use this tool versus alternatives. It implies usage via identifier or URL, but does not state when this is the right choice compared to search or other lookup tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by detailing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying scope ('caller's active subscriptions'), which is useful behavioral context beyond the annotations.

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

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

The description is two sentences that are front-loaded with the core purpose, followed by return fields and usage guidance. Every sentence earns its place with no redundancy or filler, making it highly concise and well-structured.

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

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

Given the tool's low complexity (one optional parameter), rich annotations covering read-only/idempotent behavior, and full schema documentation, the description is complete. It includes return field details and practical use cases, leaving no critical gaps for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the single parameter include_inactive is fully described in the schema. The description does not add additional meaning about this parameter, so the baseline of 3 is appropriate; it neither helps nor hurts beyond what the schema already provides.

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

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

The description clearly states the tool lists 'the caller's active subscriptions' with a specific verb and resource, distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the return fields, leaving no ambiguity about what the tool does.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This gives clear when-to-use guidance, though it does not explicitly mention alternatives (e.g., subscribe or unsubscribe) or when not to use the tool, so it misses the full 5-level criteria.

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 (all false) provide minimal safety signals, so the description carries the transparency burden. It excels: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token return behavior, that the team reads digests daily, that it's free and doesn't count against quota, and that feedback should reference Pipeworx tools/packs rather than user prompts. No annotation contradiction exists.

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 readable and front-loaded with the core purpose, then logically flows through usage rules, exclusions, claim_token behavior, and constraints. It is somewhat verbose—the same 'ONLY for tools served by this Pipeworx connection' idea is repeated with the alternative-server clarification—but every sentence adds functional value. It earns a 4, slightly penalized for 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 is a feedback submission channel with no output schema, but the description fully prepares the agent: it covers triggering conditions, scope boundaries, token-based response retrieval, rate limiting, and even sustainability ('free'). The nested 'context' object and enum are documented in the schema, and the description adds the essential workflow (file -> receive token -> later check status). This is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level guidance: it explains the claim_token flow in depth ('pass it back later... with no other arguments'), gives concrete examples for the 'type' enum, and instructs users on what to put in 'message' ('be specific... 1-2 sentences typical'). This goes beyond the schema's field descriptions, though it doesn't add much for '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 opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback types (bug, feature/data_gap, praise) and explicitly distinguishes from sibling tools by limiting scope to 'tools served by this Pipeworx connection.' This fully clarifies what the tool does and why an agent would choose it over the many research/data tools in the list.

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 for each feedback type with concrete examples ('wrong/stale data,' 'a tool you wish existed,' 'worked surprisingly well'). It also gives a clear exclusion rule: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance, including a heuristic for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already establish this as a safe, read-only, idempotent operation. The description adds valuable behavioral context: it is 'self-aggregating' from CF analytics-engine, strips PII, returns only (pack, tool, count), and is 'cached 5min-1h' depending on window—clarifying data freshness and privacy beyond the annotation set.

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 (about 80 words) and front-loaded with the core function. Every sentence serves a purpose: the first defines the tool, the next lists use cases, and the last adds provenance/caching. No wasted words or redundant restatement of the tool name.

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

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

For a simple tool with one optional parameter and no output schema, this description is remarkably complete. It covers what it returns, the meaning of the window parameter, ideal use cases, data source, privacy (no PII), and caching behavior. An agent can confidently decide when and how to call it without further clarification.

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 documented in the schema with enum values and a clear explanation of trade-offs. The description merely restates the window options without adding further meaning. Since schema coverage is 100%, the description doesn't need to compensate, and it correctly leaves parameter behavior to the schema.

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

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

The description opens with a specific, unique value proposition—'What other AI agents are calling on Pipeworx right now'—and clearly states it returns top tools, packs, and call volume. This distinguishes it from siblings like discover_tools and ask_pipeworx by focusing on aggregated community call patterns.

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

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

Three explicit, practical use cases are listed (spotting hot data sources, confirming canonical tools, aligning with agent needs). While it doesn't directly name alternative tools to use instead, the scenarios imply when this is the right choice, and the cache/window guidance helps with selection. Just missing an explicit 'compare with X to get...' caveat.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: thresholds (3pp deviation, 0.30 Jaccard, 20% placeholder fraction), the fill check logic (realizable_edge_pp <= 0 means do not trade), and the null signal behavior for partitions with high placeholder fraction. It also mentions skipped_low_similarity, disclosing rejected pair counts, 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 long but well-structured, using capitalized section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize details. It is front-loaded with the core purpose and usage modes. While some technical internals (like fill check specifics) might be trimmed for an AI agent, each sentence carries meaningful information for a complex tool.

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

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

With no output schema, the description fully specifies the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check{} fields). It covers edge cases such as placeholder slugs, low similarity filtering, and fill check outcomes. The reference to polymarket_fill_risk for custom sizing rounds out the guidance, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, with both parameters already explained. The description adds significant value: it explains the no-args trending_scan, provides examples for both event and topic, details what happens in each mode (walking child markets, checking date-axis/threshold-axis ordering, partition check), and notes that full URLs are accepted for 'event'. This goes beyond schema-level 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 states a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from sibling tools by describing the monotonicity/partition approach and explicitly referencing polymarket_fill_risk for custom sizing. The three modes (trending_scan, event, topic) further define the tool's scope.

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

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

The description provides explicit instructions: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It also gives concrete examples of event slugs and topic seeds, explains when cross-event mode is beneficial, and directs to 'polymarket_fill_risk' for custom sizing, effectively covering when and when not to use the tool.

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

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

Annotations already declare read-only/idempotent, but the description adds substantial behavioral detail: 1-hour caching keyed on knobs, diagnostics funnel counters to explain empty segments, the 24h-move warning, and the rationale for excluding Fed candidates. These go well beyond the structured annotations.

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

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

The description is extremely dense and runs as a single multi-clause paragraph. It packs in formula details, model families, output structures, and diagnostics. While each sentence carries technical value, the lack of structural formatting and excessive length makes it harder to parse; it could be more concise and 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?

Despite no output schema, the description thoroughly documents the response top-level structure (by_segment, fed_candidates, _diagnostics), opportunity fields (edge_pp_net, kelly_fraction, etc.), and tradeable-edge filters. It also covers caching and diagnostic reasons, making it highly 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?

Input schema covers 100% of parameters with detailed descriptions. The description's 'TRADEABLE-EDGE KNOBS' section largely duplicates schema content (e.g., min_partition_leg_kelly semantics are already in the schema). No significant new meaning is added beyond the schema, so baseline 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 opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further defines the three response segments and the intended use case, clearly distinguishing this from sibling tools like polymarket_arbitrage.

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 the tool is 'Built for "what should I bet on today"' and mentions agents discover opportunities 'without paging hundreds of markets.' It also provides exclusion context (Fed bets excluded due to unreliable signal). However, it does not explicitly compare to sibling alternatives like polymarket_arbitrage, so it falls short of full differentiation.

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 behavior, and the description adds substantial behavioral depth: snapshot gaps mean no scan occurred, history depth is bounded by a 60-day TTL, and decay is computed from daily closes net of slippage, not intraday. These caveats materially shape interpretation and are not disclosed in annotations or schema.

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

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

The description is long but information-dense. It is front-loaded with the core purpose, then structured into Args, RESPONSE, and LIMITS sections. Every sentence contributes necessary context about response shape, data semantics, and caveats; there is no fluff or repetition.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly describes tracked[], expired[], and snapshot_dates[], including the meaning of trend, decay_pp_per_day, lifespan_days, and the significance of gaps. It also explains the data source and computation limitations, making it complete for a telemetry 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?

Schema coverage is 100%, so the baseline is 3. The description adds useful context by labelling 'window' as a snapshot family and clarifying that 'days' is the lookback across prior snapshots. It also ties the effective history depth to the 60-day TTL, which gives the parameter real-world bounds beyond the schema's clamp values.

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

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

The description clearly identifies the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots. It states the exact question it answers ('how long has this edge existed and is it shrinking?') and differentiates from the sibling polymarket_edges by focusing on time-series analysis of historical snapshots.

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 strong contextual guidance by framing the tool's decision-relevant question ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains what the response includes. It lacks explicit when-not-to-use or named alternatives, but the context makes intended usage clear.

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

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

The description adds substantial behavioral detail beyond the readOnlyHint/idempotentHint annotations: it explains the ladder-walking process, conditional parameter requirements, return payloads for both modes, and the risk of forced directional exposure on partial fills. This is rich context that the annotations neither provide nor contradict.

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

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

The description is long, but every sentence carries essential information for a complex tool. It is well-structured with SINGLE-MARKET and BASKET blocks, front-loaded with the core purpose. It could be slightly tightened, but the density is justified by the tool's complexity.

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

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

With no output schema, the description takes full responsibility for explaining return values, and it does so comprehensively for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.). It also covers edge cases like partial fills and thin legs, making the description complete for an agent to understand what the tool will provide.

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

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

Although schema covers 100% of parameters, the description deepens meaning: it clarifies the conditional requirement of `market` vs `event`, changes interpretation of `size_usd` for basket mode (settlement notional vs spend/proceeds), and explains `side` defaults in both modes. This goes well beyond the schema's simple property descriptions.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly differentiates itself from siblings by name ('polymarket_arbitrage', 'polymarket_edges'). It details two distinct modes (single-market and basket) with concrete output fields, making its purpose unambiguous.

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

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

Explicit usage guidance provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (partial fills convert arb into unhedged position), giving clear when-to-use context and implicitly distinguishing from alternative tools.

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

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

The description adds substantial behavioral disclosure beyond the readOnly/idempotent annotations: matching is keyword-based, not provenance-based ('pairing_unverified'); fees are not modeled ('every spread_pp is gross'); unclassified legs are never paired; and temporal_alignment null means 'could not be computed,' not alignment. This is exactly the kind of caveat detail an agent needs before trusting a returned spread.

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 opening sentence is front-loaded and the rest is organized with labeled sections like 'SAFETY FIELDS,' 'RESPONSE,' and 'Codes.' It is long, but the complexity of the tool justifies most of the length. A few repeated warnings (e.g., pre-mapped ≠ tradeable appearing twice) could be tightened without losing 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?

With no output schema, the description carries the full burden of explaining return semantics, and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, skipped counters, fees_note, and temporal_alignment. Given the tool's complexity and the absence of an output schema, nothing essential for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that 'BOTH modes run the identical token-overlap matcher, so the same disclosures apply to both' and that topic shortcuts auto-fetch matching events. It clarifies the relationship between the three parameters without merely restating the schema.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from single-venue analysis and the many sibling research tools. It also states the two operational modes, making the tool's function explicit rather than tautological.

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

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

The description gives clear context for when to use each mode: 'TWO MODES: (1) topic — 10 pre-mapped macro shortcuts... (2) explicit kalshi_event_ticker + polymarket_event_slug for custom pairings.' It also warns that 'pre-mapped ≠ tradeable' and that returned compatibility fields must be read even when matches exist. It does not explicitly name a sibling alternative to switch to, but the mode-selection guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these: scoping to 'anonymous IP, BYO key hash, or account ID' and the ability to list all keys by omitting the key argument. It doesn't fully describe return behavior, but the added context is substantial.

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

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

The description is three sentences, front-loaded with the core action, and every sentence earns its place. It covers the main action, usage context, scoping, and sibling pairing 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains both invocation modes, scoping, and relationship to remember/forget. No critical operational detail is missing for the agent to select and invoke it correctly.

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

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

Schema coverage is 100% and the schema's key description already states 'omit to list all keys'. The description adds extra meaning by clarifying that keys are those 'previously saved via remember' and providing examples like 'the user's target ticker, an address, prior research notes'. This enriches the parameter's purpose 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 function: 'Retrieve a value previously saved via remember, or list all saved keys.' This is a specific verb+resource combination that distinguishes it from sibling tools like remember (save) and forget (delete). The two operational modes (get by key, list all) are explicitly described.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the paired tools 'remember' and 'forget', making the when-to-use vs alternatives clear. This is strong guidance beyond a generic statement.

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 directly contradicts annotations: readOnlyHint=true while mark_read:true explicitly flags events as read, a state mutation that affects future calls. Similarly, idempotentHint=true conflicts with the described non-idempotent behavior when mark_read is used. This is a serious annotation contradiction.

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

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

The description is packed with essential information but remains well-structured: core action, return fields, filtering/options, behavioral note, and alternative endpoint. Every sentence earns its place 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?

Without an output schema, the description appropriately explains the return payload and key behaviors (polling, mark_read, feed persistence). It also documents the alternative HTTP GET endpoint. This is complete for a polling tool with five parameters.

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 has 100% parameter coverage, so baseline is 3. The description adds value with a concrete type example ('sec_8k'), clarifies 'since' as ISO timestamp, and explains the semantic consequence of mark_read ('next call only shows newer ones'), going beyond the schema's descriptions.

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

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

The description states a specific verb ('Pull') and resource ('fired events from your subscription feed'), and details the return payload (source, citation_uri, raw event payload). This distinguishes it from siblings like 'recent_changes' by focusing on the persisted feed written by the evaluator.

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?

Clear usage context is provided: it supports polling, filtering by type/since, and mark_read to control future calls. It also points to an alternative HTTP endpoint for scripts/dashboards, implying this tool is for in-context polling. Explicit comparisons to sibling tools are absent, but the guidance is actionable.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses data source fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO patent source sunset, and soft-fail behavior. It also explains the return structure (changes[] grouped by source, total_changes, citation URIs), which is essential operational context.

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

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

The description is dense but every sentence earns its place: user-intent examples, mechanism, parameter formats, return structure, and an explicit alternative. It is front-loaded with examples and contains no filler or repetition.

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

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

Given the tool's complexity and lack of output schema, the description fully informs the agent: it explains the multi-source fan-out, fallback behavior, limitation (USPTO soft-fail), the `since` format choices, and the return payload. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds practical guidance for `since` (e.g., "Use '30d' or '1m' for typical monitoring") and ties the parameter to the source windows, exceeding the schema's static definitions.

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

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

The description opens with natural-language examples mapping to user intents, then defines the tool as a 'change feed for a company in the last N days/weeks/months' in one parallel call. It explicitly contrasts with entity_profile, distinguishing it from the most relevant sibling and naming the primary resource (company change feed).

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

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

Provides concrete query phrasings (e.g., "What's new with X"), specifies the time-window parameter with recommended values ("30d" or "1m"), and explicitly names entity_profile as the alternative when a static profile is wanted. It also describes fallback behavior (GDELT→GNews, USPTO soft-fail), giving clear decision cues.

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

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

The description discloses key behavioral traits beyond annotations: scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions, and the key-value storage model. Annotations already indicate it's not read-only and is idempotent, and the description adds context about memory lifetime and scope 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?

Four sentences, front-loaded with the primary purpose, then usage context, storage details, and alternatives. No wasted words; every sentence contributes meaningful information.

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

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

The description covers purpose, usage scenarios, persistence behavior, scoping, and related tools. For a simple key-value store with two parameters and no output schema, this is complete and self-contained.

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

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

Input schema provides 100% coverage with detailed descriptions and examples for both key and value. The description reinforces these with use-case examples but does not add new technical details beyond the schema. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Save' with a clear resource (data needed later) and scope (across conversations or sessions). It distinguishes itself from siblings by naming recall and forget as paired tools. This makes the tool's purpose unambiguous and distinct.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and provides concrete examples. It also names alternatives (recall to retrieve, forget to delete), giving the agent clear decision guidance. No explicit 'when not to use' is stated, but the when and alternatives are 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?

Even though annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavior: graceful degradation when GLEIF/OpenFIGI is unavailable, the `figi_candidates` behavior on ambiguous matches, explicit `unresolved` reporting, and labels identifying each identifier's source. This goes well beyond annotation coverage.

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

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

The opening is purpose-led and the content is information-dense, with each block adding operational guidance. However, the long example chains and nested parentheticals make it heavier than necessary, and some example lists restate the same idea.

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, this is remarkably complete: it covers supported types, input semantics, output behaviors (labels, unresolved, figi_candidates), failure modes, and why multiple lookups are avoided. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaningful parameter context: exact input formats and examples (AAPL, 0000320193, CH0038863350), the distinction between issuer name and instrument name for bonds, and the caution that trailing security-class words match nothing. This materially helps the agent construct valid input 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 identifies the tool's job: resolving a user-spoken name to canonical identifiers other tools need, with specific examples (CIK, LEI, RxCUI). It is specific enough that an agent won't confuse it with search or recall, but it never names a sibling tool, so differentiation is implicit rather than 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 gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also scopes supported entity types and explains that it replaces 2-3 manual lookups. It doesn't mention when not to use the tool or name alternatives such as entity_profile, 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 read-only, idempotent, open-world, and non-destructive behaviors. The description adds substantial context beyond those flags: it discloses orchestration of ai_visibility_check, describes ranking logic, and specifies the exact output content (score, confidence, signal density). This is genuinely useful behavioral detail.

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

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

Four sentences, each earning its place: purpose, mechanism, use case, and output. The information is front-loaded and free of filler. The example quote is illustrative, not fluff.

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

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

Given the lack of an output schema, the description compensates by explicitly naming return fields (ranked list, score, confidence, signal density). It also covers the tool's internal workflow and the competitive audit context, leaving no critical gap for deciding when and how to invoke it.

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

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

The input schema provides per-parameter descriptions for all four parameters (100% coverage). The description doesn't add syntax, constraints, or parameter-specific meaning beyond what the schema already offers. It reaches the baseline of 3, as the schema carries the semantic burden.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It names the underlying tool (ai_visibility_check), indicates ranking/surfacing behavior, and clearly distinguishes itself from siblings by focusing on multi-entity competitive comparison. The use-case quote reinforces the intended scenario.

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 positions the tool for 'competitive AI-marketing audits' and contrasts 'your brand + N competitors', giving clear contextual when-to-use guidance. However, it does not explicitly name alternative tools or state when not to use it, so a minor deduction for missing exclusions.

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

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

Beyond the read-only/idempotent annotations, the description discloses partial failure behavior, the 5-30s first-measurement latency for bundlephobia, the sources_failed field, and that the rest of results still return. This adds significant behavioral context not available in annotations.

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

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

The description is dense but well-structured, leading with the core purpose, then usage, then behavior. The long list of return fields is justified because there is no output schema, but the sentence is somewhat long and could be broken up for easier parsing. Still, every sentence earns its place.

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

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

For a composite tool with no output schema, the description thoroughly covers the returned summary fields, per-advisory details, links, alternative versions, failure semantics, latency, ecosystem scope, and alternative tool usage. No significant gaps remain.

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

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

Schema description coverage is 100% (both package and version are described), so baseline is 3. The description adds the constraint 'NPM ecosystem only in v1', clarifying that the package parameter must be an npm package, and provides a concrete example ('lodash') that helps ground the version parameter. But most parameter meaning is 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 a specific verb+resource: a composite 'should I add this npm package to my project' check. It distinguishes itself from sibling tools by naming the two data sources (deps.dev and bundlephobia) and the exact question it answers.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clearly states exclusions/alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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 non-destructive behavior. The description adds context about return fields, which is helpful, but it does not disclose pagination limits, result caps, or rate limits. With strong annotations, the additional value is moderate but not exceptional.

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, with the core function front-loaded. Each sentence adds distinct value: purpose, output, and use case. There is no verbosity, redundancy, or irrelevant 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?

Given rich input schema (100% coverage) and presence of output schema, the description is largely complete for guiding an agent. It covers what, filters, and result content. Minor gap: no explicit mention of pagination behavior, but the schema's 'page' parameter and examples cover it sufficiently.

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%, providing baseline of 3. The description adds meaning by specifying that 'query' is a name or acronym, which is not explicit in the schema, and it summarizes the type/country filters efficiently. This extra clarity justifies a score above baseline.

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

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

The description uses the specific verb 'Search' with a clear resource 'Research Organization Registry (ROR)' and enumerates the types of institutions targeted. It also states the output fields (ROR id, names, country, types, identifiers) and answers a concrete question ('which ROR id belongs to a named research institution'), differentiating it from sibling tools like 'get' or 'entity_profile'.

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

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

The description provides clear context: use this tool to identify a ROR ID for a named institution, with optional filters. However, it does not explicitly mention when not to use it or compare to alternatives, such as 'search_within' or 'get', leaving some ambiguity.

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=true and destructive=false, but the description adds substantial behavioral context: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verifiable quotes. These details go well beyond what annotations 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 organized into purpose, usage, workflow, and technical details, with each sentence contributing useful information. It is slightly dense but not bloated, earning a 4 rather than a 5.

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

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

Even without an output schema, the description fully explains return values (top-N passages with offsets and similarity scores), input constraints, truncation behavior, and how it complements ask_pipeworx_grounded. 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?

Schema coverage is 100%, and schema descriptions already explain the text, query, and limit. The description reinforces the 'text you already pulled' workflow and gives query examples, but adds little semantic value beyond what the schema already provides, so a baseline 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which names a specific verb, resource, and scope. Concrete examples (SEC 10-K, article) and the pairing with ask_pipeworx_grounded clearly distinguish it from the broader sibling `search` and other 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?

'Use when the record is too big to cram into the prompt' provides an explicit when-to-use. It also suggests an alternative workflow with ask_pipeworx_grounded ('ground over the relevant passages instead of the whole document'), but does not explicitly describe when not to use this tool beyond that.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses the side effect (creating a persistent subscription), the returned id, account verification requirements, per-channel constraints (SMS 10/day cap, phone verification), webhook signing secret behavior (returned once), and auto-disable after 10 consecutive failing runs. No contradictions with the annotations.

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

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

The description is efficiently organized: purpose first, then requirements, supported types with examples, and delivery channels with caveats. Each sentence adds necessary information, and examples are compact. Though long, the high complexity justifies the length, and there is no fluff.

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

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

Given the tool's complexity (5 subscription types, 3 delivery channels, nested parameters, auth prerequisites), the description covers all essential aspects: what it returns, what auth is needed, how each type's params work, delivery options with verification and limits, webhook security, and failure behavior. No output schema exists, so the description fully compensates.

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?

Even though schema coverage is 100%, the description massively extends parameter meaning with concrete examples for each type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id), nested object structures for delivery, and critical constraints like 'sponsor or condition required' for clinical_trial. It explains the webhook signing secret and delivery behavior in a way the raw schema does not.

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

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

The description specifies the exact verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and the return value ('Returns the new subscription id'). It clearly distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation rather than listing, canceling, or consuming alerts.

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

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

The description states a clear prerequisite ('Requires a Pipeworx OAuth account') and explicitly notes when not to use it ('anonymous + BYO cannot persist subscriptions'). It also provides an alternative for consuming alerts without subscribing ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly mention alternatives like list_subscriptions or unsubscribe, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context: it returns category-bucketed examples with exact tool and argument shape drawn from a live catalog, and mentions it covers thousands of tools. 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 front-loaded with example queries, making it immediately recognizable, then delivers the core purpose. It is a bit long and run-on, but every sentence carries useful information. Slight structural improvement would make it more scannable, so not a 5.

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 this is a discovery/onboarding tool with no output schema, the description fully covers what it does, when to use it, how to call it, and how it relates to meta-tools. It answers the likely agent questions about purpose and invocation without needing further detail.

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 `topic` field description lists all allowed values and the omit behavior). The description adds minor redundancy with 'call with no arguments for the full spread' and a few examples, but does not meaningfully go beyond the schema. Baseline 3 is appropriate.

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

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

The description is specific and actionable: it states the tool 'Returns category-bucketed example questions' and positions itself as the 'onboarding entry point' for an agent. It also explicitly lists meta-tools (ask_pipeworx, entity_profile, compare_entities) to learn from, which distinguishes it from siblings.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools'. It also details the parameter behavior, saying 'Call with no arguments for the full spread, or pass `topic`'.

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 that the row is deactivated (not deleted) and historical events remain available, which is behavioral context beyond the annotations. It also mentions ownership enforcement. Annotations already indicate idempotent, non-destructive, write operation, and the description adds useful details without contradicting them.

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

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

The description is concise at three sentences, with the primary action front-loaded. Each sentence adds distinct value: the action, the ownership constraint, and the deactivation behavior with a link to recent_alerts.

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 required parameter, no output schema) and rich annotations, the description is complete. It covers purpose, ownership, side effects, and the relationship to recent_alerts, making it fully adequate for an agent to select and invoke the tool.

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

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

The schema already provides a detailed description for the 'id' parameter ('Subscription id (uuid) returned by subscribe'), covering 100% of the parameter. The description adds no further parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, and it distinguishes from siblings like subscribe and list_subscriptions by indicating the action of cancellation. The title 'Unsubscribe from Alerts' reinforces the purpose.

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

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

The description provides clear context on when to use the tool (to cancel a subscription) and adds an ownership constraint. It does not explicitly name alternatives, but the reference to recent_alerts for historical events implies an alternative for viewing histories. This is sufficient, though not fully explicit.

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/open-world/idempotent, and the description adds high-value behavioral detail: the verdict enum, the distinction between 'check didn't happen' and 'no source exists,' the verification_error structure, and routing logic to different data sources. 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?

Although lengthy, every sentence earns its place: examples, routing, verdict enum, error handling, and the replacement value are all covered. It is densely informative without redundancy.

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

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

Given the absence of an output schema and the tool's complexity, the description is exceptionally complete. It covers routing, return values, edge cases (could_not_verify, unsupported), and the value proposition of consolidating multiple calls.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds extra value by explaining tolerance_pct semantics (default, cap of 5, and use for hallucination detection) and providing natural-language examples for claim.

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 query paraphrases ('Is it true that…' / 'fact check') and states it performs natural-language claim verification against authoritative sources. It clearly differentiates from sibling research/search tools by specifying a verdict output and noting it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and distinguishes between company-financial claims (SEC EDGAR fast path) and all other claims (grounded pipeline). It also clarifies the meaning of could_not_verify vs unsupported to prevent misuse.

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