Squiggle

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

The description discloses the default model (Workers AI Llama-3.3-70b), the free tier, the BYO Anthropic key with direct payment, and the exact return structure per model ({score, confidence, signals, raw_response}) plus a combined view. These behaviors go well beyond the annotations and add practical context about cost and output.

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

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

Two well-organized sentences front-load the core purpose and follow with key config details and use cases. Every phrase earns its place; 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?

For a tool with 4 params and no output schema, the description covers what it does, how to configure it, what it returns, and when to use it. The per-model return keys and combined view are specified, making it fully self-contained for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that `models` defaults to workers-ai, that `_apiKey` is needed only for anthropic and is passed through, and links the cost implication. This is above the baseline.

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

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

The description clearly states the tool probes LLMs and scores visibility on a 0-100 scale, using 'probe' as a specific verb and naming the target (LLMs) and outcome. It does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, but the mechanism is distinct enough.

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

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

It provides explicit use-case context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't name alternative tools or define when not to use it, but the context is clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: routing across thousands of tools, argument filling, structured answers with stable pipeworx:// URIs, and one-fast-call performance. It could mention failure modes or limitations, but the provided detail is strong.

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

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

The description is long but well-structured and front-loaded with the key guidance. It has a clear hierarchy of rationale, mechanism, triggers, examples, and alternatives. Minor redundancy (e.g., 'prefer over web search' restated) prevents 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?

For a complex tool with no output schema, the description is highly complete. It explains the routing mechanism, output format, trigger phrases, example queries, and escalation paths to alternative tools. The inclusion of citation URIs and special-case handling leaves little 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?

The input schema already documents the question parameter and all aliases with 100% coverage. The description reinforces with concrete examples but adds no new semantic details beyond the schema, so the 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 clearly states the tool's role: a default question-answering tool that routes to 5,334 tools across verified sources and returns structured answers with citation URIs. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and 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?

Explicit guidance is provided: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE', and 'Step up only when needed' with named alternatives. It also covers breaking-news scenarios, making the when-to-use 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 context beyond the annotations: it is a live experimental router with candidate routing improvements that can change behavior, currently identical to stable, and a full working router with no fallback. This is exactly the kind of dynamic, non-obvious behavior an agent needs to know.

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

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

The description is a focused paragraph of five sentences, each carrying relevant information. It is front-loaded with the core purpose and avoids fluff, though specific details like the tool count and exact date add slight verbosity. Overall well-structured.

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

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

The description covers scope, current state, usage, and relationship to the stable router. It notes the same response shape as ask_pipeworx, but does not describe the output format itself, which is a minor gap given there is no output schema. Still, for a complex router tool, it is adequately complete.

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

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

The input schema already provides 100% coverage with descriptions for the question parameter and all aliases. The description does not add parameter-specific meaning, but with such complete 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 that this is a beta version of ask_pipeworx, a universal router to 5,334 tools. It specifies the verb (route/ask), resource (all Pipeworx tools), and distinguishes itself as the experimental variant of the stable ask_pipeworx. This is specific and not a tautology.

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

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

It explicitly states to use it exactly like ask_pipeworx when you want the newest routing, and mentions that results are compared against the stable router. This gives a clear when-to-use and implies the stable alternative, effectively differentiating from its sibling 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?

Adds rich behavioral detail beyond annotations: return shape with evidence/verbatim quote, explicit refusal reasons enum, data handling ('using ONLY what the tool result contains'), and cost implication. No contradiction with the readOnly/openWorld/idempotent annotations.

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

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

Every sentence earns its place: purpose, internal mechanism, return contract with refusal reasons, and usage guidance with cost tradeoff. Dense but not verbose, with clear front-loading of the primary purpose.

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

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

For a tool with no output schema, the description fully documents the success response, explicit failure/refusal modes, and behavioral constraints. An agent has everything needed to invoke and interpret results correctly, including the extra LLM call consideration.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question'. The description mentions 'fills arguments' but does not add further parameter-level semantics. Baseline 3 applies because the schema fully covers parameter meaning.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' a specific verb+resource statement. It clearly distinguishes from sibling ask_pipeworx by describing the grounded extraction mechanism ('EXTRACTS the answer using ONLY what the tool result contains') and explicitly naming the sibling.

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 ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when-not-to-use ('prefer ask_pipeworx for casual lookups'). Directly names the alternative tool and gives the cost tradeoff (one extra LLM call).

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, etc.), the description discloses rich behavioral traits: resolver contract with match confidence and alternatives, low-confidence short-circuit, closed-market status, wide-spread tradeability warning, cancellation-rule parsing, and news fallback behavior. No contradiction with annotations.

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

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

The description is long but well-organized with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Every sentence contributes technical or operational detail, though the density could overwhelm some agents.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers response shapes, statuses, safety behavior, cancellation rules, and edge cases (closed markets, wide spreads, GDELT failures). It also explains the parent_event extractor and news fallback fields, leaving little ambiguity for an agent.

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

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

