Statfin Fi

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds meaningful behavioral context: the default model (Workers AI free), the ability to probe Anthropic with a BYO key, and direct cost implications. This goes beyond annotations and enriches the agent's understanding of side effects and 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 concise and well-structured: a front-loaded purpose sentence, a second sentence covering defaults and key handling, and a final sentence listing use cases. Each sentence earns its place with no redundancy. It is appropriately sized for the tool's complexity.

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

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

The tool has no output schema, so the description compensates by explicitly stating the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view.' Combined with the purpose and use cases, this gives a complete picture for an agent to decide invocation and interpret results. Minor gaps like scoring methodology are acceptable for 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?

With 100% schema coverage, the baseline is 3. The description adds value by explaining the default model behavior and clarifying that `_apiKey` is only needed for Anthropic, including the cost note (BYO key). This gives the agent practical knowledge about parameters that the schema alone does not fully convey.

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

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

The description opens with a specific verb ('Probe') and clearly identifies the resource (LLMs) and the outcome (visibility score 0-100 per model). It also sets expectations about the default model and combined view, making the tool's purpose unambiguous and distinct from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to invoke the tool, though it does not mention alternatives or conditions for not using it. This aligns with 'clear context, no exclusions' at level 4.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavior context beyond that: it routes to one of 5,635 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. Consistent with annotations and value-adding.

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?

Longer than average, but front-loaded with the highest-priority directive ('PREFER OVER WEB SEARCH') and dense with value: scope, trigger phrases, examples, routing guidance, and sibling conditions. Every sentence earns its place; only minor redundancy in the enumerated domain list keeps it from a 5.

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

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

Complete for a general-purpose router tool with no output schema. It explains the return format (structured answer with citation URIs), why to choose it over web search, when to escalate to siblings, and the breadth of domains. 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 coverage is 100% and the schema clearly documents the single natural-language 'question' parameter plus five aliases. The description does not add parameter-specific syntax beyond the schema, but it does supply representative question examples that illustrate expected input. Baseline 3 is appropriate since the schema carries the 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?

States a clear verb+resource: routes a natural-language question to verified data sources and returns a structured, cited answer. It explicitly names what it is not (ask_pipeworx_grounded, deep_research) and enumerates the domains it covers, so an agent can distinguish it from siblings without opening 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?

Exceptionally explicit: 'PREFER OVER WEB SEARCH', 'START HERE for most questions — this is the default entry point', plus a precise step-up rule ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). Lists trigger phrases and concrete examples. Nothing is left to inference.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context beyond these: it is an experimental edge, may have candidate routing improvements that change behavior, currently matches the stable router, and is a full working router (not a fallback). This discloses the dynamic nature and current state, which is crucial for an agent to know before using it.

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

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

The description is well-structured and front-loaded: it identifies the tool as beta, explains its identity, states the current status, gives usage guidance, and clarifies it's fully functional. Each sentence contributes necessary context without repetition or fluff. The length is justified given the complexity of the tool.

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

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

Given the tool's complexity (a universal router with 5,635 tools), the description is quite thorough: it covers purpose, current state, usage, and behavior. It does not describe the return format, but it states the response shape is identical to ask_pipeworx, which could be sufficient if the agent knows that sibling. Since there is no output schema, a brief note on expected return could improve completeness, but the description still provides a strong framework.

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%—all parameters (including aliases) are described as aliases for 'question', and the primary parameter description is clear. The tool description adds no additional semantic meaning about parameters beyond the schema, so it relies on the schema. This meets the baseline for full coverage but doesn't exceed it.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental routing improvements, and explicitly notes the current status of no active candidate. This gives a specific verb (ask), resource (pipeworx), and scope (beta routing), making it easy to identify.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This provides clear when-to-use context, and the mention that it currently matches ask_pipeworx exactly clarifies the alternative. Though it doesn't list many alternatives, the primary choice (ask_pipeworx) is addressed, and the usage condition is unambiguous.

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

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

The description discloses behavior well beyond the annotations. It explains that the tool will refuse to answer if the data doesn't directly answer, listing explicit refusal reasons ('not_in_source', 'no_tool_match', etc.). It also describes the exact success and failure return shapes, including the 'evidence' field as a verbatim quote. It mentions the extra LLM call cost and the guarantee of using only tool-result content. This is rich behavioral context that annotations (readOnlyHint, etc.) do not provide.

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

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

The description is front-loaded with the key differentiator ('Hallucination-resistant answer mode') and then covers routing, return structure, usage context, and cost trade-off. Every sentence serves a purpose, and there is no fluff. Despite being dense, it remains readable and well-structured.

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

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

Given the tool's complexity (routing across 5,635 tools) and the lack of an output schema, the description is remarkably complete. It explains both success and failure response shapes, all refusal reasons, the source and evidence fields, and when to use the tool. It even mentions the cost implication and gives a concrete alternative. No essential information is missing for an agent to call this tool correctly.

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

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

The input schema already documents all parameters with 100% coverage (question and its aliases). The description does not add any parameter-specific guidance beyond what the schema provides. Since the schema is complete, the description's lack of parameter details is acceptable. Baseline 3 applies because the description adds no extra semantic value for parameters.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode' that extracts answers only from tool results. It distinguishes itself from ask_pipeworx by mentioning 'Same routing as ask_pipeworx' but adding the grounded extraction step. The return format and refusal reasons are explicitly listed, leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups' and notes the cost difference ('Costs one extra LLM call vs ask_pipeworx'). This is exactly the kind of when/when-not guidance we want.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses extensive behavioral traits: classifier categories, fan-out examples, resolver contract (market_match_confidence, alternatives, suggestions), parent-event extraction, news fallback fields, safety short-circuits (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and resolution-rule risk (refund_50_50, etc.). This adds significant value beyond the safety profile.

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

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

