Bls

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

Annotations already declare readOnly=true and idempotent. The description adds key behavioral details: Anthropic requires a BYO key with direct billing, default model is free, and output structure (per-model score, confidence, signals, raw_response + combined). No contradictions with annotations.

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

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

Three efficient sentences. First front-loads core action and output. Second adds optional auth details. Third lists use cases. No filler.

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

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

No output schema, but description covers return structure (score, confidence, signals, raw_response per model + combined). It addresses key details like model selection and API key requirement. Could mention rate limits or caching, but overall adequate given 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% with good descriptions. The description adds value by explaining the default model behavior, the need for '_apiKey' only when probing Anthropic, and how 'context' disambiguates entities. This enriches beyond schema.

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

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

The description clearly states it probes LLMs for brand visibility and scores 0-100. It specifies default model and optional Anthropic probe. It lists concrete use cases (AI-marketing audits, pre-launch checks, competitive monitoring) which differentiates it from sibling research tools.

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

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

The description provides explicit use cases (AI-marketing audits, brand checks, competitive monitoring). It does not directly contrast with alternatives like 'deep_research' or 'compare_entities', but the specific use cases imply when this tool is appropriate.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive behavior. The description adds genuinely useful behavioral context: it routes to 5,724 tools, returns stable pipeworx:// citation URIs, is fast, works on every tier, and is described as the default entry point. 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 longer than average but front-loads the key routing decision ('PREFER OVER WEB SEARCH'), then provides triggers, examples, and escalation paths. Some marketing-style repetition exists, but the structure serves an agent well.

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 what the tool does, what it returns (structured answer with citation URIs), when to prefer it, what alternatives exist, and how to phrase requests with examples. No output schema is present, but the description compensates by describing the return value and usage context thoroughly.

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 all six parameters are clearly documented as aliases of 'question'. The description adds contextual trigger phrases and examples but no new parameter-level semantics, so baseline 3 is appropriate.

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

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

Description states a clear, specific function: route a natural-language question to the right tool among thousands of verified sources and return a structured answer with citation URIs. It explicitly distinguishes itself from web search and names sibling alternatives like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit prefer-over guidance ('PREFER OVER WEB SEARCH'), identifies default entry-point positioning, lists concrete trigger phrases and examples, and explains when to escalate to alternatives. This is exemplary when-to-use vs. when-not-to-use guidance.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond this: it is a live experimental edge, candidate routing improvements are enabled on the fly, and it 'falls back to nothing' — meaning it is a fully functional router, not a wrapper that degrades. 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?

Four sentences, each supplying a distinct fact: identity, current experimental state, usage guidance, and reassurance that it is a full working router. The key differentiator ('identical universal router... same 5,724 tools') is front-loaded, and no sentence is wasted.

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

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

The tool is a simple single-question router with six aliases, and the schema fully documents the parameter. Though there is no output schema, the description points to the stable sibling's 'same response shape', giving the agent a reference for return behavior. It also covers current routing state, fallback, and comparison purpose, leaving no material gaps.

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

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

All six parameters are aliases for 'question' and schema descriptions cover 100% of them, so the schema already carries the full semantic load. The description adds no additional parameter meaning beyond noting 'same arguments' as ask_pipeworx, which is not materially new information.

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 'Beta version of ask_pipeworx' and immediately identifies it as the same universal router with the same 5,724 tools, arguments, and response shape. This clearly differentiates it from the stable sibling ask_pipeworx while making its function evident.

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

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

The description explicitly instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router to decide merges. It even states the current state — no candidate active — which tells the agent when this is effectively identical to the stable tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses critical behavior: it extracts answers only from tool results, returns a structured success object with evidence and confidence, and has an explicit refusal mechanism with specific reasons. It also notes the extra LLM call cost. This goes far beyond what annotations reveal.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then details the return format, refusal reasons, use cases, and cost tradeoff. The structure is logical and easy to parse, with no fluff.

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

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

For a tool with high complexity (routing across 5,724 tools, multiple refusal modes, and no output schema), the description is fully complete. It explains success and failure return shapes, the extra cost, why to use it, and when not to. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% explaining all six parameters (question and aliases). The description does not add extra parameter semantics, but since the schema fully documents them, the baseline 3 is appropriate. No additional meaning is needed.

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 (ask) and resource (Pipeworx grounded) with a defined behavior: hallucination-resistant answer mode for high-stakes reads. It explicitly distinguishes itself from the sibling ask_pipeworx by noting the extra LLM call and use case, so an agent can tell them apart without inspecting schemas.

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

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

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and explicitly prefers ask_pipeworx for casual lookups. This leaves no ambiguity about which tool to choose in different contexts.

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 safe, read-only behavior. Description adds extensive behavioral details: market resolution, classification, fan-out, evidence packaging, status handling (low-confidence, closed markets, wide spreads), cancellation rules, and resolver contract. No contradictions with annotations.

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

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

