Digitraffic Ais

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

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: regional coverage limitations, the 0.5-knot moving threshold, the returned data categories, and a data timestamp. This significantly exceeds what annotations alone 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 front-loaded with the core purpose, then efficiently covers input modes, output details, coverage caveats, and a concrete example. Every sentence carries useful information without redundancy.

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

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

With no output schema, the description fully explains the return structure (total, by_category, moving/stationary, timestamp). It also covers regional behavior and provides examples, making the tool self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds valuable constraints like the exclusive OR between circle and bounding box, radius defaults/maximums, and clarifies the vessel_type filter is applied before counting. This is meaningful added context.

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

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

The description clearly states the tool counts ships in an area, broken down by category and movement, with example queries. It does not explicitly differentiate from sibling tools like ais_vessels_near, so it misses the top mark.

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 (counting queries) and how to specify an area via circle or bounding box. However, it does not explicitly state when not to use it or name alternative tools, so exclusions are missing.

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

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

The description adds significant behavioral context beyond the readOnlyHint and other annotations by listing the exact returned fields (e.g., 'name, call sign, IMO number, ship type...' and the AIS position details). It also discloses the regional limitation. However, it does not specify behavior when an MMSI is not found or is outside coverage, which could be a useful addition.

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

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

The description is four sentences with a clear front-loaded purpose. Each sentence earns its place, though the enumeration of return fields is somewhat lengthy. Still, it is well-structured and not wasteful, earning a solid score.

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

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

For a single-parameter lookup tool with no output schema, the description is remarkably complete. It explains what the tool does, the exact return contents, the input sourcing flow, and an example. The only missing piece is explicit error behavior, but that is minor given the otherwise comprehensive coverage.

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

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

Schema coverage is 100% with the mmsi parameter already well-described as a 9-digit number. The description adds an example and suggests using ais_vessels_near to obtain the MMSI, but this doesn't fundamentally alter parameter semantics. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Look up one specific ship by its MMSI number and get its registered details plus its latest AIS position.' It distinguishes from sibling tools by emphasizing 'one specific ship' and even names ais_vessels_near as the source for obtaining an MMSI, 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?

Usage guidance is explicit: it provides example queries like 'where is MMSI 230052800' and instructs to 'Get an MMSI from ais_vessels_near first.' The regional coverage note ('COVERAGE IS REGIONAL') also sets expectations about when the tool will succeed, effectively giving alternation and precondition guidance.

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

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

The description discloses the critical regional coverage limitation ('COVERAGE IS REGIONAL... Points elsewhere in the world return nothing') and describes raw data freshness, building on the readOnlyHint and openWorldHint annotations. This adds substantive behavioral context beyond what annotations provide.

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

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

The description is a single dense paragraph but front-loads purpose, then output fields, usage examples, and coverage. No filler or repetition; every sentence adds value.

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

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

Despite lacking an output schema, the description enumerates all returned per-ship fields and covers edge cases (points outside coverage return nothing). Combined with the detailed parameter schema and read-only annotations, this provides sufficient context for correct use.

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

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

The input schema already describes all five parameters with high coverage (100%). The description contributes usage examples (Helsinki coordinates, vessel_type filter) and clarifies the meaning of vessel_type, but these are supplementary to the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool returns live vessel positions near a point, and enumerates the returned fields (MMSI, name, type, speed, etc.). This specific scope distinguishes it from siblings like ais_area_count (counts) and ais_vessel (single vessel detail).

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

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

The description provides explicit example queries ('what ships are near Helsinki', 'vessel traffic outside Turku') and notes regional coverage, guiding when to use it. However, it does not name alternatives or explicitly say when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the default free model, the BYO Anthropic key cost implication, and the return structure (per-model score/confidence/signals/raw_response + combined view). This goes beyond what annotations alone 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 four sentences, each serving a distinct role: main function, default/cost, return format, and use cases. No redundancy or filler—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 4-parameter tool with no output schema, the description covers the core purpose, parameter behavior (default/free, optional Anthropic), return structure, and use cases. It doesn't detail scoring methodology or signal meanings, but given the strong schema descriptions and annotations, it is still adequately complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful detail beyond the schema by naming the default model (Workers AI Llama-3.3-70b) and clarifying that using Anthropic requires the user's API key and direct payment. This enhances parameter understanding.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') with a clear output (visibility score 0-100). It clearly defines the domain (business/brand/product/topic). However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it misses the 'distinguishes from siblings' criterion.

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 usage contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and _apiKey option. It does not mention when to use alternatives or provide exclusions, but the context is clear enough for an agent to decide when this tool applies.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the tool routes to thousands of tools, fills arguments, returns structured answers with citation URIs, and is fast (one call). It also covers its behavior for live news/breaking queries. No contradictions with annotations, but it stops short of detailing exact output format or any limitations.

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

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

The description is dense and front-loaded with the critical 'PREFER OVER WEB SEARCH' guidance. Each sentence adds meaningful context, though the long list of examples and the closing note on news make it slightly longer than strictly necessary. Still, every part serves a purpose.

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

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