Although long, the description is exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Each section earns its place with operational detail, and the first sentence immediately states purpose. This is not verbosity but dense, organized 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?

With no output schema, the description carries full responsibility for return values and does so thoroughly: result.market fields, result.analysis (model_probability, edge_pp, kelly_fraction_half, 24h warning), result.evidence, resolver contract, parent_event, news fields, and all error/edge-case statuses. It also covers safety and rules risk, making the description complete for an agent to invoke and interpret.

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

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

The schema already provides comprehensive descriptions for all three parameters (100% coverage). The description reinforces the market parameter's flexible input forms and hints at depth's effect via fan-out examples, but it does not add substantial new meaning beyond what the schema includes. Baseline for high coverage is 3; some contextual examples are provided but not transformative.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text), the process (resolves, classifies, fans out in parallel), and the output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage which focus on edge/arbitrage separately.

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 usage cues: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context. However, it does not explicitly name alternative tools or state when not to use it, so it lacks exclusions or alternative references.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: parallel execution, data source specifics (SEC EDGAR/XBRL, FAERS, FDA counts), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This substantially exceeds baseline expectations.

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

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

Despite being longer than many descriptions, every sentence contributes value: trigger examples, preference rule, type-specific data details, sorting behavior, and return format. The structure is front-loaded with the core action and usage guidance, making it easy to scan.

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

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

Given no output schema, the description adequately explains return contents ('paired data + pipeworx:// citation URIs'), sorting behavior, and coverage limits (2–5 entities). It also contextualizes the tool's efficiency gain ('Replaces 8–15 sequential lookups'), making it complete for the tool's complexity.

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

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

The schema already covers both parameters fully with descriptions and enums. The description adds semantic meaning by explaining what each type ('company' vs 'drug') retrieves (10-K financials vs. adverse-event/FDA/trial counts) and how 'values' map to tickers or drug names, enriching the schema without redundancy.

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

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

The description explicitly states the action ('side-by-side comparison of 2–5 companies or drugs in ONE parallel call') and clearly distinguishes the tool from sequential single-pack lookups. It also enumerates the entity types (company/drug) and the data sources, making its purpose unmistakable.

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

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

The description provides explicit trigger phrases ('Compare X and Y', 'which is bigger', 'rank these companies'), an unconditional preference directive ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'), and per-type usage semantics. This is strong guidance on when to use the tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial context beyond that: expected latencies (15-90s), the gaps[] never-invent behavior, hop field and citation_uri always-fetchable guarantee, large-record semantic excerpting, and contradictions[] for standard/thorough. No contradiction — openWorldHint=true aligns with querying live structured sources that change over time.

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 the account requirement, then purpose, then alternatives, then behavioral detail. It is long (~350 words), but for a genuinely complex parallel-routing tool every section earns its place; the only redundancy is depth semantics repeated against the schema. Appropriate length 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?

For a 2-parameter tool with no output schema, this is as complete as it gets: success behavior (findings packet with verbatim evidence + confidence + source + fetched_at + citation), failure behavior (gaps[]), iteration semantics, alerting on contradictions, excerpting behavior, timing, and auth requirements. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% (both question and depth well-documented), establishing a baseline of 3. The description adds value beyond the schema by conveying the practical consequence of each depth level — gap-recovery hop, lead-chasing, contradiction scan, and the time implications — which the schema's enum text only partially conveys. Minor redundancy since depth detail appears in both places.

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

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

States a specific capability — grounded multi-source research across 1,477 structured data sources via parallel decomposition — and explicitly distinguishes itself ('this is NOT open-web search'). The verb+resource+scope is unambiguous and it clearly separates itself from the ask_pipeworx siblings without opening their 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?

Exceptionally explicit: names ask_pipeworx as the alternative for single lookups and breaking/current-news, flags the account/paid-tier requirement with a fallback instruction, and details when each depth level is appropriate (standard vs thorough hop behavior). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavior: it returns top-N tools with full schemas and examples, ready to call directly with no second lookup. This explains output format and usability 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 relatively long but every part serves a purpose: purpose, domain list, return behavior, and usage guidance. The opening sentence is direct, and the domain list is compact. No filler or redundancy, though it could be slightly shorter without losing value.

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

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

No output schema exists, but the description explains the return value (top-N relevant tools with names, descriptions, schemas, examples) and that results are directly callable. It covers the main use case and return format adequately for a read-only discovery tool. Minor gaps like error handling or pagination not addressed, but not critical.

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

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

Schema description coverage is 100%, with aliases and defaults documented. The description mentions 'top-N' (matching limit) and 'describing the data or task' (matching query), but adds no detail beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 with a specific verb ('Find tools') and resource ('by describing the data or task'). It also lists comprehensive domains and distinguishes itself from siblings by stating 'Call this FIRST' and returning the option set, making it unique among sibling 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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and even hints at excluding cases where a specific tool is already known.

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

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

Annotations already declare read-only and non-destructive, but the description adds substantial behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), describes soft-fail behavior for the PatentsView API sunset, and explains fallback logic (GDELT→GNews). This goes well beyond the structured annotations.

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

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

The description is long but every sentence earns its place. It opens with concrete example queries, states the core action, gives usage precedence, lists return fields, notes API limitations, and closes with input formatting rules. The structure is efficient despite its length, with no filler.

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

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