Long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Front-loaded with main purpose. Some redundancy, but each sentence adds value given the tool's complexity. Could be slightly more concise, but 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?

Given no output schema, description covers all key return fields (market, analysis, evidence, market_match_confidence, parent_event, news fields) and error states (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). Also explains cancellation rules and blocking behavior. Complete for agent understanding.

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

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

Schema coverage is 100% and description adds significant meaning: explains market input formats (slug, URL, question text), depth parameter with quick/thorough behavior, include_raw parameter with size implications. Provides examples and detailed behavior for each parameter beyond schema.

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

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

Clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' Uses specific verb+resource+outcome. Differentiates from siblings by specifying use cases like 'should I bet on X', which are distinct from arbitrage or edge tracking tools.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Does not explicitly state when not to use or compare to alternatives, but context from siblings and the provided use cases give clear guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by stating that the tool returns 'dated data points with values,' providing useful behavioral context beyond the annotations.

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

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

The description is two concise sentences with no filler. It front-loads the core behavior, adds a return-type statement, and provides a concrete example ID, all in an appropriately compact form.

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 lookup tool with full schema coverage, an output schema, and strong annotations, the description is nearly complete. It clearly states the data domain, return format, and required input, though it could briefly differentiate itself from sibling BLS tools.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters, including defaults and the optional API key. The description's 'Provide series ID' and example add minimal meaning beyond what the schema already provides.

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

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

The description uses a specific verb and resource ('Fetch historical time series data') and lists the covered domains, making the tool's purpose clear. It implies a distinction from siblings like bls_latest and bls_search by emphasizing historical series data, though it does not explicitly name alternatives.

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

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

Clear context is provided: the tool fetches historical time series and requires a series ID, with an example ('PAYEMS'). However, it does not explicitly state when to choose this tool over bls_latest, bls_popular_series, or bls_search.

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

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

Annotations already cover readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds minimal behavioral context beyond stating it returns latest value and date. 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?

Two concise sentences: first states the action, second provides usage guidance. No extraneous text, front-loaded with key information.

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

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

Given the tool's simplicity, annotations covering safety, full schema coverage, and presence of output schema, the description is complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with both parameters fully described. The description does not add additional semantic meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'Get' and the resource 'most recent data point for a BLS series'. It distinguishes itself from sibling tools by specifying it retrieves the latest value without historical context.

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 when you need current figures without historical context', providing clear guidance on when to use this tool over alternatives like bls_get_series.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it resolves place names to LAUS series IDs, falls back to county-level data when a city is below the reporting threshold, and explicitly notes the data is not seasonally adjusted.

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

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

The description is compact and well-structured: three sentences with no filler. The first sentence establishes purpose and scope, the second covers resolution and fallback, and the third states the key data caveat. 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?

The description covers the tool's scope, resolution mechanism, fallback behavior, and seasonal-adjustment caveat, which is strong for a simple read tool. However, since there is no output schema, the phrase 'returns recent monthly data' is somewhat thin on the actual return structure, units, or field names an agent should expect.

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

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

Schema coverage is 100%, and the schema already documents each parameter with examples. The description reinforces the place/state format with examples like 'Wake County, NC' and 'Fargo-Moorhead MSA', but it does not add meaningful semantics beyond what the schema already provides.

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

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

The description opens with a specific action and resource: 'Look up the current LOCAL-AREA unemployment rate... for a US county, metro area (MSA), or city/town by NAME.' It gives concrete examples and explicitly distinguishes itself from bls_get_series, making the tool's purpose unmistakable.

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

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

It explicitly states that bls_get_series cannot resolve place names and requires a series ID, which tells the agent when to prefer this tool over that sibling. It also discloses the fallback behavior for small cities and the non-seasonal-adjustment caveat, providing clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds that it returns series IDs and descriptions, but does not disclose other details like pagination or rate limits. Given annotations, this is adequate but not exceptional.

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

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

Two sentences, 20 words, front-loaded with essential information. No filler or redundancy. Highly efficient.

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

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

With a single optional parameter, clear annotations, and assumed output schema, the description sufficiently covers all needed context: what, return types, and usage suggestion. No obvious gaps.

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

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

Parameter schema description covers the parameter fully (100% coverage). Description lists categories slightly differently than schema, but adds no new semantic value beyond schema. 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?

Description uses verb 'browse' and specifies resource 'popular BLS series', indicating what it does and what it returns (series IDs and descriptions). It distinguishes from sibling tools like bls_get_series and bls_search by implying a high-level browsing function.

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

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