The input schema already documents all three parameters with 100% coverage. The description adds value by explaining the market parameter accepts slug/URL/question text, depth default, and the include_raw trade-off (recommended false to keep responses under ~20KB vs. full payloads). This goes beyond schema descriptions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also gives concrete use cases ('should I bet on X', 'what does the data say about Y') and distinguishes itself from sibling tools by covering full research/fan-out, not just edges or 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 provides explicit usage scenarios: 'Use for "should I bet on X"...' and explains when to check cancellation rules before sizing bets. It does not list alternatives or explicitly say when not to use it, but the context is clear enough 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 readOnly/openWorld/idempotent, and the description adds substantial behavior: data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, long-term debt; adverse events, approval counts, trial counts), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and return format (paired data + pipeworx:// citation URIs). No contradiction with annotations.

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

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

The description is dense and front-loaded with trigger phrases in the first sentence. Each sentence adds distinct value (usage examples, data sources, fiscal-year edge case, sorting behavior, return format, efficiency claim). 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?

For a 2-parameter tool with no output schema, the description fully covers both entity types, their metrics, sorting logic, return data, and citation URIs. It also addresses edge cases (off-calendar fiscal years) and performance benefits, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (type enum and values array are both documented). The description adds meaningful type-specific semantics: what 'company' vs 'drug' actually retrieves (10-K data vs FAERS/FDA/trial counts), and examples for values ('AAPL','MSFT' / 'ozempic','mounjaro'). This goes beyond the minimal enum labels, though the schema already handles parameter structure.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs in one call, with specific verb ('compare') and resource ('companies or drugs'). It distinguishes itself from sibling tools like entity_profile by explicitly covering multi-entity comparison and even naming the alternative ('sequential single-pack lookups').

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

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

Provides explicit usage triggers ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies') and an explicit preference rule ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'). This gives clear when-to-use guidance and differentiates from 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?

Goes far beyond the annotations by disclosing parallel decomposition, the findings-packet format with 'gaps[]' for unanswered facets, the 'never invented' guarantee, expected latency (15-60s, up to 90s for thorough), hop fields, citation_uri semantics, and the contradictions[] array. These behavioral details are not implied by the readOnly/openWorld/idempotent annotations.

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

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

The description is long but well-structured and front-loaded with the critical account requirement before moving to core functionality, alternatives, then depth mechanics and return format. Every sentence earns its place, though it could be tightened slightly without losing critical details.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers return values (findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), auth requirements, timing, and edge cases (e.g., empty gaps for non-catalog topics). It is complete for an agent to invoke confidently.

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

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

Schema covers both parameters 100%, so baseline is 3, but the description adds meaningful semantics: it explains that 'question' accepts broad/multi-part queries (decomposition is the point) and enriches the 'depth' enum with behavior like 'standard re-angles unanswered gaps' and 'thorough chases leads'. This goes beyond the schema's enum descriptions.

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

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

The description clearly states it performs 'grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' in one call, with a specific verb+resource+scope. It explicitly contrasts itself with open-web search and distinguishes from siblings like ask_pipeworx, 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?

Usage guidance is explicit: 'Best for broad/multi-part questions over structured data'; alternatives are named for single lookups ('use ask_pipeworx') and for breaking/current-news topics ('prefer ask_pipeworx'). Also specifies account requirements and when to use each depth level.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it returns top-N tools, includes full input schemas with curated examples, and states that results are 'ready to call directly, no second schema lookup needed.' This exceeds the annotation baseline without contradicting it.

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

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

The description is three sentences, each serving a distinct purpose: purpose, usage context, and return behavior. The domain list is long but informative. It is front-loaded with the core verb phrase and avoids fluff, though slightly heavy on enumeration.

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, it is essential to describe what the tool returns. The description does so clearly: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also explains why that matters (ready to call directly) and gives usage timing. For a meta-tool with six parameters and no output schema, this description 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 description coverage is 100%, so the schema already documents all six parameters, including the aliases and limit bounds. The description reinforces the query concept with examples and mentions 'top-N' but does not add new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task', which clearly states the verb (find) and resource (tools). It lists specific domains (SEC filings, FDA drugs, etc.), making the purpose concrete, and distinguishes itself from sibling tools by positioning this as a meta-discovery tool rather than a specific data lookup. This is a strong, differentiated 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 explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and further directs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear situational context and implicitly contrasts with direct-answer tools, which is excellent usage guidance.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds rich detail: fans out across SEC, XBRL, USPTO, news, GLEIF; discloses patent API sunset and soft-fail; mentions GDELT→GNews fallback; and describes return fields and URI formats. This goes 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 detailed but starts with a long list of paraphrased example queries, which adds some redundancy. However, it is well-organized: intent examples → core capability → sources → return fields → input constraints. It earns a 4 due to slight over-length, 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?

No output schema exists, so the description carries the full burden of explaining the return structure. It lists cik, company_name, recent_filings (with pipeworx URIs), fundamentals fields, patents, news, and LEI, and also covers failure behavior (patents sunset, news fallback). This is fully adequate for an agent to use correctly.

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

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

Schema description coverage is 100%, and the description exactly repeats the examples and constraints already in the schema ("AAPL", "0000320193", names not supported). It adds no new semantic information for the parameters beyond what the schema provides, 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 provides a 'full cross-source profile of a US public company in ONE parallel call' and gives specific example queries. It distinguishes itself from chained lookups and sibling tools by targeting holistic company profiles rather than single-source lookups or broader research.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and tells users to use resolve_entity first for names. Clearly defines when to use and what to do instead in unsupported cases.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description aligns with these and adds context about clearing sensitive data and pairing with remember/recall. However, it does not disclose additional behavioral traits such as behavior when the key does not exist or confirmation of deletion, so it adds moderate value beyond annotations.

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

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

The description is two sentences, front-loaded with the action, and contains no filler. Every word contributes to understanding the tool's purpose and usage.

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

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