Given there is no output schema, the description fully enumerates the return structure (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and explains the parallel fan-out behavior. It covers edge cases (patents API sunset) and fallbacks, making the tool's behavior predictable and complete for an agent.

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

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

Schema coverage for both parameters is 100%, so the baseline is 3. The description repeats the value parameter examples ('AAPL', '0000320193') already present in the schema and adds no new parameter-specific semantics beyond reinforcing the 'not names' constraint. It does not compensate beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example queries ('Tell me about X', 'research Acme') and distinguishes itself from siblings by explicitly instructing to prefer it over chaining single-pack lookups for holistic views.

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

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

Usage guidance is explicit: use when the user asks for a holistic company view, and prefer over chaining other lookups. It also tells when NOT to use it (names not supported) and directs to resolve_entity first if only a name is available. This clearly differentiates from alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the deletion behavior is covered. Description adds the 'clear sensitive data' use case but doesn't disclose additional behavioral traits beyond annotations. No contradiction.

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

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

Two sentences, front-loaded with the core definition, then usage context. No redundancy or filler.

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

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

For a single-parameter destructive tool with annotations covering safety and idempotency, the description provides sufficient context: what, when, and how it relates to sibling tools. No output schema needed for such a simple operation.

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

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

Input schema has 100% coverage with a clear description for 'key' parameter. Description adds no new parameter semantics beyond the schema's 'Memory key to delete'.

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 specific verb 'Delete' plus resource 'previously stored memory by key', clearly distinguishing from siblings like remember (store) and recall (retrieve).

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 context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with remember and recall, providing workflow context.

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

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

The description discloses the end-to-end process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds value beyond the annotations (readOnly, idempotent, openWorld) by explaining internal behavior and output format. 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?

The description is two sentences: the first states the core function, the second explains the process and provides three concrete use cases. Every sentence earns its place, with no redundant information.

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

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

Given the tool's simplicity (2 params, full schema coverage, no output schema) and rich annotations, the description provides sufficient context. It explains the output format ('single text blob', 'standard llms.txt markdown'), making it complete for an agent to select 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 description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, such as mentioning 'any URL' and the extraction of key links, but does not elaborate on max_links behavior. This matches the baseline for well-documented 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 generates a production-ready llms.txt file for any URL, with a specific verb ('generate') and resource ('llms.txt'). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility scanning rather than file generation.

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 'Useful for' section lists three concrete contexts (client indexing, personal project drafting, competitor auditing), which clearly implies when to use it. However, it does not explicitly mention alternatives or when not to use, so it falls short of the full 'when/when-not/alternatives' guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and emphasizing 'caller's' subscriptions, providing scoping 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?

Two concise sentences: the first states the action and returns, the second gives usage guidance. No filler or redundancy, every sentence earns its place.

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

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

For a simple list tool with one optional parameter, the description fully covers return fields, usage context, and relationship to sibling tools. The lack of an output schema is compensated by explicitly listing return fields, making the tool complete for agent 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 a single well-documented boolean parameter (include_inactive). The description's mention of 'active subscriptions' implicitly aligns with the default false, but it does not add new semantic details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description begins with a clear, specific verb+resource: 'List the caller's active subscriptions.' It also distinguishes from sibling tools by listing the exact return fields and noting the use case of finding an id to cancel, which differentiates it from subscribe/unsubscribe.

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

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

The description explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly references sibling tools (subscribe/unsubscribe) and provides 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?

With all annotations false, the description carries the full burden and excels. It discloses the rate limit (5 per identifier per day), that it is free and does not count against tool-call quota, and details the claim_token behavior (returned when filing without an account, usable later to check status). It also notes that the team reads digests daily—important for expectation-setting. 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 every sentence serves a distinct purpose: purpose, usage categories, exclusion clause, token flow, rate limit, and cost. It is front-loaded with the main action and progressively adds important context. It could be slightly tightened, but the structure is logical and free of fluff.

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

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

Given the tool's complexity (4 parameters, nested context object, no output schema, no annotations), the description covers all essential aspects: what it does, when to use it, what not to do, how the claim_token flow works, the daily limit, and cost. It even mentions the team's reading cadence. This is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage for all parameters with descriptive text, so the baseline is 3. The description adds value by explaining the claim_token parameter usage in context ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by giving guidance for the message parameter ('don't paste the end-user's prompt'). This elevates it above baseline, though not all parameters need extra 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?

The description begins with a clear, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This uses a concrete verb and resource, and explicitly distinguishes the tool's feedback purpose from sibling tools like ask_pipeworx or discover_tools. It also clarifies the scope (only for Pipeworx tools), making it unambiguous.

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

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

The description provides explicit when-to-use guidance for each feedback category: bug, feature/data_gap, and praise. It also gives a direct exclusion: if the tool came from a different MCP server, file it there instead. Additionally, it explains the claim_token follow-up workflow, far exceeding basic guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds transparency about data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h depending on window'), which go beyond the annotation hints.

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

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

The description is compact and well-structured: a lead summary, a bullet-style 'Useful for' list, then a technical note. 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?

Without an output schema, the description compensates by listing return items (top tools, top packs, total call volume) and even the tuple format '(pack, tool, count)'. Combined with annotations and low parameter complexity, it is 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 sole parameter 'window' is fully described in the schema with enum values and semantics. The tool description mentions the windows but does not add new meaning, so baseline 3 applies.

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

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

The description clearly states the tool returns trending call statistics ('What other AI agents are calling on Pipeworx right now') and specifies output contents (top tools, top packs, total call volume). It distinguishes itself from siblings by focusing on aggregate usage signal rather than tool discovery.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent demand. It does not mention exclusions or alternative tools, so it lacks the full 5 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?

Beyond the readOnlyHint and destructiveHint annotations, the description reveals substantial non-obvious behavior: fill-check pricing against live CLOB depth, the condition 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book', threshold details (>3pp deviations), placeholder filtering, and the semantic anchor with Jaccard similarity. This goes far beyond what annotations provide.

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

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

The description is long but every sentence earns its place, organized with labels ('SEMANTIC ANCHOR', 'PARTITION FILTER', 'FILL CHECK') that make it easy to scan. It front-loads the core purpose, then systematically details modes and edge cases without redundancy.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It outlines the response shape (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity violation context), describes partition_check fields, covers failure modes (null arb signal), and explains the fill-check decision rule. No important aspect is left unexplained.

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

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

While the schema already has 100% coverage with descriptions for both `event` and `topic`, the tool description adds meaningful depth: concrete slug examples, clarification that full URLs are accepted, and a detailed explanation of how each mode behaves. This is a clear enhancement over 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (default trending scan, event-specific, topic cross-event), making it easy to understand what the tool does and how it differs 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?

Explicit guidance is given for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also points to an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This fully satisfies the when-to-use and alternatives criteria.

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

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

Annotations only state readOnly, openWorld, idempotent, and non-destructive; the description goes far beyond by detailing internal model families, response segments, caching behavior ('Cached 1h at the KV level'), diagnostic funnel counters, and caveats like 'your edge may already be in the price.' It also explains why Fed bets are excluded and the unreliability of the 1m-T vs EFFR signal, offering rich behavioral context not captured in annotations.

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

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

The description is heavily front-loaded with the purpose in the first sentence and uses capitalization to organize segments and knobs. Every sentence carries technical value, but the sheer length and density may overwhelm an agent trying to quickly parse the tool. It is well-structured but not concise, earning a 4 rather than a 5.

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

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

With 9 parameters, no output schema, and no nested objects, the description carries the full burden of explaining the response. It does so comprehensively: top-level response layout (by_segment, fed_candidates/fed_note, _diagnostics), what each segment contains, why segments might be empty, and caching behavior. It 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?

Although schema description coverage is 100%, the description adds substantial semantic depth. It explains how min_liquidity/max_spread_pp affect tradeability, clarifies that min_kelly applies only to single-leg opportunities, and details the unusual per-leg Kelly behavior for partition arbs. This goes well beyond the schema's field descriptions, genuinely helping the agent choose and set parameters correctly.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the intended use case ('what should I bet on today') and differentiates from alternatives by noting it avoids paging hundreds of markets. The three segments and their model families further clarify the tool's scope.

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

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

The description gives strong context for when to use the tool (discovering betting opportunities, scanning top markets) and operational guidance via knob explanations (e.g., 'Set to 2 to require tight books'). However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it state when not to use it. This is clear context without exclusions, so a 4 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 declare read-only/idempotent, and the description adds substantial behavioral detail: snapshot TTL limits, cache-miss gap semantics, daily-close vs intraday data, response structure, and signed edge_pp_net meaning. It also explains the response fields in detail, going far beyond the structured hints.

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

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

Long but dense: each section (Args, RESPONSE, LIMITS) is clearly labeled and every sentence contributes a distinct fact. The format is front-loaded with the core question, and the structure makes the length 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?

With no output schema, the description carries the full burden of explaining return values, and it does: tracked[], expired[], snapshot_dates[] with field-level details. It also covers limits and data gaps, making the tool self-contained.

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

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

Both params are already fully described in the schema (coverage 100%), and the description adds the 'lookback' concept and 'snapshot family' context, reinforcing defaults. This adds value beyond the schema by linking params to the tool's temporal design.

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?

Opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' — a specific verb+resource scope. It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling polymarket_edges (current edges) by emphasizing temporal analysis.

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

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

The description frames the tool around a specific decision (fresh wide edge vs. 3-week-old wide edge) and explains the purpose. It does not explicitly name alternative tools for exclusion, but the context is clear enough to infer when this tracker is needed.

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 goes beyond these by disclosing behavior such as 'walks the ladder', the returned fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and the risk of 'forced_directional_risk' and 'thin_legs'. It also warns that 'partial basket fills convert an arb into an unhedged directional position'—a crucial behavioral consequence not captured by the annotations.

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

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

The description is long but well-structured, using explicit SINGLE-MARKET and BASKET sections and front-loading the core purpose in the first sentence. Every sentence provides substantive information—parameters, outputs, or risk warnings—so it earns its place, though it could be slightly tightened without losing value.

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

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

The tool has two distinct modes, no output schema, and four parameters; the description covers all of these comprehensively. It explains return values for both modes, the meaning of the verdict, the interpretation of size_usd, and links to sibling tools with clear usage context. Given the complexity, this description is fully complete.

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

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

Schema coverage is 100%, but the description enriches parameter meanings by explaining how `size_usd` is interpreted differently in single-market mode (max spend vs target proceeds) versus basket mode (settlement notional, shares per leg). It also clarifies `side` defaults and mode selection between `market` and `event`, adding context that the schema's field descriptions do not fully convey.

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

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

The description opens with a specific verb-plus-resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and enumerates the exact outputs, making it easy for an agent to know what the tool does and how it differs from siblings like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create directional risk), providing both positive usage context and a clear exclusion—this is the pre-trade risk check, not the signal generator.

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

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