Explicitly says 'Start here to explore available data,' giving a clear entry-point context. However, it does not mention when not to use or directly reference alternatives among the sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns matching series IDs and titles, which is consistent. No additional behavioral details are needed beyond annotations.

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

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

The description is two short sentences, front-loads the purpose, and contains no filler. 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?

With an output schema (not shown) and rich annotations, the description is adequate. It could mention that the search is limited to BLS series or that multiple results may be returned, but overall it is sufficient for a simple search tool.

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

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

Schema coverage is 100% and the schema already documents the 'keyword' parameter with examples. The description does not add extra semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Search', the resource 'BLS economic data series', and the method 'by keyword'. It distinguishes from the sibling tool bls_get_series by specifying that it returns series IDs and titles.

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

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

The description explicitly tells when to use this tool (to search by keyword) and when to use bls_get_series (to fetch historical data). However, it does not mention when to use alternatives like bls_latest or bls_popular_series.

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 readOnlyHint, it details data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This significantly aids the agent's understanding.

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

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

The description is thorough but slightly lengthy; it front-loads example queries and prioritizes key info. Could be tightened marginally but remains efficient.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers all necessary aspects: usage, data sources, sorting, return format, and edge cases, making it highly 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 description adds rich context to both parameters: 'type' enum explained with data pulled, 'values' with examples and constraints. With 100% schema coverage, it still adds meaningful interpretation.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with explicit verb phrases like 'Compare X and Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. It lacks explicit 'when not to use' but strongly implies context.

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

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

Discloses account and paid-plan requirements, parallel execution, findings packet structure, gaps[] for unanswered facets, no-fabrication guarantee, contradictions[], latency expectations, semantic excerpting, and the fetchability of citation_uri. This goes far beyond the readOnly/openWorld/idempotent annotations and is fully consistent with them.

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

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

Long but densely packed, with the account/auth caveat front-loaded and every substantive section earning its place. It loses a point because the depth behavior partially repeats the already-detailed schema description, creating mild redundancy.

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

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

For a tool with no output schema, it thoroughly describes the return packet, expected latency, failure mode (empty gaps[] for uncataloged topics), and authentication requirements. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the depth parameter's schema already explains quick/standard/thorough behavior including gap-recovery and contradictions. The description adds minor context like 'multi-step questions resolve in one call' and example questions, but it mostly restates what the schema already documents.

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?

Explicitly states it performs grounded multi-source research over 1497 structured data sources in one call, decomposing questions and routing them to 5,724 tools. It clearly distinguishes itself from open-web search and names the sibling alternative ask_pipeworx, leaving no ambiguity about its function.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also covers auth-tier fallback and gives concrete example queries, so an agent can route correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds value by explaining that results include full input schemas with examples, ready to call, 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?

The description is moderately concise but includes a long list of domains that could be trimmed. It is well-structured with the verb first and usage guidance at the end. Every sentence adds value, but some redundancy exists.

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 compensates by stating that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Given 6 parameters (mostly aliases) and no nested objects, the description is sufficient for the agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description lists aliases (q, task, description, search) but these are also in schema. No additional meaning beyond what schema provides. 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 purpose: 'Find tools by describing the data or task.' It provides specific examples of domains it covers, and it distinguishes itself from sibling tools by positioning itself as a discovery tool for exploring the available options.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on context and helps avoid misuse by implying not to use when the agent already knows which tool to invoke.

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

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

The description discloses important behavioral traits beyond annotations: it explains that the tool fans out across multiple sources and returns specific data (cik, recent_filings with URIs, fundamentals sorted by period_end, patents via USPTO with a soft-fail note, news via GDELT→GNews fallback, LEI via GLEIF). The transparency about the USPTO sunset and soft-failure adds value. No contradiction with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false).

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 every sentence adds value. It begins with usage examples and then details the tool's capabilities. While it could be more structured (e.g., bullet points for return fields), it remains relatively concise and front-loaded with examples. A minor improvement would be better organization, but it is still 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?

Given the tool's complexity (multiple data sources, no output schema), the description is complete. It lists all expected return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and explains behavior for each. The notes about USPTO sunset and fallback mechanisms provide sufficient context for an agent to understand limitations and behavior.

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% description coverage, and the description adds significant meaning. For 'type', it clarifies that only 'company' is supported and that 'person/place coming soon.' For 'value', it explains that it accepts ticker or zero-padded CIK and explicitly states that names are not supported, linking to 'resolve_entity' as an alternative. This provides more context than the schema alone.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It lists the specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs. It distinguishes from sibling 'resolve_entity' by explicitly noting that names are not supported and that tool should be used first if only a name is available.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name).' This clearly communicates the tool's role relative 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 destructiveHint=true and idempotentHint=true. Description adds context about what to delete and when, but does not disclose behavior for missing keys.

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 with no fluff; purpose is front-loaded and all information is relevant.

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?