Given the tool's role as a default entry point, the description is highly complete: it states what it does, when to use it, gives examples, explains the return concept (citation URIs), and differentiates from siblings. No output schema exists, so the description's explanation of the structured answer format is sufficient. It even covers edge cases like breaking news.

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 covers all parameters as aliases for the question (100% coverage). The description adds concrete examples and lists domains (SEC filings, FDA data, finance, weather, etc.), which clarifies acceptable question content and helps the agent formulate queries appropriately, exceeding the baseline 3.

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

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

The description clearly states the tool's function: it routes factual questions to one of 5,322 tools across 1,393 verified sources, fills arguments, and returns structured answers with citation URIs. It explicitly distinguishes itself from web search, ask_pipeworx_grounded, and deep_research, making its purpose unmistakable.

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

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

The description provides explicit usage guidance: prefer over web search, use for factual questions, and start here for most queries. It also names alternatives (ask_pipeworx_grounded, deep_research) with specific conditions for escalation, and gives concrete example phrasings and query types.

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. The description adds valuable context beyond annotations: it's experimental, may have routing improvements enabled live, currently has no active candidate (as of a specific date), matches ask_pipeworx exactly, and is a full working router (no fallback). This provides a clear behavioral profile not available from annotations alone.

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

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

The description is four sentences, each earning its place: beta nature, current state, usage guidance, and fallback clarification. It front-loads the key differentiator and avoids redundant wording while maintaining a clear structure.

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

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

For a beta experimental router with no output schema, the description is remarkably complete. It covers what it is, current behavior (no candidate active), when to use it, and its relationship to the stable router. The mention of 'same response shape' addresses return values indirectly. No critical gaps for an agent selecting and invoking this 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?

Input schema covers 100% of parameters with descriptions for 'question' and all aliases. The description adds no specific parameter semantics beyond 'same arguments' as ask_pipeworx, which is vague. Since the schema already documents the parameters well, baseline 3 is appropriate.

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

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

The description clearly identifies it as a beta version of ask_pipeworx, a universal router to 5,322 tools, and distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded by its experimental routing. The action is implicitly 'ask/route' and the resource is explicitly the Pipeworx universal router, with scope and differentiation clearly stated.

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

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

Explicit guidance given: 'Use it exactly like ask_pipeworx when you want the newest routing.' This directly states when to use, and the contrast with 'stable router' implies when not to use (when stability is preferred). It also names the alternative ask_pipeworx and explains the comparison purpose for routing decisions.

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

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

The description reveals behavior beyond the readOnly/openWorld/idempotent annotations: it returns a specified JSON structure with evidence (verbatim quote), confidence, and refusal reasons enumerated ('not_in_source', 'no_tool_match', etc.). It also discloses the extra LLM call cost and the constraint that answers are extracted 'using ONLY what the tool result contains.' 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?

Despite being moderately long (~150 words), every sentence contributes: purpose, mechanism, return format, usage scenarios, and cost tradeoff. It is front-loaded with the key purpose and ends with an actionable recommendation, avoiding redundancy and excessive detail.

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

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

The tool has no output schema, so the description compensates by fully specifying the success return object ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal object with all possible reasons. Combined with comprehensive annotations and a fully documented input schema, an agent has complete context to select, invoke, and interpret this tool correctly.

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

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

The input schema covers all six parameters (question and aliases) with 100% description coverage, so the schema already documents parameter semantics. The description adds no extra information about how to formulate the question or what it should contain, only clarifying that the tool accepts a natural language question implicitly via usage guidance. This matches the baseline for high schema coverage.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads,' explaining it routes like ask_pipeworx and extracts answers strictly from tool results. This specific verb and resource differentiates it from sibling ask_pipeworx and ask_pipeworx_beta by its evidence-cited output.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and gives a counterexample: 'prefer ask_pipeworx for casual lookups.' Also mentions the cost tradeoff ('Costs one extra LLM call'), guiding the choice between this and the 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?

The description goes far beyond the readOnly/idempotent/openWorld annotations by disclosing detailed behavioral traits: fan-out to category-specific data packs, resolver contract with match confidence and alternatives, parent_event extractor behavior, news fallback fields, low-confidence short-circuit with status suppression, closed-market handling, wide-spread tradeability warnings, and resolution-rule parsing with ev impact. These are genuinely useful behavioral disclosures that the annotations do not capture.

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

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

The description is long but densely packed and well-structured with labeled sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). It front-loads the core purpose, then systematically addresses behavioral edges. Every sentence provides actionable information—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?