For a simple one-parameter tool with annotations covering destructiveness and idempotency, the description is sufficiently complete. It states what the tool does, when to use it, and how it relates to siblings. It does not need to describe return values since no output schema exists, but could optionally mention what happens after deletion.

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

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

The input schema has 100% coverage of the single parameter 'key' with the description 'Memory key to delete'. The tool description repeats this by saying 'by key' but does not add extra meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('previously stored memory'), with the specific mechanism ('by key'). It distinguishes itself from related sibling tools like remember and recall by naming them and positioning forget as their counterpart.

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 situations for use: stale context, task completion, or clearing sensitive data. It does not explicitly state when not to use it or offer alternative tools, but the pairing suggestion with remember/recall provides some comparative 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 read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations by naming the data source (Squiggle) and the return fields (scores, venues, dates, match IDs), enriching understanding of what the tool provides.

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

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

The description is a single, well-structured sentence that front-loads the action and includes all essential information without redundancy. Every word contributes to understanding the tool's function.

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 filtered query tool with an output schema and comprehensive annotations, the description is complete. It covers purpose, filters, return fields, and source, leaving no critical gaps. The output schema handles return format details.

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

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

Schema coverage is only 33% (only 'complete' is described). The description mentions all three filters (year, round, completion status) but adds little detail beyond the property names. It confirms their role as filters but does not compensate for the lack of schema descriptions for 'year' and 'round'.

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

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

The description clearly states the tool's action ('Fetch AFL fixture and results from Squiggle') and scope, including filters and return fields. This distinguishes it from sibling tools like ladder, standings, teams, and tips, which serve different data needs.

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

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

The description implies when to use the tool (when needing AFL fixtures/results by year, round, completion status) and specifies key filters. However, it does not explicitly mention alternatives or exclusions, though the sibling list provides 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits a standard markdown blob. This goes beyond the annotations by explaining the internal process and output format, though it omits edge cases like JS-heavy pages or error handling.

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

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

Three tight sentences: purpose, process, and use cases. Every sentence earns its place, with no redundant phrases. Front-loaded with the core action and output.

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

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

No output schema exists, but the description explicitly states the output format ('single text blob', 'standard llms.txt markdown format') and where to place it (site-root/llms.txt). This sufficiently covers return value expectations for a moderate-complexity tool. It does not mention pagination or failure behavior, but given the simplicity, the description is adequate.

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% for both parameters (url and max_links), so the schema already fully documents their meaning. The description adds minimal extra semantic value—'for any URL' and 'standard llms.txt markdown format'—but does not materially enhance parameter understanding beyond the schema.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file'), clearly stating what the tool does. It also distinguishes the tool from siblings by focusing on the specific output (standard llms.txt markdown) and mentions the intended use cases (indexing, drafting, auditing).

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

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

The description provides a clear 'Useful for:' section listing three concrete scenarios (client site indexing, personal project drafting, competitor auditing). It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide selection.

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

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