Simple tool with one parameter, no output schema; description fully covers purpose, usage, and sibling relationships.

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 description only reiterates 'by key' without adding 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?

Description clearly states the verb 'Delete' and resource 'previously stored memory by key', distinguishing it from siblings 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?

Provides specific use cases (stale context, task done, clear sensitive data) and mentions pairing with siblings, but does not explicitly state when not to use or 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, openWorldHint=true, and destructiveHint=false. The description adds behavioral details: fetching the page, extracting title/description/key links, and outputting a single text blob. No contradictions.

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

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

The description is two sentences plus a bullet list of use cases, front-loaded with purpose and key details. Every sentence adds value with no wasted words.

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

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

Given the tool's simplicity (2 params, no output schema), annotations cover safety and idempotency. The description fully explains the process and output format, and provides use cases. No gaps.

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

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

Schema coverage is 100% with parameter descriptions for url and max_links. The description does not add additional meaning beyond what the schema provides, so it meets 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 generates a production-ready llms.txt file for any URL, fetching page content and emitting standard markdown. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on llms.txt generation rather than scanning.

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 provides three use cases (client site indexing, own project drafting, competitor auditing), giving clear context for when to use. However, it does not mention when not to use or provide 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 indicate read-only, idempotent, non-destructive. Description adds default behavior (active only) and return fields. With annotations, this is adequate but not exceptional.

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

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

Two sentences, front-loaded with purpose, no fluff. Every sentence earns its place.

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

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

For a simple list tool with one parameter, the description covers purpose, usage, and returned fields. No output schema, but return fields are listed. Could mention pagination, but not necessary.

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

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

Schema coverage is 100%. The description does not add extra parameter info beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states it lists the caller's active subscriptions and mentions returned fields. Distinguishes from siblings like subscribe/unsubscribe, but no explicit sibling differentiation.

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

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

Provides explicit use cases: reviewing subscriptions before adding more or finding an id to cancel. Does not include when-not-to-use or alternatives, but gives clear context.

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

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

Annotations are all false so the description carries the transparency burden. It discloses rate limits ('5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), anonymous token flow ('Filing without an account returns a claim_token'), and status-read semantics. This goes beyond the structured annotations.

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

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

Though ~170 words, every sentence adds either an eligibility rule, behavior, or constraint; it's front-loaded with the core purpose and ends with quota/rate facts. No filler or repetition of schema.

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 purpose, selection criteria, exclusions, return behavior, rate limits, roadmap impact, and quota impact. With four optional params and no output schema, this is more than enough to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaningful semantics for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and ties type enum to real-world cases. It doesn't redundantly restate schema fields, so 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' naming the action and resource. It then enumerates specific feedback categories (bug, feature/data_gap, praise), clearly distinguishing this from sibling tools like ask_pipeworx or discover_tools.

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

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

It gives explicit when-to-use guidance ('Use when a tool returns wrong/stale data...') and an explicit exclusion ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). This is textbook usage guidance with alternatives.

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

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

Annotations already declare safe, read-only behavior. The description adds valuable context: no PII, derived from analytics engine, caching duration (5min-1h). This 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?

The description is concise, well-structured with two paragraphs: first explaining output and window, second listing use cases and additional info. Every sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool returns, caching, and data source. No gaps.

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

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

Schema coverage is 100% with full enum and description for the single parameter. The description adds nuance about shorter vs longer windows, which helps agent choose based on goal.

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. It uses specific verbs and resources, and distinguishes itself from sibling tools by focusing on trending data sources.

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

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

The description provides three explicit use cases (discovering hot sources, confirming canonical choice, aligning use case). It also explains the purpose of different window lengths. No explicit 'when not to use' is stated, but the context is clear.

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

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

Annotations already mark it as read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: partition filter with placeholder fraction, semantic anchor with Jaccard similarity, fill check against CLOB depth, and response structure. No contradictions.

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

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