With no output schema, the description carries the full burden of explaining return values and edge cases. It thoroughly documents result shapes (market, analysis, evidence), the resolver contract, parent_event details, news fallback fields, status codes (low_confidence_match, market_closed_or_inactive), and tradeability warnings. For a tool of this complexity, the coverage is exceptionally 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 has 100% description coverage for all three parameters, including the 'market' input modes, 'depth' enum meanings, and 'include_raw' size implications. The description adds some context (e.g., 'quick = 2-3 evidence sources' is in schema, but description's fan-out examples inform what 'thorough' entails), but the schema carries the main burden. Since schema coverage is complete, baseline 3 is appropriate; the description does not meaningfully add to 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+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the resolution, classification, fan-out, and evidence-return flow. The explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further differentiate it from sibling tools like polymarket_arbitrage or validate_claim.

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 the intended use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives guidance on when to inspect resolution-rule risk before sizing sports/esports bets. However, it does not explicitly state when NOT to use this tool or name alternative sibling tools as better fits, so it stops short of a full 'when/when-not' contrast.

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 well beyond annotations by disclosing data sources (SEC EDGAR/XBRL, FAERS), metric details (revenue, net income, adverse events), handling of off-calendar fiscal years, sorting behavior, and return format with citation URIs.

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

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

The description is dense but front-loaded with trigger phrases and usage guidance. Every sentence adds value, though some redundancy exists between 'ONE parallel call' and 'Replaces 8–15 sequential lookups.' Still well structured with type-specific 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?

Despite no output schema, the description covers what the agent needs: return format ('paired data + pipeworx:// citation URIs'), sorting by primary metric, and type-specific behavior for company vs drug. This is complete for an agent to invoke and interpret results.

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

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

Although schema coverage is 100%, the description deepens parameter meaning: it explains what type='company' vs 'drug' pulls, gives concrete value examples (['AAPL','MSFT'], ['ozempic','mounjaro']), and clarifies array constraints by stating 2–5 entities.

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

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

The description clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs (compare, rank, head to head) and distinguishes the resource (entities) while differentiating from sequential single-entity 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?

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' The description provides trigger phrases and clarifies when each type (company/drug) is appropriate, and states it replaces multiple lookups.

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

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

The description richly augments the annotations by disclosing account/paid-tier requirements, latency expectations (15-60s, up to ~90s), output structure (findings packet with evidence/confidence/source/citation, gaps[], contradictions[]), the second-hop iteration behavior, and semantic excerpting of large records. It does not contradict the readOnly, idempotent, or non-destructive 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?

Although long, the description is densely packed with non-redundant, high-value information: account requirements, alternatives, mechanism, output contract, gaps behavior, hop iterations, and latency. It is front-loaded with the most critical constraint (account required) and every sentence contributes actionable context for a complex tool.

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

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

Given the absence of an output schema and only two simple parameters, the description fully compensates by explaining the return format, the meaning of gaps[], contradictions[], citation URIs, hop field, semantic excerpting, and expected latency. It also covers limitations and alternatives, making the tool's behavior understandable and predictable 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 provides 100% coverage for both parameters: 'question' is described as natural-language and multi-part, and 'depth' includes detailed enum semantics (quick/standard/thorough) including the paid plan and contradictions. The tool description largely restates these details and adds no significant new parameter-level meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' and explains that it decomposes questions into facets and routes them to tools in parallel. It explicitly distinguishes itself from siblings by noting it is NOT open-web search and contrasts with ask_pipeworx for single lookups and breaking-news queries.

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

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

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also states the account prerequisite and advises using ask_pipeworx if not signed in, covering when-to-use and when-not-to-use with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and emphasizes that 'each result is ready to call directly, no second schema lookup needed.' This clarifies the tool's output and the convenience of its results, which goes beyond the structured annotations.

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

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

The description is three sentences long, each sentence earns its place: the first states the core purpose, the second details what the tool returns and its self-contained nature, and the third gives a clear priority usage directive. It is front-loaded with the most important information and contains no fluff or redundancy.

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

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

For a discovery tool with no output schema, the description is complete: it explains what the tool does, when to use it, what results look like (names, descriptions, full input schemas with curated examples), and that results are directly callable. It covers the domain scope, the return behavior, and the 'call first' strategy, leaving no critical gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the schema fully documents all six parameters (query, q, task, search, description, limit), with aliases explained. The description adds meaning beyond the schema by listing the domains of interest (SEC filings, financials, FDA drugs, etc.), which helps users formulate a query. This is extra helpful context that the schema alone does not provide.

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 identifies the verb (find) and resource (tools). It further distinguishes itself from sibling tools by framing discover_tools as a meta-tool that lists available tools, while siblings like deep_research or entity_profile perform specific tasks. The domain list (SEC filings, financials, FDA drugs, etc.) clarifies the breadth of coverage.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and gives a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and implies that when you already know the specific tool, you can skip discovery. It effectively distinguishes the tool's role from the specialized sibling tools.

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

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

The description goes beyond the annotations by disclosing non-obvious behaviors: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' in parallel, highlights a soft-fail for the USPTO API sunset, mentions a GDELT→GNews fallback, and notes the limit of up to 5 filings. These details add significant value beyond the readOnly/idempotent hints.

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

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

The description is a single dense paragraph but highly efficient, with every sentence carrying relevant information. It is front-loaded with user-friendly examples, then covers behavior, return fields, and caveats. Though lengthy, it avoids verbosity and remains structured around the tool's key aspects.

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

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

Without an output schema, the description fully enumerates all returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), including ordering and formatting. It also covers input constraints, fallback behavior, and the parallel nature of the call, making it complete for an agent to understand the tool's full 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 input schema already provides full descriptions for both parameters, including the zero-padded CIK requirement and naming limitation. The description adds only examples ('AAPL', '0000320193') that echo the schema, providing no additional semantic meaning beyond what is already structured.

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

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

The description states a clear purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific output components and distinguishes itself from siblings like resolve_entity and deep_research by specifying when to use it. The example queries provide concrete invocation triggers.

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

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