The description discloses extensive behavioral detail beyond the read-only annotation: it explains output structure (leg-by-leg prices, matched spread[].top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and exact conditions for warnings (e.g., matched_pairs:0 with skipped_cross_type>0). It also communicates real-world limitations and the fact that pre-mapped topics are often non-tradeable. This is far more transparent than typical read-only tool descriptions.

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 on the longer side but every sentence contributes essential operational detail, such as mode distinctions, response format, warning conditions, and temporal alignment. It is front-loaded with the core purpose and then expands into structured sections. A slightly more formatted layout would improve scannability, but the density is justified for a complex tool with no output 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?

Given there is no output schema, the description fully compensates by specifying the response format, the meaning of top_spreads_pp, and the semantics of all safety fields. It also addresses edge cases such as non-equivalent bet shapes, unrelated events, and temporal mismatches. This is a complete operational picture for an agent to invoke the tool and interpret results correctly.

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

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

Although the schema covers 100% of parameters, the description adds meaningful semantic context: it explains that `topic` is a pre-mapped shortcut with ten specific values, and that explicit tickers/slugs override the mapped side for custom pairings. It clarifies the relationship between the three optional parameters and their two modes. This complements the schema rather than just repeating it.

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

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

The description clearly identifies the tool's specific resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It goes beyond a generic label by explaining the two modes, the outcome comparison, and the concept of equivalent bet shapes. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on venue-to-venue spreads on matched events.

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

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

The description offers explicit guidance on how to use the tool: choose between the `topic` shortcut mode or explicit `kalshi_event_ticker` + `polymarket_event_slug` pairing. It also provides important exclusion criteria, warning that most pre-mapped topics return compatibility_warning and are not tradeable, and that temporal misalignment makes spreads meaningless. It does not explicitly name alternative sibling tools, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the upstream path rewrite, automatic resolution of labels against table metadata, defaulting to latest year and totals for unnamed dimensions, and the `selection_resolved` feedback channel. No contradiction with annotations — the description reinforces the read-only, non-destructive nature.

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 dense paragraph but well-organized: purpose first, then path format, then select semantics with a concrete worked example, then the body alternative. Every sentence carries operational value — the one mild cost is the extended worked example, which is verbose but illustrative. Appropriate length for a tool with two interlocking call modes and no output 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?

For a complex tool with nested body objects, dual select/body modes, no output schema, and a legacy-path quirk, the description covers the essential operational surface: path normalization, label resolution, defaulting behavior, and the selection_resolved/figures return shape. The companion table_meta sibling covers metadata discovery. Minor gap: it doesn't specify the return structure of `figures` beyond 'flattened,' which is acceptable given no output schema exists.

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%, giving a baseline of 3. The description adds substantial value beyond the schema: it explains that select values may be English labels or native Finnish codes, that array values take several items, the 'omit entirely to get every measure' behavior, and the precedence of body over select. These semantics are not merely restated in the schema, so the extra effort earns above baseline.

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

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

The description opens with a concrete verb-resource pair ('Get an actual figure out of a Statistics Finland (StatFin) table') and grounds it in recognizable examples (tertiary qualifications, CPI, births/deaths, employment). It clearly differentiates itself from siblings like table_meta, which handles metadata rather than figures, and names the bare 4-character path format that distinguishes this tool's contract.

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 routes between the two call modes: use `select` for plain-English labels (the primary path) and 'Pass `body` instead for a raw PxWeb query object when you already know the codes.' It also states the 'Answers in ONE call' guidance and notes the legacy path form is rewritten for the caller. It could more explicitly name table_meta as the sibling for code discovery, but the schema's body param does reference 'Codes come from table_meta.'

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 behavior. The description adds valuable context about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of omitting the key to list all keys. No contradictions with annotations, and it avoids repeating what annotations already state.

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 to three sentences, front-loaded with the primary function, and every sentence earns its place. It includes purpose, usage guidance, scoping, and pairing with related tools without excessive verbosity.

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?

This is a simple tool with one optional parameter and no output schema. The description adequately covers its purpose, when to use it, scoping, and relationship to sibling tools. There is no ambiguity left for an agent to select and invoke it correctly.

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

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

The schema description covers 100% of parameters (key: 'Memory key to retrieve (omit to list all keys)'). The description adds semantic context beyond the schema by giving examples of keys (user's target ticker, address, prior research notes) and explaining the scoping of keys, which helps the agent understand what to pass and what to expect.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and distinguishes itself from sibling tools like remember and forget by clarifying it retrieves rather than saves or deletes.

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

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

Provides clear context on when to use: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions complementary tools ('Pair with remember to save, forget to delete'), but does not explicitly exclude alternatives or state when not to use it, so it misses full marks.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: each alert carries source, citation_uri, and raw payload; mark_read:true changes read state so subsequent calls return only newer events; and the feed location. This is rich behavioral context that the annotations alone do not provide.

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

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

The description is three sentences, front-loaded with the core purpose, and packs a surprising amount of useful detail without fluff. Every sentence earns its place—purpose, payload/filtering, mark_read semantics, and the alternative HTTP endpoint.

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 explains exactly what the return values contain (source, citation_uri, raw payload), how filtering works, and the mark_read behavior. It also provides an HTTP alternative for scripts. For a moderate-complexity tool with no required parameters, this is complete and self-sufficient.

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

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

With 100% schema coverage, the schema already documents all parameters. The description adds value by giving a concrete example for type ("sec_8k"), specifying the format for since (ISO timestamp), and explaining the side-effect of mark_read:true. This goes beyond the schema's descriptions, which are more terse.

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

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

The first sentence, 'Pull fired events from your subscription feed', uses a specific verb and resource, clearly distinguishing it from sibling tools like list_subscriptions. It further specifies that these are alerts from the evaluator written to the persisted feed, making the tool's purpose unambiguous.

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

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

The description states that polling works fine, which is useful implementation guidance, and notes the feed is also available via direct HTTP GET for scripts/dashboards, giving an alternative path. It does not explicitly name alternative tools or when not to use it, but the context strongly implies its niche among 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 the readOnly/idempotent hints, the description discloses source fan-out (SEC, GDELT/GNews, USPTO), fallback logic (GNews on rate limit/5xx), future failure mode (PatentsView sunset), and return structure. This is rich behavioral context that the annotations do not capture.

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

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

The description is dense but well-organized, front-loading intent with example queries before covering sources, parameters, and alternatives. Every sentence contributes, though the length is substantial; could be slightly tightened but remains appropriately structured for the tool's complexity.

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

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

Despite no output schema, the description clearly communicates return format (changes[] grouped by source, total_changes, citation URIs), source behavior with fallbacks, and a usage boundary via entity_profile. This covers the essential context for a multi-source tool and leaves minimal ambiguity.

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

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

Schema covers all parameters at 100%, but the description adds practical value by explaining `since` with both ISO and relative shorthand examples, and recommending '30d' or '1m' for typical monitoring. This goes beyond the schema's basic type descriptions, though not exhaustively.

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

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

The description clearly defines the tool as a change feed for a company over a time window, using concrete example queries ('What's new with X', 'latest on Y'). It distinguishes itself from sibling entity_profile by explicitly stating when to use the alternative, ensuring the resource and verb are specific and non-overlapping.

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 signals through natural language examples and directly names entity_profile as the alternative for static profiles. This gives the agent clear decision boundaries, exceeding simple 'use when' guidance.

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

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

The description goes beyond annotations by disclosing persistence behavior: key-value scoping by identifier, authenticated users get persistent memory, anonymous sessions retain 24 hours. It also notes the pairing with recall/forget. While annotations indicate idempotent and non-destructive, the description adds crucial lifetime details.

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 yet comprehensive, with each sentence adding value: purpose, usage, storage details, and companion tools. It is front-loaded with the main action and efficiently structured 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 key-value store with no output schema, the description covers essential aspects: what to store, when to use, persistence rules, and relationships to other tools. It could mention return value or error scenarios, but for this low-complexity tool, the existing information is sufficient.

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

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

The input schema already covers both parameters with examples (key and value). The description does not add new parameter-specific semantics, but it contextualizes them through usage examples. With 100% schema coverage, this is a solid baseline; no additional parameter info 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 the tool's function: 'Save data the agent will need to reuse later' with a specific verb (save) and resource (data). It distinguishes itself from siblings by explicitly pairing with recall and forget, making its role in the memory system 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?

It provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also mentions the companion tools recall and forget, offering clear context for when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining graceful degradation (LEI/FIGI enrichment fails but EDGAR returns), internal cascading lookups ('replaces 2-3 manual lookups'), and that unresolved identifiers are stated explicitly under 'unresolved' rather than omitted. This goes beyond what annotations provide.

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

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

The description is moderately lengthy but well-structured: it opens with relatable example queries, then states the core purpose, followed by detailed support for each type. Every sentence provides useful information; there is minimal redundancy. Some wording ('cross-source identity spine') is slightly dense but still valuable. It earns its length without being verbose.

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

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

Despite having no output schema, the description fully explains what the tool returns (canonical identifiers with source labels, explicit unresolved field, LEI/FIGI when available). It covers input formats, error/fallback behavior, and internal complexity. For a 2-parameter lookup tool, this is a complete and self-contained specification.

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 descriptions for both parameters (type, value). The description significantly enriches these: it explains what each entity type (company vs drug) returns, enumerates acceptable input formats for company (ticker, CIK, ISIN, name) and drug (brand/generic), and adds context like ISIN resolving to legal entity via GLEIF mapping. This is exemplary additive semantics.

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

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

The description opens with concrete example queries and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input'. This clearly defines verb (resolve) and resource (names to identifiers) and distinguishes it from sibling tools like entity_profile or compare_entities, which are about comparing or profiling entities rather than resolving.

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 FIRST whenever you have a name but need an ID' and outlines accepted input formats (ticker, CIK, ISIN, name for company; brand/generic name for drug). It implies when to use this tool versus alternatives (e.g., if you already have an ID, use other tools), though it could be more explicit about exclusion cases. The guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: that it 'probes each entity with ai_visibility_check' (indicating external AI API calls) and that it returns a ranked list with score/confidence/signal density. This goes beyond the annotations and clarifies the external, idempotent read behavior 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 three sentences: it states the core action, a practical use-case with an example, and the return value. Every sentence earns its place, and the most critical information is front-loaded. No fluff or redundancy.

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

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

The tool has moderate complexity (4 params, 1 required, no output schema). The description explains the use case, the probing mechanism, and the return structure (ranked list with fields). It does not describe error handling or edge cases (e.g., what happens with invalid entity counts), but given schema coverage and annotations, it is sufficiently complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% (each param has a clear description), so baseline is 3. The description adds slightly by explaining the overall probe-and-compare mechanism and the 'subject vs competitors' narrative, but it largely restates what the schema already covers. It doesn't introduce new semantic meaning beyond the schema for any parameter.

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

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

The description clearly states a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side' with a detailed breakdown of the process (probes, ranks, surfaces). It distinguishes itself from sibling tools like ai_visibility_check by explicitly mentioning it as the underlying single-entity probe, and positions this as the multi-entity version for competitive audits.

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

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

The description provides clear use-case context ('competitive AI-marketing audits') and an illustrative question, and implicitly contrasts with ai_visibility_check by stating it probes multiple entities. However, it doesn't explicitly mention when not to use it (e.g., for single-entity checks) or name direct alternatives like compare_entities, leaving a small gap in explicit 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?

Despite readOnlyHint already marking this as safe, the description adds valuable behavioral context: it fans out to external services, handles partial failures gracefully, and warns that the first bundlephobia measurement can take 5-30s with sources_failed as the failure signal. 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 moderately long but every sentence carries functional value: composite purpose, use cases, output fields, ecosystem limits, and failure behavior. It is well structured and front-loaded, though slightly dense.

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

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

With no output schema, the description fully enumerates the return block: is_latest, license, published_at, advisory_count, bundle sizes, dependency_count, ESM/tree-shake flags, advisories, links, and alternative versions. It also covers latency and partial failure, making it highly complete for a composite tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the npm ecosystem scope and mentions the version default, but the schema already documents these details. No additional parameter semantics beyond the schema are provided.

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

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

The description opens with a specific, composite purpose: 'should I add this npm package to my project' check in ONE call, spanning deps.dev and bundlephobia. It clearly differentiates from siblings by naming the exact data sources and the decision it supports.

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: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also names an alternative for non-NPM ecosystems (deps.dev:version directly), providing clear boundaries and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral details beyond annotations, including the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, and the 200K char truncation limit with a flag. These are non-obvious behaviors that affect agent expectations.

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

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

The description is longer than average but every sentence carries functional weight: purpose, usage condition, pairing strategy, and technical implementation. It is front-loaded with the core action and output, and the additional details are justified by the tool's complexity. Slightly dense but not wasteful.

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

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

With no output schema, the description compensates by explaining return values (top-N passages, offsets, similarity scores). It also covers usage context, pairing with another tool, and a hard limit (200K chars). Missing minor details like error behavior or auth, but these are not critical for this read-only, self-contained 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 description coverage is 100%, so the structured data already documents all three parameters well. The description adds some context (e.g., 'text you already pulled', example queries) and references the truncation cap, but it does not significantly enhance parameter understanding beyond the schema. It meets the baseline but does not excel.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb-resource pair ('search inside') and explicit outputs (top-N passages with character offsets and similarity scores). It also distinguishes itself from sibling tools by mentioning the pairing with ask_pipeworx_grounded, making its niche clear.

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

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

The description explicitly states when to use the tool ('Use when the record is too big to cram into the prompt') and names an alternative/complementary tool (ask_pipeworx_grounded) with guidance on how they pair. It does not provide an explicit 'when not to use' scenario, but the context is sufficient for an agent to infer appropriate 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness, so the description does not need to restate those. It adds valuable behavior details: the distinction between folder and table entries, the format of IDs, and how to combine paths (e.g., 'vkour/15ig.px'). This goes beyond the structured annotations and helps the agent predict output structure and integration with other tools.

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 long but each sentence serves a purpose: stating the purpose, defining the two entry types, and giving concrete examples. It is front-loaded with the primary function and then details, making it easy to scan. It is appropriately sized for the complexity of the tool.

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

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

For a tree-browsing tool with no output schema, the description provides enough context: it explains what the entries are, how to navigate, and how to use the returned IDs with other tools. It does not describe the exact structure of the response (e.g., fields like name, childCount), but the essential behavior is covered. Given the tool's simplicity and the annotations (openWorldHint), this is nearly complete.

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

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

The schema already covers the 'path' parameter with a description and examples (coverage 100%). The tool description enriches it by explaining the meaning of folder IDs (e.g., 'vkour' for education) and how they are used to drill in, adding context beyond the schema's basic definition. This is a meaningful enhancement over 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 explicitly states the tool browses the StatFin subject tree, lists the topics covered, and distinguishes folders (type 'l') from tables (type 't'). It also differentiates itself from siblings by explaining that table IDs are passed to table_meta and query_table, making it clear this tool is for discovery, not querying.

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

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

The description gives clear context on when to use the tool—to browse and drill into the subject tree—and implicitly states that table IDs from here are used with table_meta/query_table. It does not explicitly enumerate alternatives or exclusions, but the examples and mention of downstream tools provide strong usage guidance.

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

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

The description reveals important behavioral details: the tool requires authentication, subscriptions persist only for OAuth accounts, and SMS delivery has a 10/day cap with phone verification required. These go well beyond the annotations, which only indicate readOnlyHint/closedWorldHint/idempotentHint/destructiveHint, providing actionable operational context.

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

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

The description is dense but well-organized, starting with a clear action sentence and then detailing types and delivery channels. It could be more scannable with bullet points, but every sentence contributes necessary information for the complex tool.

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

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

Despite lacking an output schema, the description explains the return value (subscription id), authentication requirements, and delivery channel options. It provides enough context for the agent to decide when to use this tool and how to configure it correctly, especially with the type-specific examples.

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 enriches the schema parameters with concrete examples and mappings, such as `items:["5.02"] = officer change` for sec_8k and `params:{topic:"fed"}` for polymarket_edge. This adds meaning beyond the schema's property descriptions, helping the agent construct valid parameter objects.

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

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

The description states the exact action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value ('Returns the new subscription id'). It differentiates from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on the create operation and enumerating supported subscription types.

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 establishes clear prerequisites and constraints: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also describes delivery channels and usage examples for each type. However, it does not explicitly compare with alternative tools for similar data access (e.g., recent_alerts) beyond mentioning the feed channel.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety surface is clear. The description adds meaningful behavior beyond that: output is category-bucketed, examples are drawn from the live catalog, and passing a topic changes the focus. It does not describe output size or error handling, but given annotation coverage this is sufficient.

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

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

The description is long but every clause adds value. It front-loads the purpose and output behavior, then parameter usage, then when-to-use guidance. It could be tightened slightly, but the density of useful information justifies the length.

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

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

The tool is simple (one optional parameter, no output schema), and the description covers purpose, return contents, parameter semantics, and invocation timing. For an onboarding tool, this is complete: an agent can decide whether to use it and how to call 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?

Although schema coverage is 100%, the description adds important semantics beyond the schema: it explains that omitting `topic` returns a cross-category spread, while passing a topic focuses results, and it maps example values to categories. This helps the agent choose correct argument values.

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

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

The description clearly states this is 'the onboarding entry point for an agent that just connected and wants to know what is worth asking' and that it 'returns category-bucketed example questions' with 'the exact tool + argument shape' that answers each. It distinguishes itself from sibling tools by explicitly saying to use this FIRST when the agent does not yet know what Pipeworx can do, and to learn how to call the meta-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?

Explicit guidance is provided: '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 the two invocation modes—no arguments for the full spread, or with a `topic` to focus—and gives concrete examples of topic values.

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, openWorld, idempotent), the description explains that the tool returns all valid values and that dimension codes are native Finnish and cannot be derived from English titles. This gives agents a clear expectation of the output's nature and the necessity of the path parameter, adding significant 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 longer than typical but each sentence adds necessary context (purpose, usage timing, code examples, path format). The purpose is front-loaded, and the detail is warranted given the non-obvious Finnish codes. It is somewhat verbose but not wasteful.

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 only one parameter, no output schema, and rich annotations, the description fully covers the tool's functionality, including examples and important cultural background. An agent can call it correctly without needing further specification.

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

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

The schema already documents 'path' with examples and description covering 100% of the parameter. The description reinforces this with additional examples and explains why the path format matters (bare 4-character id) and that it points to a specific table, adding value beyond the schema baseline.

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

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

The description states a precise action ('List the dimensions and every valid value') on a specific resource (a StatFin PxWeb table), and clarifies what the tool is for (to inspect breakdowns before slicing, or when query_table returns no matches). It clearly distinguishes this metadata-exploration tool from data-fetching siblings like query_table.

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 when to use it ('before slicing it, or when query_table reports that a value matched nothing') and gives context on the Finnish dimension codes, which prevents misuse. It also indirectly points to the 'subjects' tool for finding table ids (in the schema example), offering clear guidance on the workflow.

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

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

The description goes beyond the annotations by explaining that rows are deactivated rather than deleted, and that historical events remain accessible via recent_alerts. It also discloses the ownership enforcement rule. The annotations already note idempotentHint and destructiveHint=false, and the description reinforces and adds context beyond those structured hints.

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

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

The description is two sentences long, immediately states the primary action, and packs the ownership and deactivation details into the second sentence without wasted words. It is perfectly front-loaded and 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?

For a single-parameter tool with no output schema and no nested objects, the description covers the essential contextual points: action, target, ownership, and post-effect on data. It does not mention error cases or the return value, but given the simplicity and existing annotations, it is nearly complete. A 4 is appropriate.

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

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

The input schema already provides full coverage: one required parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description only echoes 'by id' and adds no semantic detail beyond what the schema provides. Since schema coverage is 100%, baseline is 3.

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

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

The description opens with a specific action and target: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe (creates), list_subscriptions (lists), and recent_alerts (reads event history). The ownership constraint is also stated, further refining what the tool does.

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

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

The description implies when to use the tool (when you want to cancel your own subscription) and even notes that deactivation preserves historical events, which helps decide between cancellation and other actions. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

The description adds critical behavioral context beyond the annotations: 'could_not_verify means the check did not happen... must not be shown as one' and distinguishes it from 'unsupported'. It also discloses the internal routing (SEC vs. grounded) and the exact percent-delta math, which helps the agent interpret results correctly and safely.

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

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

The description is longer than average but every sentence contributes: examples, use case, routing logic, return values, and important caveats. It is front-loaded with the tool's purpose and key examples, but there is some redundancy (e.g., the initial natural-language examples could be condensed). Overall well-structured and informative.

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 thoroughly explains return values (verdict types, actual value, citation, reasoning) and edge cases (could_not_verify vs. unsupported). It also covers the two processing paths and performance benefit, making it complete for an agent to invoke and interpret results even without a schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the claim verification workflow (e.g., 'exact percent-delta math' for financial claims, 'grounded pipeline' for others). It does not repeat the schema parameter descriptions, and the tolerance parameter semantics remain primarily in the schema, hence not a 5.

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 claim verification with verbs like 'fact check' and 'verify the claim that', and distinguishes it from siblings by scoping to factual claim validation with a verdict. It also differentiates the SEC/XBRL fast path for financial claims versus a grounded pipeline for other claims, which sets it apart from general ask/query tools.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing to two distinct pipelines (SEC vs. grounded), giving clear when-to-use guidance. It does not explicitly name sibling alternatives but notes it 'Replaces 4–6 sequential calls', providing a comparative alternative, though an explicit 'do not use for X' is absent.

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