Annotations already indicate that the tool is read-only, open-world, idempotent, and non-destructive, so the safety profile is covered. However, the description adds minimal behavioral context: 'projected' suggests a forecast or estimate, but there is no explanation of what 'projected' means, how the 'source' parameter affects results, or any other behavioral trait. It adds barely more than 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 only one short sentence, so it is terse, but it is under-specified rather than appropriately concise. It omits essential information such as a verb, parameter meanings, and usage context. While it is front-loaded, the content is too sparse to justify its brevity.

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 an output schema existing, the description is far too minimal for a tool with 3 parameters and sibling tools sharing related concepts. It does not define what a 'ladder' is, what 'projected' means, or how the parameters filter the result. The agent would be unable to correctly select and invoke this tool based on the available text.

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 0%, yet the description provides almost no parameter meaning. Only 'per source' hints that the 'source' parameter is a filter, but 'year' and 'round' are completely unexplained. With three optional parameters and no elaboration, the description fails to compensate for the schema's lack of 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 'Projected ladder per source' is a noun phrase without a clear verb. It conveys that the tool provides a projected ladder data item per source, but 'ladder' is ambiguous without context and not effectively differentiated from the related 'standings' tool. It is not a pure tautology, but it is vague and does not state an explicit action.

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 no guidance on when to use this tool versus alternatives such as 'standings', 'sources', or 'teams'. There is no mention of use cases, prerequisites, or exclusions. The lack of any contextual direction leaves the agent to guess when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the scope ('caller's active subscriptions'), which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the action, and every sentence earns its place: the first states the purpose, the second provides return fields and usage guidance. No wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the essential context: what is listed, what fields are returned, and when to use it. The annotations and schema fill the remaining gaps, making it 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% and the single parameter (include_inactive) is fully described in the schema. The description does not mention this parameter, but since the schema does the heavy lifting, 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 uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing the tool from siblings like subscribe and unsubscribe. It also explicitly connects to use cases (reviewing before adding more, finding an id to cancel), reinforcing its unique role.

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

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

The description provides clear context for when to use the tool: 'before adding more' (i.e., before subscribing) and 'to find an id to cancel.' It implies the alternatives (subscribe/unsubscribe) but does not name them explicitly as tools, which would have made this 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 indicate this is not read-only or idempotent, implying a write/action. The description adds context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that team reads digests daily. It doesn't contradict any annotation.

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

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

Four sentences, each serving a purpose: purpose, when-to-use, content guidance, and constraints. Front-loaded with the main action, 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?

The description is fully self-contained for this simple feedback tool: it covers purpose, usage triggers, content requirements, constraints, and impact. Given no output schema and low complexity, nothing 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 provides 100% coverage with detailed descriptions for all parameters, including enum meanings and message formatting. The description adds minimal extra value (e.g., don't paste end-user prompt), so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about something broken, missing, or needing to exist. It uses a specific verb ('Tell') with a specific resource ('Pipeworx team') and enumerates use cases (bug, feature/data_gap, praise), distinguishing it from all sibling tools which are research/query tools.

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

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

The description explicitly lists when to use the tool: for bugs, feature gaps, data gaps, or praise. It also provides content guidelines (describe in terms of tools/packs, don't paste end-user prompt) and mentions rate limits. No alternatives are named, but no sibling tool serves this purpose, so the guidance is clear.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses that the data is self-aggregating, derived from the CF analytics-engine, contains no PII, and is cached for 5min-1h. This is rich, non-obvious information that helps the agent anticipate behavior and trust the signal.

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

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

The description is front-loaded with the core function and uses a numbered list for use cases, making it scannable. It is slightly longer than strictly necessary but every sentence contributes useful context (return values, use cases, data source, caching), so it 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 simplicity (one optional parameter, no output schema), the description adequately explains return values (top tools, top packs, total call volume), window semantics, and caching behavior. It does not describe an exact response format, but that is not critical for this simple read-only tool.

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

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

The input schema already provides 100% coverage for the window parameter, including enum values and semantics. The description mentions windows but does not add new meaning beyond what the schema description already states. Therefore, the description contributes no extra value here, consistent with the baseline.

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

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

The description clearly states what the tool does: returns trending tools, packs, and call volume over a recent window. The verb 'Returns' is specific, and the resource (top tools, top packs, total call volume) is distinct from sibling tools like discover_tools or sources.

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 'Useful for' scenarios (discovering hot data sources, confirming canonical tools, aligning use cases), which gives clear context on when to use it. However, it does not explicitly mention when NOT to use it or name alternative sibling tools, 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?

The description goes well beyond the annotations by explaining internal checks (semantic anchor, partition filter, fill check), algorithm thresholds (e.g., >3pp deviations), and providing actionable advice like 'do not trade it' when realizable edge is ≤0. This is rich behavioral context that annotations alone 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 lengthy (over 400 words) but uses structured sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and bold key terms, making it scannable. The first sentence conveys the core purpose, and details are organized, though it could be trimmed for faster comprehension by an agent.

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

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

Given the tool's complexity (multiple modes, algorithmic checks, fill risk), the description is exceptionally complete. It describes the response structure (opportunities[], partition_check), failure conditions (skipped_low_similarity, placeholders), and even warns against trading on un-realizable edges, all without an output schema.

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

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

Both schema parameters already have descriptions, but the tool description adds concrete examples (e.g., 'fed-decision-may-2026') and explains the default mode when no arguments are passed. It also clarifies the behavior of each parameter in the context of the algorithm, which goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, which is specific to the resource. However, it does not explicitly mention how it differs from sibling tools like polymarket_edges or polymarket_edge_tracker, so differentiation is implicit rather than named.

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

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

The description explicitly explains when to use each mode: no args for trending_scan, `event` for specific markets (recommended), and `topic` for cross-event scanning. It even names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This provides clear when/alternative guidance.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It reveals caching behavior ('Cached 1h at the KV level'), diagnostic outputs ('_diagnostics' with funnel counters), warning messages (24h-move warning), and processing nuances (placeholder-slug filters, per-sport alpha adjustments). It also explains why segments may be empty (stale top-N, failed gates, knobs), which is critical for agent debugging. No contradiction with annotations.

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

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

The description is long and dense, but it uses clear structural markers (FIVE MODEL FAMILIES, RESPONSE TOP-LEVEL, TRADEABLE-EDGE KNOBS) and numbered sections to organize the content. Each sentence provides substantive information; there is no filler. However, the sheer length and density may be challenging to process quickly, and some details could be considered over-specified. It is efficiently structured but not maximally concise.

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

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

Given the tool's complexity (9 parameters, no output schema, nested response objects), the description is exceptionally complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), covers all behavioral caveats (Fed signal unreliability, halved Kelly, placeholder filters), and describes how the knobs affect outcomes. There is no output schema to rely on, so the description carries the full burden—and it succeeds comprehensively.

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

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

The input schema has 100% coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds value by explaining the purpose and interaction of these parameters in the broader context: e.g., min_partition_leg_kelly is elaborated with why the parent-level kelly is zero and how the knob applies to per-leg values. It also offers practical usage examples (e.g., setting min_liquidity to 5000). This lifts the score above baseline, though not to 5 since the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the resource (Polymarket markets), the action (scan and return opportunities), and the scope (top markets, without paging hundreds). This distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker, which focus on different aspects of market analysis.

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

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

The description provides strong contextual guidance: 'Built for "what should I bet on today"' and explains how agents can discover opportunities without manual paging. It describes the filtering knobs that refine results (min_liquidity, max_spread_pp, etc.). However, it doesn't explicitly mention when NOT to use this tool or point to specific alternatives for edge cases (e.g., 'use polymarket_arbitrage for pure arbitrage'), so it stops 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?

Despite readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: data is bounded by a 60-day TTL, snapshots are only written on cache-miss causing gaps, decay is computed from daily closes (not intraday), and negative edge_pp_net means SELL YES. These details go well beyond the annotations and describe the tool's operational quirks.

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 useful information. It is well structured with 'Args:' and 'RESPONSE:' sections, front-loads the core purpose, and uses formatting that aids scannability. 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?

Given no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), data limits (TTL, snapshot start), and computation nuances (slippage, daily closes). It fully equips an agent to interpret results and anticipate gaps.

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

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

Schema coverage is 100% and the description mostly restates schema values (default 14, max 30, default 1wk). It adds minor context like 'snapshot family' and the clamp range, but does not deeply expand on parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a distinct question ('how long has this edge existed and is it shrinking?') and differentiates from siblings like polymarket_edges by focusing on time-series persistence and decay rather than current edge values.

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

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

The description implies when to use it by contrasting a 'fresh wide edge' vs a '3-week-old wide edge', suggesting it is for assessing edge durability. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion 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?

Even though annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, the description goes far beyond by disclosing behavioral nuances: how the tool walks the order-book ladder, interprets size_usd differently for buys vs sells and for basket mode, returns a verdict ('clean|degraded|cannot_fill'), and explicitly warns that partial basket fills convert an arb into an unhedged directional position. This is rich, non-obvious behavioral context that annotations cannot convey.

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

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

Although the description is long, it is densely packed and well-organized with mode headings (SINGLE-MARKET vs BASKET). Every sentence adds value: return fields, defaults, risk warnings, and usage triggers. The opening sentence front-loads the core purpose, and the structured breakdown makes complex behavior scannable without wasted words.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It enumerates key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, theoretical_sum vs realizable_sum, capture_ratio, per-leg fill detail, thin_legs[], forced_directional_risk). It also covers prerequisites, trade size thresholds, and failure modes, making the tool's context complete for an agent despite the absence of an output schema.

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

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

With 100% schema_description_coverage the baseline is 3, but the description adds substantial semantics beyond the schema. It explains the dual meaning of size_usd ('max spend on buys, target proceeds on sells' in single-market; 'settlement notional S' in basket mode), clarifies the side default logic in basket mode ('auto — sell if partition sum > 1, buy if < 1'), and distinguishes the market vs event parameters as mutually exclusive modes. This goes well beyond the schema's field-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 opens with a specific verb+resource combination ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly differentiates from siblings by explicitly saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It unambiguously defines the tool's role as a risk-checking layer before executing arb/edge trades.

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

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

The description provides explicit when-to-use guidance ('USE THIS before...'), names alternative tools (polymarket_arbitrage, polymarket_edges), and explains the two modes (single-market vs basket) with clear requirements. It even enumerates scenarios where this tool is essential (partial fills, thin books), which gives the agent strong decision-making context.

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

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

The description goes far beyond the annotations by disclosing detailed behavioral edge cases: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs skipped_cross_type:0), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also warns that 'pre-mapped ≠ tradeable', which is crucial behavioral context not captured by readOnlyHint or openWorldHint. This is a model of transparency.

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

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