Explicit usage guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when NOT to use it: 'names not supported (use resolve_entity first if you only have a name).' This clearly 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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description consistently says 'Delete' without contradiction. It adds context about what kind of data is affected ('previously stored memory', 'sensitive data') beyond the structured annotations, though it doesn't elaborate on irreversibility or side effects.

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

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

Three sentences, each earning its place: purpose, use cases, and relationship to siblings. 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?

For a simple one-parameter destructive tool with no output schema, the description covers purpose, when to use, and sibling context. Combined with strong annotations, the tool is fully understood.

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 fully documents the only parameter 'key' with description 'Memory key to delete' (100% coverage). The description adds the phrase 'by key' but no additional parameter-level detail, so it neither enhances nor detracts from 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 clearly states the tool's function: 'Delete a previously stored memory by key.' The verb 'Delete' and resource 'memory' are specific, and the mention of 'by key' distinguishes it from sibling tools like remember and recall.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also advises pairing with remember and recall, which clarifies the relationship to alternatives.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds behavioral context by explaining the fetch/extract/emit workflow and the text blob output, which is useful beyond the annotations. No contradictions found.

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: first sentence states primary purpose, second explains the method, third lists use cases. Every sentence adds value, with no redundancy or filler.

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

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

For a simple tool with 2 parameters, the description provides complete context: what it does, how it works, what output to expect, and typical scenarios. Annotations cover safety, so no gaps remain.

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

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

The schema description coverage is 100% for both parameters (url and max_links), so the description does not need to add parameter details. The description does not elaborate on max_links semantics beyond the schema, maintaining the baseline for high coverage.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the process (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown), distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description lists concrete use cases (client indexing, personal project drafting, competitor auditing), providing clear context. However, it does not explicitly mention when not to use the tool or name alternative tools, so it falls short of a perfect score.

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 this as a read-only, idempotent, non-destructive operation, so the safety profile is clear. The description adds value by disclosing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the scope ('caller's'), which are not in the annotations or schema. This provides useful behavioral context beyond the structured data.

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

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

The description is two sentences that are front-loaded with the action and return format, followed by a concrete use case. Every sentence earns its place, with no filler or redundancy. This is an exemplary model of concise, high-value description.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is fully complete. It lists the return fields, explains the scope, and provides usage motivation. The schema covers the parameter, so there's no missing information that the description needs to supply.

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 covers 100% of the parameters (only include_inactive), and its description fully explains its behavior. The tool description does not add any additional meaning about the parameter, so the baseline of 3 is appropriate. The description's mention of 'active subscriptions' implies the default behavior but doesn't elaborate beyond what the schema already states.

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

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

The description clearly states the verb ('List') and resource ('the caller's active subscriptions'), making the tool's purpose unambiguous. It also differentiates from sibling tools like subscribe and unsubscribe by specifying it is for listing, and includes the return fields, providing a complete picture.

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 usage context: 'review what you're monitoring before adding more or to find an id to cancel.' This implicitly guides when to use this tool versus subscribe/unsubscribe, though it doesn't explicitly name alternatives. It's strong guidance but not as explicit as naming when not to use each 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?

The description discloses several behavioral traits beyond the annotations: rate limit (5 per identifier per day), cost (free, no quota), and team review cadence (digests daily, affects roadmap). Since annotations only state flags like readOnlyHint=false, this added context is valuable and not contradictory.

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

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

The description is efficiently structured with a purpose statement, usage conditions, content guidance, and operational constraints (rate limit, quota). Every sentence earns its place without redundancy, and it's appropriately sized for the tool's complexity.

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

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

Given the tool's moderate complexity (nested context object, enum type) and absence of an output schema, the description is complete: it explains feedback categories, provides content rules, notes rate limits, and clarifies that it's free. No critical gaps appear for an agent to use this 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?

While the schema already provides detailed descriptions for all parameters, the tool description adds crucial usage semantics: instructing the agent to describe issues in terms of tools/packs and to avoid pasting the end-user prompt. This goes beyond schema-level descriptions and improves invocation quality.

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

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

The description opens with a clear verb and resource ('Tell the Pipeworx team...') and immediately enumerates feedback categories. It uniquely identifies this tool among siblings, which are mostly data-fetching tools, by focusing on submitting feedback rather than retrieving information.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and gives a clear exclusion ('don't paste the end-user's prompt'). This is exemplary usage guidance that helps the agent decide exactly when to invoke this tool and how to frame the input.

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, idempotentHint, etc.), the description adds important behavioral context: it is derived from CF analytics-engine, contains no PII, outputs only (pack, tool, count), and is cached 5min-1h depending on the window. These details disclose freshness and privacy characteristics not captured by 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 front-loads the main purpose and then presents a structured list of use cases followed by technical details. It is somewhat verbose but each sentence contributes value—purpose, use cases, and data provenance/caching. It earns a 4 for good organization and no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers return values (top tools, top packs, total call volume), the data format (pack, tool, count), and caching behavior. It gives the agent enough information to correctly select and invoke the tool, so a 5 is justified.

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 explains the 'window' parameter with its default and the trade-off between short and long windows. The description merely repeats the window options in the opening sentence without adding new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d). The verb 'Returns' and specific resource make the purpose unambiguous. It also distinguishes itself from sibling tools by focusing on aggregate call trends rather than individual queries or discovery.

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 includes an explicit 'Useful for' list with three concrete scenarios: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. This gives clear when-to-use context, but it does not mention alternatives or explicitly state when not to use the tool, so it falls short of a 5.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds significant behavioral nuance: partition filter placeholder logic, semantic anchor Jaccard similarity, fill check against live CLOB depth, and the warning that realizable_edge_pp ≤ 0 means do not trade. This goes well beyond annotation basics.

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 front-loaded with the core purpose and mode selection. It is well-organized with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), but a few sentences could be tightened without losing value. Still, it earns its length given the tool's complexity.

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

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