The description is thorough but somewhat verbose. It is well-structured with clear sections for each mode and additional technical notes (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, but it could be slightly more concise.

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

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

Given no output schema, the description summarizes the response format (opportunities[], partition_check) and explains edge cases (fill check, placeholder filters). It also references a sibling tool (polymarket_fill_risk) for custom sizing. Very 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%. Description adds significant meaning beyond the schema: explains that 'event' accepts slugs or URLs, 'topic' searches related events, and provides examples. Also clarifies the behavior of each mode in detail.

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

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

Description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (trending_scan, event, topic) with specific examples and use cases, making the purpose unmistakable.

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

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

Provides explicit guidance on when to use each parameter: 'no args for trending scan', 'event for specific market', 'topic for cross-event scanning'. Also explains why cross-event mode is better for certain patterns. Implicitly tells when not to use 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 mark it as read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral context: how edges are computed (three model families), caching behavior, diagnostics for empty segments, and details on slippage, Kelly fractions, and 24h-move warnings.

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?

Description is quite lengthy but well-structured, front-loading the purpose and then detailing technical aspects. Every sentence adds value, but the density could be reduced slightly for better readability.

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

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

Given the tool's complexity (9 parameters, three response segments, no output schema), the description is exceptionally complete. It details each segment's logic, the diagnostic fields, caching strategy, and edge-case handling (e.g., Fed markets).

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 all 9 parameters with descriptions. The tool description adds significant extra context for several parameters (e.g., slippage_pp explaining Polymarket fee structure, min_partition_leg_kelly explaining its interaction with partition arbs).

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

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

Description clearly states the tool scans Polymarket markets to surface opportunities where Pipeworx data diverges from market price. It specifies the three response segments and distinguishes itself from sibling tools by focusing on edge discovery without paging hundreds of markets.

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 framed for 'what should I bet on today' use cases, highlighting that agents can discover opportunities efficiently. However, it does not explicitly mention alternatives or when not to use this tool in favor of siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 detail beyond annotations: it explains data sources (daily polymarket_edges snapshots, 60-day TTL), response structure (tracked, expired, snapshot_dates), and limitations (history depth, decay from daily closes). Annotations already indicate readOnly and idempotent, so the description focuses on operational 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 front-loaded with the key question and then details the response. It is well-organized but somewhat verbose. Every sentence adds value, but could be tightened slightly. Overall, it effectively communicates without being overly brief.

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

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

Despite no output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates with fields). It covers all necessary information for an agent to understand what the tool returns and how to interpret results, given the moderate 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%, but the description adds default values (14 days, '1wk'), clamp range (2-30), and explains the meaning of 'window' as snapshot family. This goes beyond the schema's brief description, providing practical usage context. Without these, the agent might misinterpret the parameters.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?'. It distinguishes from a tool like polymarket_edges by emphasizing historical behavior rather than current edges. The specific contrast between fresh and old wide edges clarifies the unique value proposition.

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

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

The description implies usage when needing historical edge decay analysis, but does not explicitly state when to avoid using it (e.g., when current edges only are needed). The context of sibling tools like polymarket_edges suggests alternative, but no direct guidance is given. The examples of trade differences provide implicit context.

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

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

Annotations already declare non-destructive, read-only, and idempotent behavior. The description adds crucial behavioral context: it walks the ladder, returns verdicts (clean|degraded|cannot_fill), explains forced directional risk, and mentions that partial basket fills create unhedged positions—the dominant loss mode. 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 somewhat lengthy (~150 words) but well-structured: it starts with the core purpose, then details each mode, and ends with usage guidance. While dense, every sentence contributes meaning; minor verbosity prevents a perfect 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?

Given the tool's complexity (two modes, multiple return fields, no output schema), the description comprehensively covers inputs, outputs (top_of_book, vwap_fill_price, slippage_pp, verdicts, per-leg details, etc.), risks, and contextual warnings. It is fully adequate for agent selection and invocation.

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

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

Schema coverage is 100% with all parameters described. The description adds value by clarifying defaults (size_usd default 1000, clamp 10–1,000,000), explaining side auto-detection in basket mode, and distinguishing market vs event modes 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from siblings like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on those signals.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about the risk of partial fills converting an arb into an unhedged directional position, giving clear when-not-to-skip usage.

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

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

Despite readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already covering the safety profile, the description adds substantial behavioral disclosure: compatibility warnings can be non-empty even with matched pairs, unknown legs are never paired, temporal_alignment null means unknown rather than aligned, fees are gross and not modeled, and skipped comparison counters are explained. No contradiction with annotations.

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

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

The description is dense but well organized: purpose, modes, response, safety fields, and skipped-count semantics are clearly labeled and front-loaded. It is long, and the prose is heavy in places, but almost every sentence carries a distinct operational caveat or rule, so the length is mostly 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?

With no output schema, the description carries the burden of documenting return semantics, and it does so comprehensively: top_spreads_pp, per-entry flags[], temporal_alignment, fees_note, low_confidence_pairs, and skipped counters are all explained. The main gap is that it never states what happens if no parameters are supplied, even though the schema marks all parameters as optional.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds meaningful semantic value by defining the two mutually exclusive call modes, listing the ten topic shortcuts, and clarifying that explicit ticker/slug override the topic-mapped side while both modes run the same matcher. It does not add new syntax or format details, but it meaningfully disambiguates how the parameters interact.

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 by stating exactly what the tool computes: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It further distinguishes itself by defining the two access modes and noting that the tool detects when bet shapes are not equivalent, so an agent can tell this apart from other Polymarket or Kalshi tools.

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

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