The description is long but information-dense, with a clear logical flow: purpose, modes, response, safety fields, caveat. Every sentence adds substantive detail about functionality or limitations, so it's not verbose for the sake of it. It could be trimmed slightly for rapid consumption, but the structure is well-organized and front-loaded with the core purpose.

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

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

Given the tool's complexity (two venues, two modes, safety warnings, spread computation), the description is remarkably complete. It explains the response format (leg-by-leg prices, spread array), the safety fields, and the meaning of alignment and skipped types. No output schema exists, so the description fully compensates by covering return values and edge cases comprehensively.

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

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

The schema already provides 100% coverage for all three parameters with descriptive help text. The tool description adds extra meaning by explaining how topic shortcuts map to a list of macro keywords, how explicit ticker/slug overrides the topic-mapped side, and how the two modes relate to output. This goes beyond the schema's straightforward descriptions, enriching the understanding of parameter semantics.

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

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

The description opens with a specific verb phrase 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', which clearly states the tool's function and distinguishes it from sibling tools like polymarket_arbitrage. It further details two operation modes and the kind of output produced, 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 clearly outlines two usage modes: topic shortcuts for pre-mapped events and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also provides a strong caveat that most pre-mapped topics return compatibility_warning and are not tradeable, guiding users to be cautious with those shortcuts. However, it doesn't explicitly compare against sibling tools like polymarket_arbitrage, so guidance on when to choose this over alternatives is implicit rather than 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?

While annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, the description adds valuable context: the ability to list all keys when key is omitted, and that storage is scoped to the user's identifier (anonymous IP, BYO key hash, or account ID). This goes beyond the 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 three sentences long and front-loaded with the core function in the first sentence. The subsequent sentences add usage context, scope, and related tools without redundancy. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the main behaviors, use cases, and scope. It could mention return value details or behavior on missing keys, but the description is sufficient for a tool of this complexity, especially given the strong annotations.

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

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

The schema already describes the key parameter fully ('Memory key to retrieve (omit to list all keys)'). The description essentially restates this behavior in prose, so it does not add meaningful new meaning beyond the schema. Schema coverage is 100%, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This is specific with a verb (retrieve/list) and resource (saved memory), and it naturally distinguishes itself from sibling tools like remember and forget.

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

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

It says 'Use to look up context the agent stored earlier' and suggests pairing with remember to save and forget to delete, giving clear context and alternatives. However, it does not explicitly state when not to use this tool, so it stops short of a perfect 5.

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

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

The annotations declare readOnlyHint=true and idempotentHint=true, but the description explicitly says 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a persistent state change, directly contradicting the read-only and idempotent annotations. The contradiction warrants a score of 1.

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

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