With no output schema, the description fully discloses the response shape: opportunities[] with gap_pp, suggested_trade, reasoning, partition_check details, and fill check fields. It covers edge cases, filters, and safety conditions, making it complete for an arbitrage 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?

Although the schema already covers both parameters 100%, the description enriches them with concrete examples ("fed-decision-may-2026"), mode-specific behavior, and how each parameter changes the scan scope and output. This far exceeds 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 opens with a specific verb and resource: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It distinguishes between trending_scan, event, and topic modes, clearly differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit usage guidance is provided: "Call with NO args for a trending_scan," "pass event for..." and "topic for..." It even recommends when to use each mode and directs to polymarket_fill_risk for custom sizing, serving as an explicit 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?

With annotations already declaring readOnlyHint and destructiveHint, the description goes far beyond safety by detailing algorithmic behavior: the three model families, placeholder-slug filters, partition overround with per-sport biases, the 24h-move warning, exclusion of Fed bets with reasoning, diagnostics, and KV-level caching. This is extensive behavioral disclosure that adds significant 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 dense but well-structured: purpose first, then model segments, response shape, knobs, and diagnostics. Every sentence contributes unique information; there is no repetition or padding. Despite its length, the complexity of the tool justifies it, and the front-loaded purpose makes it immediately scannable.

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

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

With no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and why segments can be empty. It covers the models' logic, filters, and caching. For a tool of this complexity with zero output schema, 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?

Schema description coverage is 100% and the schema entries are already detailed. The description adds useful context about how knobs interact, e.g., "TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable" and explains the special relationship between min_partition_leg_kelly and partition overrounds. This elevates it above the baseline 3, though not to a 5 since much of the semantics are already in the schema.

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

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

The description opens with a specific verb+resource+scope: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It also clarifies the intended use case ("what should I bet on today") and distinguishes this tool from siblings like polymarket_arbitrage by focusing on model-driven edges rather than pure 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 clearly establishes the discovery use case: "agents discover opportunities without paging hundreds of markets." It also explains specific filtering knobs (min_liquidity, max_spread_pp, etc.) and what situations they are for. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a full 5.

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

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

The description adds extensive behavioral detail beyond the annotations. It discloses the response structure (tracked[], expired[], snapshot_dates[]), explains what each field means (including sign of edge_pp_net, trend categories, decay computation), and reveals limitations (60-day snapshot TTL, cache-miss gaps, daily closes not intraday, net of default slippage). This far exceeds the readOnly/idempotent hints.

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

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

The description is long but well-structured: a concise purpose statement, a clarifying question, an Args section, a detailed RESPONSE breakdown, and a LIMITS section. Every sentence earns its place, though the RESPONSE section is arguably more verbose than necessary. The front-loading is effective.

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

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

With no output schema, the description fully explains the return values and their semantics, including edge cases (expired opportunities, snapshot gaps). It also covers parameter behavior, data source provenance, and computational methodology. For a tool with this complexity, the description is exceptionally complete.

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

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

The schema already provides 100% coverage of the two parameters (days with default/clamp, window with allowed values). The description's Args section mostly repeats this information, with only a slightly different phrasing ('max 30' vs 'clamp 2-30'). No additional semantic meaning is added 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 a specific verb+resource: it tracks edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges (source snapshots) and polymarket_arbitrage by focusing on temporal persistence/decay rather than detection 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 gives clear context on when to use it: when the age of an edge matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternative tools or state when not to use it, but the context is unambiguous. Sibling tools like polymarket_edges are implied as the snapshot source, not as a replacement.

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 well beyond the readOnlyHint/idempotentHint annotations by detailing specific behavior: walks the order-book ladder, returns metrics like vwap_fill_price, slippage_pp, shares_filled, and warns about thin legs and forced directional risk. No contradiction with annotations; adds meaningful operational context.

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

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

The description is long but well-structured with REQUIRES, SINGLE-MARKET, and BASKET labels, and the purpose is front-loaded. Every sentence carries useful information, though it could be tightened slightly by removing a few parenthetical redundancies. Given the tool's complexity, the length is justified.

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

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

Covers both operation modes, input disambiguation (market vs event), return fields, risk warnings, default values, clamp ranges, and the strategic context for use. With no output schema, this description fully equips an agent to understand what the tool does and what it returns.

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?

Adds mode-specific meaning to all parameters beyond the schema: `market` is single-market mode, `event` is basket mode, `side` has different semantics per mode, and `size_usd` is 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional' in basket. This enriches the schema descriptions substantially.

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

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