It gives clear context for when to use each mode, including the pre-mapped topic shortcuts and the explicit ticker/slug pairing, and warns that pre-mapped topics are often not tradeable. It does not explicitly name alternative sibling tools or state when NOT to use this tool in favor of one of them, so it stops short of a full exclusion list.

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

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

Beyond annotations (readOnly, not destructive), description adds scoping info (anonymous IP, BYO key hash, account ID) and pairing with remember/forget. No contradiction.

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

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

Three concise sentences, front-loaded with the main action. Each sentence adds value: what it does, usage examples, scoping, and tool relationships. No waste.

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?

Fully adequate for a simple retrieval tool: explains input, behavior, scoping, and how it fits with siblings. No output schema needed; return is implied.

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?

One parameter (key) with 100% schema coverage. Description adds the important behavior that omitting key lists all saved keys, reinforcing and extending the schema's description.

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

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

Clearly states the tool retrieves a value by key or lists all keys when omitted. Mentions the associated tools (remember, forget) and gives concrete examples, distinguishing it from siblings.

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

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

Describes when to use: to look up previously stored context without re-deriving it. Provides examples and pairing guidance. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations declare readOnlyHint=true, but the description describes a mutation (mark_read:true flags events as read, changing state). This contradiction lowers transparency. Additionally, there is no disclosure of other potential side effects or authorization requirements.

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 purpose and covers key points in a few sentences. It is concise but could be slightly more structured; however, every sentence adds value without redundancy.

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

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

The tool has 5 parameters and no output schema. The description explains the return format and the use of mark_read, but fails to mention the unread_only parameter. Schema covers it, but the description is incomplete in covering all parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving an example for type ('sec_8k') and clarifying the behavior of mark_read, which enhances meaning beyond the raw 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 'Pull fired events from your subscription feed' with specific verb and resource. It explains the returned data (source, citation_uri, raw payload) and distinguishes this tool from siblings like list_subscriptions and subscribe by focusing on alert retrieval.

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

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

The description provides clear context on usage, including filtering by type and ISO timestamp, and the mark_read option. It also mentions an alternative direct HTTP endpoint for scripts/dashboards, but does not explicitly state when not to use this tool versus siblings.

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

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

Beyond annotations (readOnly, idempotent, etc.), description discloses multiple behaviors: fan-out to three sources, fallback mechanism, soft-failure for patents, return structure with citations, and accepted date formats.

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?

Front-loaded with natural language examples; every sentence adds value. Slightly dense but appropriate for the 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?

No output schema, but description fully explains return structure (grouped changes, counts, citations). Covers edge cases and fallbacks, making it complete.

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

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

Schema coverage is 100%, but description adds meaning: explains relative shorthand for 'since', accepts ticker or CIK for 'value', and clarifies 'type' only supports 'company'.

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 specific verbs ('change feed', 'fans out') and clearly identifies the resource (company changes in time window). It explicitly distinguishes from the sibling tool 'entity_profile' for static profiles.

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 query examples and when to use alternatives ('Use entity_profile instead when you want the static profile'). Also describes fallback logic between GDELT and GNews.

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 idempotentHint true and destructiveHint false, but the description adds valuable context: storage is key-value scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. This goes beyond annotations without contradiction.

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

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

The description is concise (four sentences) and front-loaded with the core purpose. Every sentence adds value—purpose, usage guidance, persistence details, and sibling references—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 simple tool with two parameters and no output schema, the description is complete. It explains when to use, what is stored, scope, persistence behavior, and associated tools, leaving no critical gaps.

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

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

Schema coverage is 100% with clear descriptions for both 'key' and 'value' parameters. The description reinforces key-value pairs with examples but does not add new syntax or constraints beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides concrete examples (resolved ticker, target address, user preference) and distinguishes from sibling tools like recall and forget, making its role unambiguous.

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

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

The description explicitly advises when to use: 'when you discover something worth carrying forward'. It also mentions pairing with recall and forget, providing clear usage context. It does not explicitly list when not to use, but the guidance is sufficient.

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

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

Annotations already mark it read-only/idempotent, but the description adds substantial behavioral detail: graceful degradation when LEI/FIGI sources fail, ambiguous matches returning figi_candidates instead of asserting, unresolved identifiers being explicitly listed, and internal cascading through multiple endpoints. This goes well beyond the annotations.

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

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