The description is compact—three sentences—and front-loaded with the core purpose. It packs return payload details, filtering options, mark_read behavior, and a polling/alternative endpoint without waste. Slightly dense but efficient.

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

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

With no output schema, the description compensates by explaining what each alert carries (source, citation_uri, raw payload) and the mark_read lifecycle. It also mentions the HTTP alternative. While it doesn't mention unread_only or limit in prose, those are covered in the schema. Overall, it gives sufficient context for a read tool.

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

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

The input schema has 100% parameter coverage with descriptions for all five parameters. The description only adds a few examples (e.g., 'sec_8k' for type, ISO timestamps for since) that are already implied by the schema. It does not add meaningful semantic value beyond what the schema provides.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed' and details what each event carries (source, citation_uri, raw payload). This distinguishes it from siblings like recent_changes and list_subscriptions. The verb 'Pull' and specific resource make the purpose unambiguous.

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

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

The description says 'Polls work fine' and provides an HTTP endpoint as an alternative for scripts/dashboards, giving some usage context. However, it does not explicitly state when to use this tool instead of sibling tools, nor does it offer exclusions or when-not scenarios. Usage is implied rather than explicitly guided.

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 significant behavioral traits beyond the read-only/idempotent hints: it details the sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback logic (GDELT preferred, GNews on rate limit/5xx), and the soft-fail status of USPTO due to API sunset. This gives the agent a clear model of what happens under the hood.

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

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