The description begins with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal detection.

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

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

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of not using it (partial fills convert arb into unhedged directional position), providing strong context for 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses substantial behavioral details: compatibility_warning fires under two specific conditions, temporal_alignment indicates whether spreads are meaningful, and skipped_cross_type/subtype expose which comparisons are dropped. It also explains that mismatched bet shapes (e.g., range_bucket vs cumulative_threshold) mean 'no arb exists.' This far exceeds what annotations convey.

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

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

The description is long but well-structured with clear sections: core definition, two modes, response format, safety fields, temporal alignment, and a warning. Every sentence contributes useful information, though some redundancy exists around the 'pre-mapped ≠ tradeable' caution. The length is justified by the tool's complexity, but it could be tightened slightly by removing repeated warnings.

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 thoroughly explains the response structure: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_cross_type/subtype counts. It also covers edge cases (matched_pairs:0 with various skipped_cross_type values) and explains why they occur. This gives an agent all the information needed to interpret results and decide if the spread is meaningful.

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 parameter names and descriptions are already present. The description adds meaning by explaining the relationship between the parameters: topic is a shortcut, while kalshi_event_ticker and polymarket_event_slug override the mapped event and enable custom pairings. It clarifies that topic and explicit parameters are mutually exclusive modes, but it doesn't add syntax-level detail beyond the schema.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on the cross-venue comparison, and it explains the two modes (topic shortcuts vs explicit pairings) that define its scope.

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

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

The description clearly explains two usage modes (topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug) and provides a strong caution: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' It does not explicitly compare to sibling tools, but it gives clear context for when to use this tool versus relying on simple mappings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context beyond annotations: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys when the key is omitted. It does not cover potential return errors or fallback behavior, but given the annotation coverage, the added context is meaningful.

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

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

Two sentences, front-loaded with the primary action, then scoping and companion tool relationships. Every sentence adds value with no repetition or fluff.

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

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

The tool is simple (one optional parameter, no output schema), and the description provides enough context for an agent to use it correctly: what it retrieves, how to list all keys, and the scoping model. It does not mention what happens if the key doesn't exist, but that is a minor gap given the low complexity.

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

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

Schema coverage is 100% and the single parameter already has a clear description ('Memory key to retrieve (omit to list all keys)'). The description reinforces this behavior but does not add new semantic information beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Retrieve' / 'list') and resource ('value previously saved via remember' or 'saved keys'). It explicitly distinguishes from sibling tools: remember saves, forget deletes, recall retrieves. The examples (ticker, address, research notes) further clarify scope.

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

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

Provides clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Mentions pairing with remember and forget, which implies when to use this tool vs alternatives. It does not explicitly state when NOT to use it, 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 discloses the mark_read side effect and return payload structure, but it contradicts the idempotentHint annotation. Setting mark_read:true causes state changes, making repeated calls non-idempotent, which violates the idempotentHint promise. This is a clear annotation contradiction.

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

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

The description is concise and front-loaded with the main purpose. Each sentence adds valuable details: return fields, filtering, mark_read side effect, polling, and an alternative access endpoint. There is no wasted text.

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 adequately explains what is returned (source, citation_uri, raw payload) and covers key behavioral aspects like the persisted feed and polling. Despite the annotation conflict, the description itself is complete for a tool with five optional parameters.

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

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

The input schema already provides 100% description coverage for all five parameters. The description adds minimal extra nuance, such as the type example 'sec_8k', but mostly restates schema information, 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 pulls fired events from the subscription feed and returns the most recent alerts, using a specific verb and resource. It differentiates from sibling tools like list_subscriptions by focusing on alert events rather than subscription management.

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 usage context, including filtering options, mark_read behavior, and polling suitability. However, it does not explicitly mention alternative tools or situations where this tool should be avoided, so it stops 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 indicate readOnly, non-destructive, idempotent, open-world. The description adds critical behavioral context: multi-source fan-out, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, and return structure with 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 but each sentence earns its place: user queries, source list, parameter semantics, and alternative tool. It is front-loaded with natural-language examples that make the purpose instantly clear. Slightly long but not verbose or redundant.

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

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