The description is long but densely informative, front-loaded with user intents and organized by SUPPORTED TYPES. Each parenthetical adds operational value, though the wall of text could be broken up for easier scanning.

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 burden of explaining return behavior, and it does: it names returned fields (CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand), the ambiguous case (figi_candidates), unresolved identifiers, and source attribution. For a complex resolution tool, this 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 covers the parameters, but the description adds crucial semantics: 'Pass the ENTITY NAME ONLY,' the distinction between ticker/CIK/name for companies, and the warning that trailing security-class words break FIGI matching. This meaningfully clarifies how to construct the value beyond the schema's bare examples.

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

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

States a precise verb+resource: resolves user-spoken names to canonical/official identifiers needed by other tools. It names concrete use cases ('find the CIK for...', 'who owns X') and supported entity types, clearly distinguishing it from siblings like compare_entities and entity_profile.

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

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

Gives an explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' It also lists common query phrasings that should trigger this tool. It does not explicitly name sibling alternatives or say when NOT to use it, 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?

The description adds significant behavioral details beyond the annotations: it explains the process (probing each entity with ai_visibility_check, ranking), and specifically that the first entity is treated as the 'subject' for narrative. It also reveals output fields (score, confidence, signal density). The annotations (readOnlyHint, idempotentHint) are consistent, and the description enriches understanding of the tool's 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?

At four sentences, the description is concise and well-structured. The first sentence states the primary purpose, the second details the process, the third provides a practical use case, and the fourth describes the output. No sentences are wasted, and key information is front-loaded.

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

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

Given the tool's moderate complexity (4 parameters, comparison logic) and the absence of an output schema, the description is complete. It explains the input semantics, the processing logic, and the output structure (ranked list with score, confidence, signal density). The comprehensive annotations further cover safety and idempotency, leaving no major gaps.

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

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

The input schema already has full description coverage (100%) for all 4 parameters. The description adds value by explaining that entities should be 'your brand + N competitors' and that the first entity is treated as the subject. It also contextualizes the purpose of models and context, going beyond the schema's literal descriptions.

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

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

The description clearly states the tool's core function: 'Compare AI visibility across multiple entities side-by-side.' It specifies that it probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. This distinguishes it from the sibling tool ai_visibility_check (single entity check) and other compare tools by focusing on 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 provides a concrete use case: 'useful for competitive AI-marketing audits' with an example question. It implies this tool is for comparing multiple entities, implicitly differentiating from single-entity checks. However, it does not explicitly state when not to use it or list alternatives, missing the highest standard.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), description discloses fan-out behavior across two services, potential timeout for bundlephobia, graceful partial failure, and the return structure (summary block, per-advisory detail, links, alternative versions). No contradictions with annotations.

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

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

Description is dense with useful information, using parentheses and lists effectively. While slightly long, every sentence adds value and it is front-loaded with the primary purpose. Could be streamlined but remains clear.

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

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

Given no output schema, description thoroughly explains return structure (fields like is_latest, license, bundle_kb_gz, etc.), partial failure handling, and data sources. Provides sufficient context for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100% with both parameters described. Description adds contextual meaning: 'package' is an npm package name (scoped accepted), 'version' defaults to latest. It also connects parameters to the overall check purpose, adding value beyond schema alone.

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

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

Description clearly states the tool's purpose as a composite check for adding an npm package, listing specific checks (license, advisories, bundle size) and data sources (deps.dev, bundlephobia). Distinguishes from siblings by explicitly noting NPM-only scope in v1 and referencing alternative tools for other ecosystems.

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 (agent asks about safety, popularity, size, cost) and when not to (PyPI, Maven, etc. fall under deps.dev:version directly). Also notes that bundlephobia first measurement may take 5-30s and that failures degrade gracefully.

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

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

Beyond annotations (which all indicate safe, non-destructive, idempotent behavior), the description reveals technical details: embedding model (BGE-base-en), similarity measure (cosine), windowing (500-char overlapping windows), and a hard cap (200K chars with truncation and flagging). Also mentions character offsets for quote verification. This adds significant behavioral context that annotations alone don't cover.

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

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

Every sentence serves a purpose: first sentence states functionality, second provides usage context and benefit, third gives pairing advice, fourth details technical implementation and limits. Front-loaded with purpose, then usage, then technical details. No filler or redundancy.

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

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

Given no output schema, the description explains return values (top-N passages with character offsets and similarity scores). It addresses the main use case (large documents), technical constraints (200K char cap, truncation), and integration with sibling tools (ask_pipeworx_grounded). Annotations provide safety guarantees. The description is complete enough for an agent to understand when and how to use 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?