The description is a single dense paragraph but well-structured: it opens with usage examples, then defines purpose, enumerates sources, parameter details, output shape, and closes with an alternative tool. Every sentence carries information, though it could be slightly more scannable with line breaks.

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 there is no output schema, the description compensates by explicitly stating the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers error behavior (GDELT fallback, USPTO soft-fail), making the tool's behavior complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining `since` accepts ISO or relative shorthand, giving examples ('7d', '30d', '3m', '1y'), and recommending '30d' or '1m' for typical monitoring. This is beyond the schema's basic type descriptions.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific verbs like 'fans out' and 'returns'. It includes user query examples ('What's new with X') and explicitly differentiates from the sibling tool entity_profile, making the purpose highly unambiguous.

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

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

Provides explicit usage guidance by naming the alternative tool: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This tells the agent exactly when to choose this tool versus a sibling.

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

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

Beyond annotations, the description adds critical context: storage as a key-value pair scoped by identifier, persistence differences for authenticated vs anonymous users (persistent vs 24 hours), and the explicit relation with recall/forget. This provides valuable behavioral details not present in the annotations.

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

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

The description is concise, front-loaded with the main purpose, and every sentence adds value (purpose, usage, storage details, persistence, tool pairing). No filler or redundant content.

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

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

For a simple 2-parameter write operation with no output schema, the description covers purpose, usage, behavioral traits, and tool relationships comprehensively. There is no missing information that would hinder an agent from using the tool correctly.

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

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

Schema description coverage is 100%, and the schema already provides clear parameter descriptions with examples. The description reinforces the key-value nature but adds little beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Save data the agent will need to reuse later') and clearly distinguishes itself from siblings by naming the paired tools 'recall' and 'forget'. It also provides concrete examples of what to store, making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' and lists example scenarios. It also tells the agent to pair with 'recall' and 'forget', which serves as a clear alternative/complementary usage guide, effectively distinguishing from siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations: 'Each call cascades through several lookup endpoints internally' and details the exact return values (ticker, CIK, RxCUI, citation URIs). This enriches the agent's expectation of behavior without contradicting annotations.

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

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

The description is front-loaded with the core purpose and usage guidance, then breaks down supported types in an organized way. It is somewhat long but every sentence conveys necessary information about outputs and internal behavior. A more compact version could omit some example queries, but overall it is 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?

With no output schema, the description fully compensates by describing return types for both entity categories, including citation URIs. It also explains internal cascading calls and clarifies accepted input formats. For a tool with two parameters and no output schema, this description is complete for an agent to 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%, so the baseline is 3. The description adds meaningful extra detail: it explains the 'value' parameter accepts ticker, CIK, or name for companies and notes auto-disambiguation; for drugs it mentions brand/generic names and examples. It also clarifies the 'type' enum values. This goes beyond the schema descriptions.

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

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

The description explicitly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete example queries and clearly distinguishes the resource (entities like companies/drugs) and the action (resolving to IDs). This differentiates it from sibling tools like entity_profile or compare_entities.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces multiple manual lookups. However, it does not explicitly mention when not to use it or name alternative tools for comparison, 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?

Beyond the annotations (readOnly, idempotent), the description reveals that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also specifies the return format (score, confidence, signal density), adding meaningful behavioral context.

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

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

The description is two tightly written sentences plus a usage example and an explicit return-value note. Every sentence earns its place, with no redundant or vague wording.

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

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

Despite having no output schema, the description fully explains the process (probing with ai_visibility_check), the competitive audit use case, and the output fields (score, confidence, signal density). Combined with the rich annotations and 100% schema coverage, nothing critical is omitted.

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

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

Schema coverage is 100%, and the description adds only minimal extra meaning beyond reinforcing the existing entity semantics ('your brand + N competitors'). It doesn't fill any gaps since the schema already explains each parameter, so a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, making the purpose unambiguous.

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

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

The description states it's 'Useful for competitive AI-marketing audits' and gives an example query, making the intended use case clear. It implicitly contrasts with ai_visibility_check by focusing on side-by-side comparison, though it doesn't explicitly name the alternative.

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

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

Even with annotations declaring read-only/idempotent behavior, the description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed field indicates timeouts. This goes well beyond the annotation flags.

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 is dense with information: purpose, external sources, use cases, ecosystem scope, return block, and failure behavior. It's front-loaded with the main purpose and flows logically to limitations, with no wasted words.

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

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

With no output schema, the description enumerates the exact summary fields (is_latest, license, bundle sizes, etc.), additional outputs (advisories, links, alternative versions), and explains the non-npm fallback. It also discloses timing and partial failure behavior, making it fully self-contained for an agent.

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

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

The input schema already has 100% coverage with descriptions for both parameters (package and version). The description does not add extra parameter-level meaning; it only mentions version in the context of output fields, not as additional guidance. Therefore baseline 3 is appropriate.

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

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

The description clearly states the composite check purpose: 'should I add this npm package to my project' in ONE call, and it names specific sources (deps.dev and bundlephobia) and outputs. This distinguishes it from sibling tools, none of which are dependency scanners.

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

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

Explicitly tells when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding the agent away from this tool for non-npm ecosystems.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings and cosine similarity over 500-char overlapping windows, and has a 200K character cap with truncation handling. This goes well beyond the annotation hints.

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

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

Though the description is long, every sentence earns its place. It opens with the core behavior, then discusses use cases, return values, and technical constraints. The structure is logical and front-loaded, with no filler or redundant statements.

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

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

Since there is no output schema, the description must explain the return format, which it does: passes with character offsets and similarity scores. It also covers the key use case, the 200K char limit, truncation behavior, and integration with a sibling tool. For a tool of this complexity, the description is remarkably complete.

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

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

Scheme description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for the parameters themselves, but it does frame them nicely: 'Pass the text you already pulled... plus a natural-language query.' This adds a usage context, but for parameter-level semantics, the schema already fully explains each field.

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 performing semantic search inside a provided text record, with a specific verb ('search') and resource ('fetched record'/'text'). It distinguishes from siblings like ask_pipeworx_grounded by saying it searches within a given text, and the title 'Search Within a Source' 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 explicitly states when to use it: 'Use when the record is too big to cram into the prompt.' It also provides guidance on how it complements other tools, saying 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document,' which clarifies when this tool is preferable.

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 useful context by specifying the domain (AFL tipping) and the scope (all registered sources), which complements rather than repeats annotations. No contradictions.

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

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

The description is a single well-structured sentence with a semicolon separating the primary action from usage guidance. Every phrase contributes value, 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?

Given the tool's simplicity (no parameters, output schema present), the description provides everything needed for selection and integration. It states what is listed, the categories of sources, and how to use the output with related tools, making it complete for its scope.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed since the schema is empty. It does convey what the result contains (numeric IDs), which is the relevant semantic here.

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

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

The description clearly states the tool lists all registered AFL tipping sources (models, pundits, bookmakers) with numeric IDs. It differentiates from sibling tools like `tips` and `ladder` by explicitly framing itself as the source of IDs for those tools, making its unique role obvious.

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

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

The description gives clear context: use this tool to obtain numeric IDs for use with `tips` and `ladder`. It doesn't explicitly exclude other tools, but for a simple list tool with no parameters, the guidance is sufficient and direct.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds that the data comes from Squiggle and returns specific fields, but does not disclose edge-case behavior such as handling of missing data or default round when omitted. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that front-loads the main verb and resource, then efficiently adds parameter and output details. There is no redundant or unnecessary wording.

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

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

For a simple read-only tool with rich annotations and an output schema, the description covers the core purpose and data source. The major gap is not addressing the overlapping sibling 'ladder' tool, which is essential for correct tool selection. Also, it doesn't mention default behavior for optional round.

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

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

The input schema has no descriptions (0% coverage), so the description is the only source of parameter meaning. It explicitly states 'year' and 'optional round', clarifying that round is optional. However, it does not provide constraints or what happens when round is omitted, leaving gaps.

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 'Fetch the AFL ladder' with parameters 'year' and 'optional round', and lists return fields. This is specific and identifies the resource. However, it does not differentiate from the sibling tool 'ladder', which appears to cover similar functionality.

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 no guidance on when to use this tool versus alternatives. No alternatives are mentioned, and with a sibling named 'ladder' that likely overlaps, the agent has no criteria for selecting this tool.

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

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

Beyond the annotations (non-destructive, idempotent, open-world), the description adds behavioral context: auth requirement, persistence caveats, SMS verification/cap, webhook signing secret issued once, and auto-disable after 10 consecutive failures. It does not contradict any annotation.

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

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

The description is dense but front-loaded: the first sentence states purpose and return value, followed by prerequisites, type examples, and delivery options. Every clause adds operational detail without 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?

With no output schema, the description correctly identifies the return value. It covers prerequisites, all supported subscription types with examples, delivery channels, rate limits, verification requirements, and failure behavior—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?

Even though the schema already has 100% parameter coverage, the description adds high-value semantic detail: concrete examples for each type (items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE"), clarifies required fields for clinical_trial, and explains delivery channel behavior (email, SMS, webhook with HMAC).

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 ('Create') and a precise resource ('a proactive monitoring subscription to a live-data event stream'), and clearly states the output ('Returns the new subscription id'). This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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 states a prerequisite (Pipeworx OAuth account), a when-not ('anonymous + BYO cannot persist subscriptions'), and an alternative for reading the feed ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). This gives the agent clear conditional 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 mark it read-only, non-destructive, and idempotent. The description adds behavioral context by stating it returns categorized example questions drawn from a live catalog of thousands of tools and that arguments are optional, which enriches beyond the annotations without contradiction.

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

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

The description is longer than minimal but well-structured: opens with user-intent phrasings, then states behavior, categories, invocation options, and usage guidance. Each segment earns its place, though the enumeration of categories and example phrasings adds some length.

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

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

With no output schema and a single optional parameter, the description carries the burden of explaining the return shape and invocation semantics. It thoroughly covers categories, tool+argument examples, optional topic focus, and when to use, making it complete for an onboarding tool.

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

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

The input schema already fully documents the optional `topic` parameter with allowed values and omission behavior. The description reinforces this with examples ('finance', 'pharma', 'betting') and clarifies the distinction between a full cross-category spread and a focused search, adding modest value beyond schema.

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

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

Description clearly identifies the tool as the onboarding entry point for suggesting what to ask Pipeworx. It specifies the return value (category-bucketed example questions with exact tool + argument shape) and explicitly distinguishes it from meta-tools like ask_pipeworx by positioning it as a first stop.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides context about no-arg vs topic-based calls, but does not explicitly state when not to use it or name alternative tools for the same purpose.

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

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

Annotations already declare the tool read-only, idempotent, open-world, and non-destructive. The description adds behavioral context by explaining the year filter and the returned data fields, which helps the agent anticipate results without contradicting the annotations.

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

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

The description is a single sentence that front-loads the core action ('List all AFL teams'), then covers the optional filter and output, with zero extraneous words.

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

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

For a tool with one optional parameter and comprehensive safety annotations, the description fully covers the purpose, the filter's effect, and the output contents. No critical information is missing for an agent to correctly invoke and interpret 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?

With no schema descriptions for the parameter, the description compensates by explaining the `year` parameter's purpose as an optional filter. It doesn't detail format or edge cases, but for a simple numeric year filter, this is sufficient.

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 'List' and identifies the resource 'AFL teams tracked by Squiggle,' clearly distinguishing it from sibling tools that handle games, ladders, or standings. It also specifies the optional year filter and return fields, leaving no ambiguity about the tool's function.

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

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

The description provides clear context that this tool returns team identifiers used across other tools, implying its role as a reference lookup. However, it does not explicitly state when to use it over alternatives or mention exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context such as data source or limitations, but it does not contradict the annotations. With the annotations carrying most of the burden, a 3 is appropriate.

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—a single sentence with no filler. It front-loads the key information without waste, making it easy to parse.

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

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

Despite having output schema and annotations, the description is too sparse to be complete. It leaves unclear what the output structure is (though schema covers it) and does not explain the meaning of 'year' and 'round' parameters. More detail is needed for full contextual understanding.

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 only 33% (only 'source' is described). The description 'per game per source' hints that 'year' and 'round' help identify games, but it does not explain the format or allowed values for these parameters, so it only partially compensates for the low schema coverage.

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

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

The description 'Tips per game per source' clearly identifies the resource (tips) and the scope (per game per source), making the tool's purpose understandable. However, it lacks a verb and does not differentiate this tool from siblings like 'games' or 'sources', so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives. The description merely states what the tool returns without any context about scenarios, prerequisites, or exclusions, leaving the agent without direction on tool selection.

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

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

The description adds significant behavioral details beyond the annotations: ownership enforcement and the fact that the row is deactivated (not deleted), preserving historical events. This complements the annotations (destructiveHint=false, idempotentHint=true) by explaining the soft-delete 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 concise and well-structured, with three short sentences that front-load the purpose, then add ownership and side-effect context. No fluff or redundant information.

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

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

For a simple tool with one parameter, the description covers key aspects: what it does, ownership constraints, and the side effect of deactivation. It references recent_alerts for historical availability. Minor gaps remain, such as explicit return value semantics, but the overall context is strong.

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

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

The input schema already provides 100% coverage for the parameter, describing 'Subscription id (uuid) returned by subscribe.' The description does not add any additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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) but does not explicitly mention alternatives or exclusions. It implies the tool is for canceling subscriptions that the user owns, but lacks direct guidance on when not to use it.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it explains the two-path pipeline (SEC EDGAR/XBRL fast path vs. grounded fallback), the exact verdict set, the nature of evidence (verbatim, with pipeworx:// citations), and how tolerance_pct overrides default logic. No contradiction with annotations.

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

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

The description is dense and information-rich but presented as a single long paragraph. It front-loads examples and use cases but then rambles slightly with repeated references to 'grounded' and the efficiency claim. While every sentence contributes value, the structure could be improved with bullets or shorter sentences.

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

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

With no output schema, the description fully covers return values: verdict categories, actual value, citation, and reasoning. It also explains the routing logic and parameter behavior, making the tool's behavior predictable in various scenarios. This is complete for an agent to 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%, but the description adds meaningful semantics beyond the schema. For tolerance_pct, it explains the default behavior ('implied by wording, capped at 5') and gives practical guidance ('set 1–2 for hallucination detection'), which the schema does not. The claim parameter is well exemplified in both schema and description.

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

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

The description opens with concrete natural-language examples that clarify the tool's purpose: claim verification against authoritative sources. It uses specific verbs ('verify', 'fact check') and explicitly distinguishes itself from siblings by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and gives detailed routing rules (company-financial vs. any other factual claim). It does not explicitly list when-not-to-use or name alternative tools, but the context is clear enough for selection.

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