Despite no output schema, the description tells the caller exactly what to expect: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers edge cases (API sunset, fallback behavior) and clearly scopes to company-type entities. This is fully complete for a decision.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra meaning: explains `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), clarifies `value` can be ticker or zero-padded CIK, and recommends '30d' or '1m' for typical monitoring. This enriches 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 clearly states this is a change feed for a company in the last N days, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. Specific verbs like 'Fans out' and 'Returns structured changes' make the resource and action unambiguous. It also distinguishes from sibling 'entity_profile' by contrasting dynamic changes vs static profile.

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

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

Provides multiple example user intents ('What's new with X', 'latest on Y') and explicitly says 'Use entity_profile instead when you want the static profile'. Also describes fallback behavior for news sources, giving clear contextual guidance. This goes beyond vague usage hints.

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 idempotent and non-destructive hints. The description adds valuable context about scoping by identifier and retention differences between authenticated and anonymous sessions, which goes beyond annotations.

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

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

Three densely packed sentences: purpose, when to use, persistence details, and sibling references. No filler, every sentence contributes.

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

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

For a simple key-value memory tool, the description covers what it stores, when to use it, scoping, persistence, and companion tools. No output schema is needed since it's a write operation.

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

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

Schema descriptions cover 100% of parameters, so baseline is 3. The description reinforces the key-value semantics and gives real-world examples (resolved ticker, user preference) that clarify the intended 'value' content.

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 saves data for reuse, with specific examples (ticker, address, preference, research subject). It distinguishes itself from sibling tools by explicitly naming recall (retrieve) and forget (delete).

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

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

It provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and explains persistence behavior (authenticated vs anonymous). It points to alternative tools (recall, forget) for other operations.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive behavior. The description adds that each call cascades through multiple lookup endpoints, returns citation URIs, and auto-disambiguates input—context beyond the annotation-only safety profile. It does not cover failure or ambiguity edge cases, but the added detail is meaningful and not contradictory.

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

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

The description is well organized around user intents, a clear usage directive, supported types, and return details. It is slightly long because the type/return details are also present in the schema, but it is front-loaded, purposeful, and free of filler.

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

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

With no output schema, the description appropriately enumerates return fields and sources per entity type: ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug—plus citation URIs. It also covers input variants and auto-disambiguation. Error handling and ambiguous-result behavior are not mentioned, but this is adequate for a lookup/resolution 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 documents both parameters with 100% coverage, including concrete examples like AAPL and ozempic. The description reinforces this by listing accepted input forms and return fields, but adds little new syntactic or formatting information 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 opens with concrete user phrasings and explicitly states the tool resolves a user-spoken NAME to the canonical/official identifier other tools require as input. It names source systems (SEC EDGAR, RxNorm) and distinct entity types, clearly distinguishing it from siblings like entity_profile or compare_entities that operate on already-resolved 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?

It provides an explicit directive 'Use FIRST whenever you have a name but need an ID' and notes that it replaces 2-3 manual lookups, making the trigger condition clear. It does not list exclusions or when to choose an alternative tool, so it stops 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses how the tool operates: it probes each entity via ai_visibility_check, ranks results by score, and returns a structured list with score, confidence, and signal density. This adds meaningful behavioral context that annotations alone don't provide, though it doesn't mention authentication nuances or rate limits.

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

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

The description is two sentences long, front-loaded with the primary purpose, and includes a concrete use case and return format without any fluff. Each sentence earns its place, making it highly efficient and easy to scan.

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 what the tool returns (ranked list with score, confidence, signal density). It covers the tool's behavior (probing with ai_visibility_check), the use case, and entity ordering, making it complete for an AI agent to select and invoke correctly. The sibling context and schema handle the remaining 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 100%, with every parameter described in the input schema. The description adds minimal additional semantics beyond the schema—mainly tying 'entities' to the probe operation. Since the schema already documents parameter roles (e.g., first entity as subject, optional models), the description doesn't need to compensate, aligning with the baseline of 3.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side. It specifies the verb 'Compare', the resource 'AI visibility', and the multi-entity scope, distinguishing it from the single-entity ai_visibility_check sibling. The example use case ('does Claude know about us as well as our competitors?') further clarifies intent.

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: competitive AI-marketing audits comparing multiple brands. It implicitly indicates that ai_visibility_check is the underlying single-entity probe, suggesting differentiation. However, it does not explicitly mention alternatives or state exclusions (e.g., 'for a single entity, use ai_visibility_check directly'), 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 adds significant behavioral context beyond annotations: it warns about 5-30s latency for first-time bundlephobia measurements, explains graceful degradation via sources_failed, and clarifies that NPM is the only supported ecosystem in v1. These details help agents anticipate failure modes and timeouts.

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

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

The description is dense but every sentence contributes: purpose, use cases, return field list, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and follows a logical flow, making it information-dense without redundancy.

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

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

For a composite tool that fans out to two external services, the description covers all essential aspects: what it does, when to use it, what it returns (explicitly listing the summary fields and links), ecosystem boundaries, and failure handling. Given no output schema, this description fully compensates.

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

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

The input schema already provides full descriptions for both parameters (package name with scoped support and version default). The description does not add meaning beyond what the schema offers, though it does reinforce the default behavior. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with a specific composite check for npm packages, explaining exactly what it aggregates (deps.dev license/advisories/version history and bundlephobia bundle metrics). It distinguishes from siblings by clearly limiting scope to NPM and pointing out that other ecosystems fall under deps.dev:version directly.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to use (non-NPM ecosystems). Also notes partial failure behavior, which helps agents decide whether to fall back to other tools.

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

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

Annotations already declare read-only/idempotent, but the description goes further: it discloses the return format (top-N passages with character offsets and similarity scores), the underlying mechanics (BGE-base-en embeddings, cosine similarity, 500-char overlapping windows), and the 200K character limit with truncation behavior. This adds substantial context 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?

Despite being a longer description, every sentence is information-dense: purpose, use case, pairing advice, and technical limits. It is front-loaded with the core action and structured logically. No redundant phrasing or promotional filler.

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

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

Given the lack of an output schema, the description compensates by naming the return fields (passages, offsets, similarity scores). It covers usage context, technical limits, edge-case behavior, and integration with a sibling tool. For a read-only search tool with 3 simple params, this is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the schema's param meanings (already-pulled text, natural-language query) and adds one behavioral nuance for the text param: longer inputs are truncated and flagged. This slight enhancement over the schema justifies a 4, though the schema already carries most of the load.

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

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

The description clearly states the tool performs semantic search inside an already-fetched text, using a specific verb+resource ('semantic search INSIDE a fetched record'). It distinguishes itself from sibling tools by emphasizing the input is pre-fetched text, not an external source, and explicitly names ask_pipeworx_grounded as a complementary tool.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the value (saves context, returns only relevant passages). It also provides a pairing strategy with ask_pipeworx_grounded, showing how to use it instead of grounding over the whole document. This is clear and distinguishes it 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?

Despite having annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds substantial behavioral context: it returns a new subscription id, requires authentication, details delivery channel behaviors (feed always on, phone verification, SMS cap), and explains the persistence requirement. This goes well beyond the annotations and paints a clear picture of the tool's runtime behavior.

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

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

The description is dense but well-organized: purpose, return value, requirement, supported types with examples, and delivery options. Every sentence carries useful information, and the structure logically guides the reader from general to specific. No fluff or redundant restatement of the title.

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

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

Given the tool's complexity (3 params, nested delivery object, 5 enum types, no output schema), the description covers all essential aspects: what it does, how to invoke each type, what the return value is, authentication requirements, and delivery channel specifics. It is a complete operational overview 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?

While the schema already has 100% parameter coverage, the description enriches it with concrete examples for each subscription type (e.g., items:["5.02"] = officer change, params:{topic:"fed"}, series_id:"UNRATE"). It also adds practical delivery details like the feed being always-on and the phone verification requirement. This significantly helps an agent understand how to construct valid params beyond the raw schema.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts. It also lists supported subscription types and delivery channels, making the scope unmistakable.

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

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

Usage guidance is explicit: it requires a Pipeworx OAuth account and warns that anonymous/BYO cannot persist subscriptions. It also directs users to pull via recent_alerts or a direct JSON endpoint for the always-on feed, and it identifies when email or SMS are appropriate with constraints (phone verification, 10/day cap). This effectively tells the agent when this tool should be used and what preconditions exist.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive. The description adds useful context about the live catalog and the structure of returned examples, but doesn't disclose additional safety-relevant behavior. This is appropriate for a read-only meta-tool.

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

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

The description is relatively long but well-structured, leading with example queries, then output format, then call variants, then usage guidance. Every sentence contributes useful context, though it could be slightly tighter.

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 adequately explains the return format (category-bucketed examples with tool + argument shape). It covers usage scenarios, parameter behavior, and when to use it, making it complete for an onboarding tool of this simplicity.

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

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

The single optional `topic` parameter is fully described in the schema, including allowed values and behavior when omitted. The description gives examples but doesn't add new semantic information beyond the already-detailed schema.

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

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

The description clearly identifies it as the onboarding entry point for discovering what can be asked of Pipeworx, and explicitly states it returns category-bucketed example questions with the exact tool + argument shape. It distinguishes from siblings like ask_pipeworx by focusing on capability discovery rather than answering a query.

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

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

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools (siblings). It also explains when to call with no arguments vs. with a `topic`.

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

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

The annotations already mark this as non-destructive and idempotent. The description adds important behavioral detail: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts,' disclosing exactly what happens to the data. It also mentions ownership enforcement, which is an important auth requirement.

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

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

Three sentences, each serving a purpose: action, constraint, and consequence. 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 single-parameter tool, the description is quite complete. It covers purpose, ownership, and data persistence. It lacks explicit return value info, but the absence of an output schema and the simplicity of the operation mitigate this. The reference to 'recent_alerts' also helps tie into the system context.

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

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

The input schema has 100% coverage with the parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description does not add any extra meaning to the parameter beyond the schema, so it relies on the schema's description. Per the baseline for high schema coverage, this is a 3.

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

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

The description opens with 'Cancel a subscription by id,' which is a clear verb+resource+scope statement. It also distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by making the cancellation action explicit.

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

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

The description gives context by stating 'Ownership is enforced — you can only cancel your own subscriptions,' which sets a condition for use. However, it does not explicitly name alternatives or when-not-to-use scenarios, so it stops short of full guidance.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses substantial behavioral context: the dual-path execution (structured SEC EDGAR for financial claims vs. grounded pipeline for other claims), the exact percent-delta comparison approach, and the specific verdict vocabulary. It also mentions that it replaces multiple sequential calls, adding operational 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 longer than minimal but well-structured: example queries, use case, routing detail, output summary, and efficiency benefit. Each sentence contributes value, though it could be trimmed slightly without losing essential meaning.

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

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

With no output schema, the description clearly explains the return structure (verdict, grounded/structured actual value, citation, reasoning) and threshold criteria. It covers the main complexity (two paths, tolerance, verdict types) and is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already achieves 100% description coverage for both parameters. The description adds little parameter-specific information beyond what the schema provides (e.g., 'exact percent-delta math' implies tolerance but does not elaborate). This matches the baseline appropriate for high schema coverage.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with a specific verb ('verify') and resource. It enumerates example query forms and explains the two routing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for others), distinguishing it from sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly says 'use whenever the agent needs to check whether something a user said is factually correct,' providing strong usage context. It also describes the routing logic based on claim type, but does not explicitly state when not to use it or name alternatives, so it falls short of the top score.

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