Schema coverage is 100% (all three parameters described with basic purpose). The description adds value by clarifying that 'text' is the document to search, 'query' is a natural-language query with examples, and 'limit' controls max passages. It also explains the max char limit and truncation behavior, which is not in the schema. However, the schema already provides adequate descriptions, so the incremental value is somewhat limited.

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 ('Semantic search INSIDE a fetched record') and resource (a fetched record) and immediately distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded. It gives concrete examples (e.g., SEC 10-K, article, long tool result). This leaves no ambiguity about what the tool does and how it differs from other search tools.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt') and suggests an alternative workflow ('Pairs with ask_pipeworx_grounded'). Also explains the benefit ('saves context, returns only the passages that matter'). Provides clear context for selecting this tool over alternatives.

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

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

The description adds behavioral context beyond annotations, such as requiring OAuth, phone verification, SMS cap, webhook auto-disable, and return of subscription ID. It aligns with idempotentHint=true but does not explicitly state idempotency behavior. No contradiction with annotations.

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

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

The description is well-structured with a clear first sentence defining purpose, followed by details on types and delivery. It is somewhat verbose but each sentence provides value. Front-loading of purpose is good.

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

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

For a tool with 3 parameters, nested objects, and no output schema, the description covers essential aspects: required parameters, type-specific params, delivery channels (including webhook signing secret), auth requirements, and caveats. Missing explicit error handling, but overall complete enough.

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

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

Schema coverage is 100%, but the description adds substantial meaning with examples for each subscription type, detailed delivery channel requirements, and constraints. It explains enum options, nested objects, and dependencies (e.g., sponsor or condition required for clinical_trial).

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and always-on feed + optional delivery channels.

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

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

The description provides clear context on when to use the tool (creating subscriptions) and includes prerequisites (Pipeworx OAuth account, phone verification for SMS). It does not explicitly list alternatives or when-not-to-use, but the specificity of the description guides the agent well.

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

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

The description adds significant behavioral context beyond the annotations: it explains the tool returns category-bucketed example questions, drawn from the live catalog, and that passing a topic focuses the results. It is consistent with the readOnlyHint and openWorldHint 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 slightly verbose with multiple alternative phrasings at the beginning ('What can I ask Pipeworx? / what is Pipeworx good for? ...'), but it remains well-structured and front-loaded with the essential 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 simple input schema (one optional param, no output schema) and the rich annotations, the description is complete. It covers what the tool returns, how to use it, and when to use it, leaving no ambiguity.

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

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

The single optional parameter (topic) has full schema coverage. The description adds meaning by listing example values (finance, pharma, etc.) and specifying that omitting it gives a cross-category spread, which complements the schema's description.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. The title and description explicitly differentiate it from sibling tools like discover_tools or ask_pipeworx.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to call (no arguments or with topic) and provides a list of topic options.

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 value beyond annotations: it explains that the row is 'deactivated (not deleted)' and that 'historical events stay available via recent_alerts.' This aligns with the idempotentHint (true) and destructiveHint (false) annotations.

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

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

Two concise sentences front-loaded with the main action. No superfluous words; every sentence provides essential information.

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

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

Given the tool's simplicity (1 required param, no output schema), the description adequately covers the effect, ownership rule, and lifecycle implications. No missing 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 the id parameter described. The description adds context that ownership is enforced, implying the id must belong to the user, enhancing understanding of the parameter's constraints.

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

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

The description clearly states 'Cancel a subscription by id.' specifying the action (cancel) and resource (subscription). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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 mentions 'Ownership is enforced — you can only cancel your own subscriptions,' which clarifies when to use the tool. It doesn't explicitly state alternative scenarios or when not to use, but for a simple tool the guidance is adequate.

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

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

The description goes well beyond the annotations by disclosing the internal routing (SEC EDGAR/XBRL fast path vs. grounded pipeline), the return verdicts, and critically the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found). This prevents misinterpreting a failed check as evidence, which is essential behavioral context.

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

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

The description is dense but well-organized, leading with trigger phrases, then use case, then pipeline details, then return values and caveats. Every sentence carries meaning, though the long sentences with viele dashes might be slightly harder to parse. Still, it earns high marks for efficiency.

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

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

Given there is no output schema, the description thoroughly explains the return values (verdicts, actual value, reasoning) and clarifies ambiguous outcomes. It covers the major execution paths and the important 'could_not_verify' pitfall. This is complete for a tool of this complexity.

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

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

The input schema already fully documents both parameters (claim and tolerance_pct) with clear descriptions and defaults. The tool description adds no additional parameter-level information, so the baseline of 3 applies. It does mention 'exact percent-delta math' but that is about internal computation, not 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 clearly identifies the tool as natural-language claim verification, with specific trigger phrases like 'fact check' and 'verify the claim'. It distinguishes itself from sibling tools by focusing on factual claims against authoritative sources, and even breaks down the two processing paths (SEC EDGAR fast path vs. grounded pipeline).

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the automatic routing for financial vs. other claims. This gives clear when-to-use context, though it doesn't mention specific exclusions or alternatives, the scope is comprehensive and unambiguous.

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