Stat Ee

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

Annotations already declare readOnly/idempotent, yet the description adds meaningful behavioral context: the default model is free, passing `_apiKey` incurs direct Anthropic costs, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. It also implies external network calls to LLMs, which is a key behavioral trait 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 three tightly-written sentences: purpose+scoring, default and key-based model expansion, and return format+use cases. No wasted words; front-loaded with the core purpose.

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

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

Despite no output schema, the description clearly specifies the return structure per model and combined view, explains the two model options and the API key requirement, and lists concrete use cases. This is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the cost implication of `_apiKey` (BYO key, pay Anthropic directly) and the default model behavior for `models` (default to Workers AI). This extra context enriches parameter semantics beyond the schema.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs), what it measures (visibility 0-100), and the output format. It distinguishes itself from sibling tools like ask_pipeworx by framing it as a scored audit rather than a Q&A, and mentions concrete use cases (AI-marketing audits, pre-launch checks, competitive monitoring).

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-case context ('Useful for...') and explains when to pass `_apiKey` (to also probe Anthropic). It does not explicitly name alternatives or give 'when not to use' exclusions, but the use-case framing is clear enough for an agent to select it over similar query tools.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavior beyond that: it routes to thousands of sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradiction with annotations exists.

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

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

The description is longer than average but every sentence earns its place: it front-loads the critical 'prefer over web search' guidance, gives concrete examples, states the default-entry-point role, and names alternatives with conditions. The structure is dense and actionable rather than redundant.

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

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

Given the tool's complexity, the description fully covers when to use it, what it does, how it behaves, which alternatives exist, and what kinds of questions to ask. There is no output schema, but the description's examples and expected-answer framing compensate sufficiently for an agent 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% and all parameters are aliases for the same question field, so the baseline is 3. The description adds value by providing natural-language trigger phrases and concrete example questions, reinforcing that the parameter accepts broad factual queries. It does not add new constraints, but the examples meaningfully clarify expected usage.

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

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

The description uses a specific verb and resource ('ask Pipeworx', 'routes the question to the right one of 5,708 tools') and clearly differentiates the tool from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. It also gives concrete examples of what it answers, making the purpose unmistakable.

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

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

The description is explicit about when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when not to ('Step up only when needed'), naming the exact sibling tools and the conditions that select them. It even covers edge cases like breaking news and 'world's saying about X'.

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

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

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior, and the description adds meaningful context beyond that: beta status, live candidate routing tests, current equivalence to ask_pipeworx, and the experimental edge nature. This gives the agent an accurate mental model of what happens when it invokes the tool.

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

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

The description is tightly written and front-loaded with the most important distinction (beta, identical to ask_pipeworx), then covers usage, current status, and a reassurance that it is fully functional. Every sentence earns its place with no wasted words.

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

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

Given that this is a natural-language router input tool with no output schema, the description is complete: it explains the relationship to the stable counterpart, the current active state, what the response shape looks like, and why the agent might choose it. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100% and every alias is already documented in the schema as an alias for question. The description adds no parameter-level details beyond saying 'same arguments,' which is redundant with the schema. Baseline 3 is appropriate because structured data carries full parameter meaning.

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

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

The description precisely identifies the tool as a beta universal router, explicitly states that it is identical to ask_pipeworx in tools, arguments, and response shape, and differentiates it from the stable sibling by the candidate routing improvements. The relationship to the sibling is unambiguous, so an agent can immediately understand what this tool does and how it differs.

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

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

The description provides explicit when-to-use guidance: use it 'exactly like ask_pipeworx when you want the newest routing.' It also clarifies current behavior relative to the stable alternative and confirms this is a full router with no fallback layer, leaving no ambiguity about invocation choice or capability.

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

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

Annotations already establish readOnly/openWorld/idempotent safety, and the description adds substantial behavioral detail: it returns verbatim evidence, emits structured refusal reasons when data does not directly answer, routes across 5,708 tools, and costs one extra LLM call. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return contract, refusal reasons, usage scenarios, and cost tradeoff. It is front-loaded with the core grounding guarantee before the mechanical details.

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

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

Given there is no output schema, the description fully specifies the success and refusal response shapes, evidence quoting, confidence, and source fields. It also covers when to prefer the sibling tool, making the definition complete for correct invocation and interpretation.

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 fully documents that all six parameters are aliases for a single natural-language question. The description does not add parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific, distinctive capability: a hallucination-resistant answer mode that extracts answers only from fetched tool results. It explicitly contrasts itself with ask_pipeworx by describing the additional grounding/refusal behavior, so an agent can tell them apart without inspecting schemas.

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

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

Provides clear when-to-use guidance: use when an answer will be quoted, cited, or acted on and facts must not be invented, with concrete example domains. It also gives an explicit when-not-to-use recommendation, preferring the cheaper ask_pipeworx for casual lookups, and names the alternative directly.

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

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

The description goes far beyond the annotations by disclosing the resolver contract, status codes (low_confidence_match, market_closed_or_inactive), fan-out behavior, safety short-circuiting, and cancellation-rule handling. This provides rich behavioral context beyond the readOnly/idempotent hints.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the core purpose and use cases. Some redundancy exists (e.g., blocking routes repeated), but overall each section earns its place.

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

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

With no output schema, the description thoroughly explains the return shapes (market, analysis, evidence), the resolver contract, parent_event extractor, news fallback fields, and safety statuses. It even covers cancellation-rule risk, making the tool fully usable without additional documentation.

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 does not add new parameter-level semantics beyond what the schema already states (market can be slug/URL/question); it merely repeats examples and adds response-shape context, not parameter meaning.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from sibling tools like polymarket_arbitrage/edges by focusing on per-bet research, and gives explicit use cases ('should I bet on X', etc.).

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 'Use for' guidance covers the primary intents: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, it does not name alternatives or state when NOT to use this tool, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations: it lists specific data sources (SEC EDGAR/XBRL, FAERS), mentions handling of off-calendar fiscal years, describes sorting by primary metric, and states the return format (paired data + citation URIs). This fully discloses behavior, with no contradiction to annotations.

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

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

The description is dense but every sentence earns its place. It front-loads with examples, then provides preference guidance, per-type details, fiscal-year handling, sorting behavior, and efficiency benefits. No wasted words; it's well-structured and 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?

This is a complex tool with two entity types and no output schema. The description covers all essential context: what data is pulled for each type, fiscal-year handling, result sorting, return format, and efficiency. It leaves no meaningful gaps for the intended use case.

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

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

Although the schema already describes both parameters, the description adds substantial meaning: for 'type', it explains the different data sources and fiscal-year handling for 'company' vs 'drug'; for 'values', it gives concrete examples (tickers vs names) and explains the min/max. This goes far beyond the schema descriptions.

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

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

The description is extremely clear: it states the tool performs side-by-side comparison of 2–5 companies or drugs in one call. It uses specific verbs like 'compare' and 'rank', and provides trigger examples ('X vs Y', 'which is bigger'). It also explicitly distinguishes from sequential single-pack lookups, making its unique 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive for when to use this tool instead of alternatives. It also explains what each type ('company' vs 'drug') does, giving concrete context for choosing the right mode.

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 this readOnly, non-destructive, and idempotent, and the description adds substantial behavioral context: account/paywall requirements, 15-90s latency, parallel decomposition, gap reporting, contradiction flags, hop fields, resolvable citation_uri, semantic excerpting, and the 'never invented' guarantee. There is no contradiction with annotations.

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

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

The description is dense and front-loaded with the most decision-critical information (account requirement and when to use ask_pipeworx instead). While every sentence carries useful information, the block is long and somewhat repetitive about depth behavior that the schema already documents.

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

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

For a complex tool with no output schema, the description is remarkably complete: it explains the return packet structure, evidence fields, gap handling, contradiction detection, citation resolvability, latency expectations, account tiers, and limitations. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds behavioral meaning beyond the schema: it explains how depth values affect iteration (quick single-hop, standard gap recovery, thorough leads-chasing) and clarifies that the question parameter is meant to be broad/multi-part. This goes beyond the schema's dry enum descriptions.

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

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

The description opens with a specific, distinctive purpose: grounded multi-source research over 1,494 structured data sources, decomposing a question into facets and routing them in parallel across 5,708 tools. It explicitly contrasts itself with open-web search and with ask_pipeworx, so an agent can clearly distinguish it from siblings.

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

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

Usage guidance is explicit and actionable: use for broad/multi-part structured-data questions; use ask_pipeworx for single lookups or breaking/current-news; if not signed in, use ask_pipeworx. It even explains why (deep_research returns mostly empty gaps[] for news topics). This fully covers when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is disclosed. The description adds behavioral context beyond annotations: it returns top-N tools with names, descriptions, and full input schemas, and explicitly notes that results are ready to call directly with no second schema lookup. It doesn't mention limitations like pagination or rate limits, but the key behavioral traits are covered.

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 structured logically: purpose, when to use, return value, and a directive to call first. The list of domains is somewhat long but directly informs the agent of relevant use cases. Every sentence contributes value, and there is minimal redundancy, though it could be slightly trimmed.

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

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

The description is complete for the tool's role: it explains the return format (top-N tools with schemas and examples), the lack of need for a second lookup, and the recommended invocation order among many sibling tools. Even without an output schema, the description sufficiently covers what the agent should expect, given the tool's straightforward discovery purpose.

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 each parameter having a description. The description itself does not add significant parameter-level meaning beyond the schema; it does mention that query accepts aliases, but this is already encoded in the schema properties (q, task, search, description). The baseline of 3 is appropriate because the schema carries the parameter semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools) and verb (find/discover), and distinguishes itself from sibling tools by being a meta-tool that returns available tools rather than performing domain-specific tasks. The listed domains (SEC filings, FDA drugs, etc.) further clarify scope.

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

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

Explicit guidance is provided: '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.' This tells the agent exactly when to invoke this tool instead of directly using a specific sibling, making it a strong usage guideline.

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

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

Beyond the read-only, idempotent, and open-world annotations, the description discloses significant behavioral details: parallel fan-out across multiple sources, soft-failure for the USPTO API, GDELT→GNews fallback, and the exact output fields (filings, fundamentals, patents, news, LEI). It also mentions the limitation on input types, enhancing transparency.

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

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

The description is dense but every part serves a purpose: example queries, usage preference, data source list, output details, and input constraints. It is a single long paragraph, which slightly hurts scannability, but there is no fluff and all information is relevant.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It specifies the exact return fields, the parallel-call behavior, fallbacks, and input limitations. This is sufficient for an agent to select and invoke the tool correctly without needing additional documentation.

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

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

Schema descriptions already fully cover both parameters, but the description adds practical input semantics: examples ('AAPL', '0000320193'), the zero-padding requirement for CIK, and the explicit note that names are unsupported. This goes beyond the schema's basic descriptions, helping the agent format 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 clearly states the tool's purpose: creating a full cross-source profile of a US public company in one parallel call. It uses specific verbs ('profile', 'brief me on') and enumerates the included data sources, distinguishing it from related tools like compare_entities and deep_research by emphasizing its holistic, single-call nature.

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

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

The description explicitly tells when to use this tool: whenever the user asks for a holistic company view, and it explicitly prefers this over chaining single-pack lookups. It also states that names are not supported and instructs to use resolve_entity first, providing clear alternatives and exclusion 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds valuable context beyond annotations: keyless access (no auth needed), the gross-vs-net distinction, the 'per employee position' counting convention (double-counts dual-job holders), and that headline fields describe the newest period. This is genuinely useful behavioral information for correct interpretation.

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 efficient and front-loaded, leading with the core function and key data source in one sentence. The PREFER list is somewhat redundant (multiple trigger examples), but the caveats (gross vs net, per position counting) are valuable and earned their space. Slightly verbose due to the repeated trigger phrases, 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?

For a single-parameter, non-nested tool with strong annotations (readOnly, idempotent, openWorld), the description fully covers the key caveats: source table, keyless access, gross/net distinction, statistical convention (per employee position), and time scope. No output schema exists, but the description's mention of 'recent quarterly trend' and 'headline fields describe the newest' provides sufficient return-shape context 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 description coverage is 100%, so the quarters parameter is already documented in the schema ('How many recent quarters to include (1-40, default 8)'). The description adds minimal extra meaning for the parameter, though it clarifies that headline fields describe the newest period. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description clearly states the tool retrieves Estonia's average and median monthly gross wage from Statistics Estonia (table PA111), specifing gross vs net, per employee position, and median vs mean distinction. It distinguishes itself from sibling tools by explicitly naming table_meta/query_table/subjects for breakdowns, showing a specific verb+resource+scope.

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

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

Provides explicit PREFER phrases ('what is the average wage in Estonia', 'Estonian salary', etc.) giving clear trigger intents. It also explicitly states when NOT to use it ('Use subjects/table_meta/query_table for breakdowns by economic activity or county'), naming the alternative tools.

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

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

Annotations already declare destructiveHint and idempotentHint, so the safety profile is known. The description does not add further behavioral details such as behavior when key is missing, irreversibility, or effects on other components; it only restates the delete action.

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

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

Two sentences with action first, then usage conditions. No redundancy, and every sentence adds value.

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

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

For a single-parameter destructive tool with annotations covering risk, the description is sufficient: it defines the operation, use cases, and related tools. It could be slightly more complete by explaining the result of deleting a non-existent key, but the idempotent hint partially covers this.

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

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

Schema covers the single 'key' parameter with description 'Memory key to delete' at 100% coverage. The description adds no additional meaning for the parameter beyond what schema already provides.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory') with a clear key parameter, and distinguishes itself from siblings by explicitly pairing with 'remember and recall'.

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

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

It states explicit conditions when to use ('context is stale, task done, clear sensitive data') and identifies the complementary tools 'remember and recall' which serve the other storage operations.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable process details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also clarifies the output is a single text blob, giving beyond-annotation 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 three sentences, front-loaded with the core action, followed by output details and use cases. Every sentence contributes value; no fluff or repetition.

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

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

For a tool with 2 parameters and no output schema, the description fully covers what the tool does, how it behaves, what it returns, and when to use it. There are no significant gaps for the agent to guess.

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

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

Input schema covers 100% of parameters with clear descriptions for 'url' and 'max_links'. The description does not add any parameter-specific details beyond what the schema already provides, so it earns the baseline 3 for high schema coverage.

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

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

The description uses a specific verb ('Generate'), a clear resource ('llms.txt file'), and scope ('for any URL'). It also lists concrete outputs and distinct use cases (client indexing, own project, competitor audit), which differentiates it from sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly provides 'Useful for:' scenarios with three distinct contexts, covering when to invoke the tool. It lacks explicit exclusions or alternative tool references, so it doesn't reach a 5, but the context 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 and idempotentHint, so the safety profile is clear. The description adds useful behavioral detail: it returns specific fields (id, type, params, created_at, last_fired_at, fire_count) and focuses on 'active' subscriptions, which is valuable beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose and return fields, followed by a concise usage hint. Every sentence adds value and there is no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, returns, and usage. The absence of pagination or error details is acceptable given the tool's simplicity and strong annotations.

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

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

The input schema fully documents the single optional parameter include_inactive with a clear description. The tool description does not add anything about the parameter, but the schema already covers it entirely, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb ('list') and resource ('subscriptions'). It also distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading existing subscriptions.

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

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

The description explicitly says to use this 'to review what you're monitoring before adding more' and 'to find an id to cancel', giving concrete use cases tied to sibling actions. It does not explicitly name alternatives or exclusions, but the intended 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 provide no safety hints (all false), so the description carries the full burden. It discloses that filing without an account returns a claim_token, that passing the token back alone retrieves status, that the team reads digests daily, that there is a rate limit of 5 per identifier per day, and that it is free. This gives the agent a clear picture of side effects and limitations.

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

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

The description is long but densely packed with necessary information. It starts with the core purpose, then covers usage conditions, prohibitions, follow-up mechanics, rate limits, and cost. Every sentence contributes meaning, though a more structured format (bullets) could aid scanability. The length is justified given the nuanced semantics.

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

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

For a tool with no output schema, the description thoroughly explains what happens when filing, what happens when following up with a claim_token, and what parameters are expected. It even addresses ambiguity about which tools qualify. It covers the full lifecycle: when to use, when not, what to include, what to expect in return, and constraints.

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

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

Schema provides 100% coverage with descriptions for all parameters, so a baseline of 3 applies. The description adds value by explaining the claim_token usage pattern (pass it back later to read status) and the meaning of 'type' in the context of the tool's purpose. It also clarifies that claim_token is mutually exclusive with other arguments, which is not stated in the schema.

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

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

The description clearly states the resource (Pipeworx team) and the action (tell them something is broken, missing, or needs to exist). It enumerates specific feedback types (bug, feature, data_gap, praise) and disambiguates from other Pipeworx tools by emphasizing this is for feedback on tools served by this connection only. Distinct from sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly states when to use: for bugs, feature gaps, or praise. Also states when NOT to use: for tools from a different MCP server, directing users to file with that server instead. Provides a heuristic for uncertainty (Pipeworx tool names are the ones this connection lists). Includes the claim_token follow-up workflow as a secondary usage pattern.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by disclosing that results are cached (5min-1h), that no PII is included, and that data is self-aggregating from CF analytics-engine. This provides a clear picture of data freshness and privacy, adding significant context beyond the structured fields.

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

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

The description is well-organized: it states the tool's output, then lists three brief use cases, then adds transparency details. Each sentence contributes value, though the 'Useful for' list could be slightly more compact without losing meaning.

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

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

This is a simple, read-only analytics tool with a single optional parameter and no output schema. The description fully covers what it returns (top tools, top packs, total call volume), data source/caching behavior, and intended use cases, making it self-sufficient for an agent to decide when to call it.

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

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

The schema already provides 100% coverage of the single `window` parameter, including its enum values and the trade-off between short and long windows. The description only casually mentions the window options and does not add new parameter-level detail, 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 what the tool does: it returns top tools, top packs, and total call volume over recent windows. The verb 'Returns' and specific resource ('top tools, top packs, total call volume') distinguish it from siblings like discover_tools or recent_alerts. The title and description align perfectly.

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

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

The description provides three concrete 'Useful for' scenarios that tell the agent when to use this tool (discovering hot data sources, confirming canonical choice, alignment check). However, it does not explicitly name sibling alternatives or state when not to use it, so it falls just short of the highest bar.

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

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

The description goes far beyond the read-only annotation by detailing internal behaviors: it explains the partition_check sum logic, the >=0.30 Jaccard similarity anchor, placeholder filtering (>20% returns null signal), and the fill check against live CLOB depth with advice not to trade when realizable_edge_pp <= 0. This provides rich context that the annotations alone do not.

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

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

The description is lengthy but highly structured, with clear bolded labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded summary. Every section contributes essential operational detail, and the length is justified by the tool's complexity. There is no filler or repetition.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It describes the response shape (opportunities[], partition_check, fill check fields), handles edge cases (null signal, skipped_low_similarity, thin_legs), and provides actionable guidance on interpreting results. No critical gap remains for an agent to invoke 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?

Although the input schema already provides 100% description coverage for both parameters, the tool description adds significant semantic value by giving concrete example slugs ('fed-decision-may-2026'), explaining the behavior triggered by each parameter, and clarifying that full URLs are also accepted. This exceeds the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges (likely focused on edges) and polymarket_fill_risk (pricing risk), making its purpose unmistakable.

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

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

The description provides explicit usage guidance: call with NO args for trending_scan, use 'event' for a specific market, and use 'topic' for cross-event scanning. It explains when each mode is appropriate and even references an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'). This fully satisfies when-to-use/alternative guidance.

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

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

The description is exceptionally transparent about behavior beyond the readOnly/openWorld/idempotent annotations: it details the three response segments, the 24h-move warning, Kelly caps, placeholder-slug filters, the Fed signal caveat, caching at the KV level, and diagnostic funnel counters. There is no contradiction with annotations.

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

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

The description is a dense, single-paragraph wall of text with ALL-CAPS pseudo-headers and many parentheticals. Every sentence carries useful information, but the lack of structural formatting (sections, bullet points, line breaks) makes it harder to parse. It is information-complete but not 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?

With no output schema, the description carries the full burden of explaining return values. It thoroughly covers the response shape: by_segment, fed_candidates/fed_note, and _diagnostics, including what each segment contains and why segments can be empty. It also explains filtering behavior, caveats, and caching. This is a model of completeness.

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 every parameter already has a detailed description, which would normally earn a baseline 3. The description adds extra value by explaining how knobs interact (e.g., min_partition_leg_kelly nuance about parent-level kelly_fraction_half=0, tradeable-edge filters dropping unrealizable edges, slippage subtracted before Kelly). This pushes it 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 specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by emphasizing Pipeworx disagreement, the 'what should I bet on today' use case, and the three response segments.

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 the intended use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when to adjust knobs like min_liquidity and max_spread_pp. However, it does not explicitly say when NOT to use this tool or name alternative tools for different purposes, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so those basics are covered. The description goes far beyond by disclosing snapshot-gap behavior ('snapshots are written when polymarket_edges runs on a cache-miss'), the 60-day TTL limit, that decay is computed from daily closes not intraday, and that expired opportunities disappear because they are 'closed, resolved, or arbed away'. This rich behavioral context is genuinely useful for an agent.

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

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

The description is detailed but logically structured with sections for Purpose, Args, RESPONSE, and LIMITS. Each sentence carries information, and the RESPONSE section's field-level detail is essential given the lack of an output schema. While longer than average, the complexity of the tool's output justifies the length. A slight trim of the explanatory parenthetical about trading would make it tighter, but it is 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 fully documents the return structure: tracked[] with its fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. It also explains data limitations (TTL, snapshot gaps) and computation methodology. Given the tool's complexity and the available structured annotations, this description is complete enough for an agent to invoke and interpret responses confidently.

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

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

Input schema coverage is 100%, with defaults and allowed values for both parameters (days: 'default 14, clamp 2-30'; window: '24hr | 1wk | 1mo'). The description restates these but adds the concept of 'snapshot family' for window, which adds minimal semantic insight beyond the schema. Since the schema already provides complete parameter documentation, the baseline of 3 is appropriate; no meaningful extra meaning is 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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly frames the tool's purpose via the question 'how long has this edge existed and is it shrinking?' It clearly differentiates from the sibling tool polymarket_edges by focusing on historical persistence and trends rather than current edge data. The verb 'Answers' combined with the resource 'edge persistence and decay telemetry' is specific and unambiguous.

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

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

The description provides clear context by answering 'how long has this edge existed and is it shrinking?' and offers an interpretive insight ('a fresh wide edge and a 3-week-old wide edge are different trades'). This implies when to use the tool, but it does not explicitly name alternatives or state 'use this instead of X'. The mention of being 'built from daily polymarket_edges snapshots' hints at the relationship to sibling tools, but an explicit exclusion would elevate it to a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds substantial behavioral context beyond those: it walks the order-book ladder, returns fields like vwap_fill_price and slippage_pp, interprets size_usd differently across modes, and warns about partial basket fills converting an arb into unhedged directional risk. No contradiction with annotations.

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

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

The description is long, but every sentence carries operational weight. It is front-loaded with the core purpose, then organized by mode with clear labels (SINGLE-MARKET, BASKET). It avoids filler and includes concrete, enumerable outputs and risk guidance.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It enumerates all return fields for each mode, including per-leg fill detail, thin_legs[], capture_ratio, and max_clean_notional_usd, and explains the failure mode of partial basket fills. It leaves no ambiguity about how results are interpreted.

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 crucial meaning beyond parameter names: it defines single-market vs basket interpretation of size_usd, defaults for side and size, the clamp range, and the requirement that one of market/event be provided. This goes far beyond the schema's basic property descriptions.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges, and further clarifies the two modes (single-market vs basket).

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes and when each is appropriate, and points to alternatives by referencing sibling tools.

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

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

Annotations only provide readOnly/openWorld/idempotent hints, so the description carries the behavioral burden. It adds rich context: compatibility_warning and compatibility_codes behavior, never pairing unknown legs, skipped cross-type/cross-subtype counters, temporal_alignment, and per-entry flags. No contradiction with annotations.

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

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

The description is long but tightly structured and front-loaded with the core purpose, followed by mode explanations, response semantics, safety fields, and caveats. Section labels like 'TWO MODES' and 'SAFETY FIELDS' make it scannable, though the density is high.

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 carries the burden of explaining return interpretation. It covers top_spreads_pp, flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, compatibility codes, and the tradeability caveat, giving callers enough context to act on the result.

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 meaningful mode framing beyond the schema: topic shortcuts auto-fetch matching events, while explicit ticker/slug enable custom pairings and override the mapped side, which enriches the individual parameter descriptions.

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

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

The description opens with a precise function: cross-venue spread between Kalshi and Polymarket for the same resolving question, and the venue names distinguish it from Polymarket-only siblings. It also names the two input modes and the response structure, leaving no ambiguity about what the tool does.

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

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

The description clearly establishes when to use the tool: when comparing equivalent bets across Kalshi and Polymarket, and it explains both the pre-mapped topic mode and explicit ticker/slug mode. It also warns that pre-mapped topics often return compatibility_warning and that pre-mapped does not mean tradeable, though it does not explicitly name sibling alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds meaningful constraints: the body must be a PxWeb query object, values must come from table_meta, and there is a ~100k-cell limit. These are behavioral details beyond what annotations provide, with no contradiction.

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

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

The description is two sentences, with the main purpose front-loaded. Every sentence adds unique value: the first covers what the tool does, the second covers how to use it correctly (body semantics and limit). No filler or redundant content.

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

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

For a tool with nested body object and no output schema, the description covers the core aspects: purpose, input format, prerequisite, and a critical constraint. It doesn't explicitly describe return values, but the example in the schema includes response formatting, and the tool's purpose implies a return of statistical figures. The overall context is sufficiently complete for an agent to use 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% for both parameters, but the description adds value by explaining that body is a PxWeb query object and directing users to table_meta for valid dimension values. This clarifies how to construct the body parameter beyond the schema's minimal description.

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

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

The description states a specific action ('Pull ESTONIA official statistics figures') with a clear resource (Statistics Estonia table) and enumerates example topics (wages, population, GDP, prices, unemployment). It distinguishes itself from siblings by focusing on querying data from a table, as opposed to table discovery or metadata.

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

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

The description gives an explicit workflow prerequisite: 'get valid dimension values from table_meta first', which tells the agent to use the sibling tool first. It also warns about the ~100k-cell limit, guiding selection filtering. It doesn't explicitly state when not to use this tool vs alternatives, but the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, reducing the burden. The description adds valuable context beyond those hints: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of listing all keys when key is omitted. This provides a richer behavioral picture without contradicting the annotations.

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

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

The description is three sentences, each earning its place: the first states the core action and listing behavior, the second gives concrete use cases, and the third explains scope and pairing. It is front-loaded with the essential verb and resource, with no wasted words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, strong annotations), the description covers all necessary aspects: purpose, usage context, scope/isolation, and relationship to sibling tools. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%: the 'key' property already has the description 'Memory key to retrieve (omit to list all keys).' The description reinforces this with examples of realistic key values, but since the schema fully defines the parameter, the added semantic contribution is modest.

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 the specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes itself from siblings by naming 'remember' and 'forget' and giving concrete examples ('user's target ticker, an address, prior research notes'), which makes the tool's purpose unmistakable.

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

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

The description clearly indicates when to use this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references sibling tools ('Pair with remember to save, forget to delete'), implying the workflow. However, it does not explicitly state when *not* to use it (e.g., alternatives like search), so it stops short of a full when/when-not contrast.

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

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

The description discloses key behavioral traits beyond the annotations, such as the persisted feed behavior and the mark_read side effect ('Set mark_read:true to flag returned events read so the next call only shows newer ones'). This adds valuable context about state changes that the annotations alone do not convey. It does not contradict the readOnlyHint, as the default behavior remains read-only and the state change is opt-in.

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

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

The description is concise at five sentences, each serving a distinct purpose: stating the core function, describing the return value, explaining filtering, clarifying mark_read behavior, and noting polling/HTTP alternatives. It is front-loaded with the primary action and contains no fluff or repetition.

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

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

Despite having no output schema, the description explains the return fields (source, citation_uri, raw payload) and covers the main usage scenarios. It addresses state-changing behavior, filtering options, and even provides an external mirror URL. This is remarkably complete given the tool's complexity and the rich 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?

The schema covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra meaning by providing a concrete type example ('sec_8k'), clarifying the consequence of mark_read, and explaining what the returned payload contains. This enriches the parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull/return alerts), and the scope (most recent alerts). It distinguishes from sibling tools like list_subscriptions or subscribe by focusing on reading fired events, not managing subscriptions.

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

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

The description provides clear context for when to use the tool, noting that 'Polls work fine' and offering an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly mention when not to use it or name alternative MCP tools, so it stops short of fully explicit exclusions.

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

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

Annotations already mark readOnly/openWorld/idempotent/non-destructive. The description adds multi-source fan-out, GDELT→GNews fallback on rate limit/5xx, and USPTO patent soft-fail due to API sunset. These are beyond annotation fields.

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

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

Description is dense but well-structured; every sentence adds a function detail. Slightly longer than necessary, but not redundant.

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

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

Even without output schema, it describes return shape (changes[] by source, total_changes, citation URIs), source behavior, and fallbacks. Covers all operational aspects needed for invocation.

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

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

Schema covers 100% of params with descriptions; description adds no new parameter details beyond restating the `since` format already present in schema. Baseline 3 for high coverage.

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

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

Description clearly states it provides a 'change feed for a company in the last N days/weeks/months' and lists concrete natural-language triggers. It explicitly contrasts with entity_profile, distinguishing it from a key sibling.

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

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

Description opens with example queries, specifies when to use (recent changes) and when not (entity_profile for static profile). It also notes 'in ONE parallel call' as an efficiency rationale. This is 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?

Annotations only indicate idempotent and non-destructive. The description adds that memory is scoped by identifier, persistent for authenticated users, and retained 24 hours for anonymous sessions — beyond what annotations offer.

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

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

Four sentences, each with a distinct purpose: definition, use case, storage model, and sibling relationships. 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?

For a two-parameter tool with annotations, the description fully covers when to use, persistence behavior, scoping, and interactions with related tools. No gaps evident.

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 already covers both parameters with descriptions and examples (100% coverage). The description reinforces key-value pairing but adds little new parameter-specific information.

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

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

The description uses a specific verb ('Save') and defines the resource ('data the agent will need to reuse later'), clearly distinguishing this from sibling tools like recall and forget by naming them. It also gives concrete examples of what to store.

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

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

Explicitly states 'Use when you discover something worth carrying forward' and provides concrete examples. It also names pairings with recall and forget, giving clear usage context.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: graceful degradation of LEI/FIGI when sources are unavailable, explicit listing of unresolved identifiers under a dedicated field, and that each call cascades through multiple endpoints. 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 well-structured with example queries up front, a clear 'Use FIRST' guideline, and a bulleted breakdown of supported types. It is longer than average, but each sentence adds value—explaining resolution logic, data sources, and edge cases. A slight reduction from 5 due to minor redundancy (e.g., repeating input acceptance details).

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

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

Given the tool's complexity (multiple entity types, multiple external sources, fallback behavior) and the absence of an output schema, the description is remarkably complete. It covers both company and drug resolution, explains what identifiers are returned, how they are labelled, how unresolved identifiers are handled, and degradation behaviour. No gaps remain for an agent to reasonably use this tool correctly.

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

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

Schema coverage is 100%, but the description greatly enriches parameter semantics. For 'type', the description explains the resolution pipeline per entity type (sources like SEC EDGAR, GLEIF, OpenFIGI) and accepted input formats. For 'value', it details acceptable values (ticker, CIK, ISIN, name for company; brand/generic for drug) and even gives examples. This goes far beyond the schema field descriptions.

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

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

The description opens with concrete example queries and explicitly states the core action: resolve a name to canonical identifiers. It distinguishes itself from sibling tools by positioning itself as the 'first step' tool for ID lookups, and the supported types (company, drug) are clearly defined with specific resolution details.

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

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

The description includes an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' This sets clear context for when to invoke the tool. It does not, however, explicitly describe when not to use it or name alternative tools, though the sibling context provides that implicitly. The mention that it replaces 2-3 manual lookups reinforces its efficiency.

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 beyond these: it explains the probing mechanism (calls ai_visibility_check per entity), the ranking behavior, and the return format (score, confidence, signal density). This enriches understanding without contradicting the annotations.

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

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

The description is three sentences long and every sentence earns its place: the first states the core purpose, the second explains the method and outputs, and the third gives a concrete use case. It is front-loaded and contains zero redundant or filler content.

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

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

Despite having no output schema, the description clearly specifies what the tool returns (a ranked list with score, confidence, signal density). It also covers the operational flow (probing with ai_visibility_check), the array sizing (2-8 entities), and the first-entity-as-subject convention. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the schema descriptions are already detailed. The tool description adds minimal additional parameter meaning—it reinforces that entities are brand/business names and that the first is the subject, but this is already present in the schema's entity description. The description does not introduce new format or syntax constraints.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities), and distinguishes itself from the sibling tool ai_visibility_check by explicitly addressing multi-entity comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a realistic example question. It also mentions that it probes each entity with ai_visibility_check, implying that single-entity checks should use that tool directly. However, it does not explicitly state when NOT to use this tool, leaving some room for inference rather than direct 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 adds significant behavioral details beyond the annotations: it reveals the tool makes a composite call across external services, returns a specific summary block with fields, includes failure handling ('sources_failed' on timeout), and notes the 5-30s latency for bundlephobia's first measurement. It also states the NPM-only limitation in v1.

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 fairly long but each sentence earns its place: first defines the composite action, second gives usage triggers, third lists the output, fourth states the ecosystem limitation, and fifth explains partial failures. It is front-loaded with the core purpose and structured logically, though could be slightly trimmed.

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 listing the exact return fields (summary block, per-advisory detail, links, alternative versions). It also covers edge cases like partial failures, timing, and ecosystem scope, making it 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?

The input schema already provides full descriptions for both parameters (package and version), and schema coverage is 100%. The description adds minimal additional parameter-specific meaning beyond what the schema provides, warranting the baseline score of 3.

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

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

The description clearly defines the tool as a composite 'should I add this npm package' check, specifying it fans out to deps.dev and bundlephobia. It uses a specific verb and resource, and distinguishes itself from siblings by being the only tool focused on npm dependency evaluation.

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: 'whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion by noting that non-NPM ecosystems should use deps.dev:version directly, guiding the user away from this tool for those cases.

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

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

Annotations already declare read-only/idempotent behavior, but the description goes further by revealing exact mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation flag, and return contents (offsets, similarity scores). This substantially exceeds the annotation baseline.

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

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

The description is front-loaded with the core action and use case, and every subsequent clause adds operational detail. It is somewhat long, but all information (algorithm, limits, pairing) is relevant to correct invocation rather than padding.

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 directly states what the caller receives: top-N passages with character offsets and similarity scores. It also covers input limits and truncation behavior, making it sufficient for an autonomous agent to invoke the tool correctly.

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

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

The input schema already documents all three parameters with 100% coverage. The description adds concrete usage context—examples of appropriate text (SEC 10-K body) and query phrasing—that enriches comprehension without needing to restate schema details.

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

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

The description opens with a specific verb phrase, 'Semantic search INSIDE a fetched record,' and clearly defines inputs and outputs. It distinguishes itself from the sibling ask_pipeworx_grounded by explaining the intended pairing, making its unique role unambiguous.

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

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

The description provides an explicit trigger: 'Use when the record is too big to cram into the prompt' and explains the context-saving benefit. It names a companion tool (ask_pipeworx_grounded) and contrasts grounding over relevant passages vs. the whole document, though it does not state explicit non-use cases.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: the tool returns label chains, indicates folder vs table, searches English labels while path ids are Estonian slugs, and explains the optional auto-fetch behavior of fetch_latest. 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 information-dense but every sentence adds value: purpose, examples, return details, workflow guidance, and language quirk. It is front-loaded with the core purpose and logically structured, with no superfluous text.

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

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

Given no output schema, the description thoroughly explains what the tool returns (path, label chain, folder/table indicator) and how to use it in a broader workflow. It also covers edge concerns like language mismatches and optional parameters, making it 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing concrete query examples, clarifying the meaning of 'path' with Estonian slug examples, and explaining the fetch_latest behavior in context ('what is the current X in Estonia'). This enhances parameter understanding beyond bare schema descriptions.

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

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

The description clearly states the tool's function: 'Search Statistics Estonia (Statistikaamet) for ESTONIA official statistics tables by plain-English keyword'. It includes specific verbs and resources, and distinguishes itself from siblings by explicitly positioning it as the starting point and directing users to table_meta and query_table for subsequent steps.

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: 'START HERE for any question about Estonian data.' It also explains when to use fetch_latest (for actual figures) versus when to hand the path to table_meta/query_table. This directly addresses alternatives and workflows.

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

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

Annotations already cover read-only and safety, so the description adds context beyond that: items are type 'l' or 't', ids end in .px, and browsing is 'one level at a time.' This gives a partial sense of the return structure, though no output schema exists. No annotation contradiction.

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

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

Two sentences, front-loaded with the tool's purpose and then adding usage guidance. No redundant words, 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 browse tool, the description covers the core behavior, return item types, and workflow integration with sibling tools. It adequately fills the gap left by the absent output schema and makes the tool usable in a larger context.

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

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

The schema description for the single parameter 'path' is already detailed (sub-path under /stat/, default empty, example). The description only reinforces the use of a path, so it adds no new meaning beyond the schema. Baseline 3 applies for high schema coverage.

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

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

The description clearly states the tool 'browse[s] the subject tree of available tables' with a specific verb and resource. It distinguishes itself from the sibling stat_ee_find_table by noting that this tool is for browsing a known path while the sibling handles English questions. This makes the purpose unambiguous.

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

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

It explicitly says when to use this tool: 'Handy for listing everything under a path you already know' and provides an alternative ('use stat_ee_find_table'). It also gives follow-up steps with table_meta + query_table, so usage is well-defined.

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

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

The description adds substantial behavioral detail beyond annotations: requires OAuth, returns subscription id, supports specific types with examples, email/SMS/webhook delivery nuances (verification, rate caps, webhook auto-disable, signing secret). No contradiction with annotations; it enriches them.

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

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

The description is dense but well-structured: purpose first, then requirements, types, and delivery channels. Every sentence carries essential information for a complex tool with five subscription types and three delivery options. 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?

The description covers all necessary aspects: return value, auth prerequisites, all supported types with concrete examples, delivery channels (always-on feed plus optional email/SMS/webhook), and critical limitations (phone verification, 10/day cap, webhook auto-disable). With no output schema, it sufficiently explains what to expect.

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

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

Schema coverage is 100%, but the description goes beyond it by explaining type-specific params (e.g., items:["5.02"] = officer change, topic:"fed" for polymarket), delivery channel requirements (verified phone, 10/day cap), and webhook signing details. This adds meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (create) and resource (subscription), and distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description gives clear context for when to use the tool (creating monitoring subscriptions) and includes important prerequisites (Pipeworx OAuth account). It does not explicitly name alternatives or state when not to use, but the context is strong enough for an agent to differentiate from list/unsubscribe tools.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description goes beyond by detailing the category-bucketed output format with tool and argument shapes, the live catalog source, and the topic-focusing behavior—all valuable behavioral transparency.

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

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

While long, every sentence earns its place: the opening example queries help recognition, then the purpose, output, call pattern, and usage context are each addressed in sequence with no filler. It is efficiently structured and front-loaded with the most important facts.

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

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

The description is fully sufficient for this simple tool: it explains what is returned (bucketed example questions with tool+argument shapes), the full-spread vs focused behavior, and when to use it. No output schema exists, but the return value description is clear enough.

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

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

With 100% schema coverage for the single `topic` parameter, the schema already lists all allowed values and the omit behavior. The description adds only redundant examples (finance, pharma, betting), so it does not materially enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what to ask Pipeworx. It uses specific verbs like 'suggest' and 'returns example questions', and distinguishes it from operational tools like ask_pipeworx by positioning it as the discovery layer.

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 directs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to leverage topic for focused results. It also references meta-tools (ask_pipeworx, entity_profile, compare_entities) as alternatives for specific queries, providing clear when-to-use context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no new behavioral context beyond its purpose (e.g., no details about response format, auth, or side effects), but it does not contradict the annotations. Given the annotations cover the safety profile, this is adequate but minimal.

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

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

The description is two short sentences with no filler. The first sentence states what the tool returns, and the second explains how to use it. Every word earns its place, and the structure is front-loaded and easy to scan.

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

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

For a simple tool with one parameter and no output schema, the description is complete enough: it explains what the tool provides (dimensions, valid values) and how it should be used (to build a filtered query_table call). It does not describe the exact response structure, but that is not necessary given the tool's simplicity and the context signals.

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 the single 'path' parameter, including an example. The description adds a hint that the path refers to a Statistics Estonia table and that the result is used for filtering, but it does not add significant new meaning beyond the schema. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly identifies the tool as returning the table definition (dimensions, valid values) for a Statistics Estonia table, which is distinct from siblings like query_table (which queries data) and stat_ee_find_table (which finds tables). The verb is implied (get/retrieve) but the resource and content are specific.

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

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

The description explicitly states 'Use these to build a filtered query_table call', which tells the agent when to use this tool (before querying a table to get filter dimensions). It does not explicitly list when not to use it, but the specific use case is clear and ties directly to a sibling tool.

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

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

The description adds valuable behavior beyond annotations: 'Ownership is enforced — you can only cancel your own subscriptions' and 'The row is deactivated (not deleted)' are not present in the annotations. It explains the side effect on historical data, which is helpful for the agent.

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 with no filler. The primary action is front-loaded, and the second sentence efficiently conveys constraints and behavioral nuance. Every word earns its place.

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

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

For a single-parameter mutation tool with no output schema and no nested objects, the description covers the action, ownership constraint, and the deactivation effect. It does not describe return values or error behavior, but the simplicity of the tool and existing annotations make this acceptable.

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

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

Schema coverage is 100% for the single 'id' parameter with a clear description. The tool description adds the ownership constraint ('only cancel your own'), which is not in the schema, giving additional semantic meaning about what ids are valid.

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 starts with a clear verb+resource: 'Cancel a subscription by id.' It explicitly distinguishes from sibling tools by noting the deactivation behavior ('not deleted') and ownership enforcement, making its purpose unambiguous.

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

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

The description clearly implies when to use this tool (to cancel a subscription) and provides important context: ownership is enforced, and historical events remain available via recent_alerts. It does not explicitly list when-not-to-use or name alternatives, but the context is sufficiently 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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by disclosing the internal two-path mechanism, the possible verdicts, the special meaning of could_not_verify (not evidence) versus unsupported, and the pipeworx:// citation format. It does not contradict any annotation; it enriches the behavioral contract.

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 each section earns its place: example phrasings, explicit usage criterion, path routing, verdict list, and a critical caller-facing caveat. It is well-structured with a clear flow and front-loaded with natural-language triggers. Slightly 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?

Despite having no output schema, the description discloses all relevant return semantics: verdict vocabulary, actual value with citation, reasoning, and explicit handling of failure modes (could_not_verify vs unsupported). It covers when and how to invoke, what to expect, and how to interpret edge cases, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% for both parameters, with detailed descriptions and examples. The description reinforces the tolerance override context (e.g., "set 1–2 for hallucination detection") but does not add meaning beyond what the schema already provides. A baseline of 3 is appropriate since the schema carries the explanatory load.

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

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

The description precisely states the tool verifies natural-language factual claims against authoritative sources, with specific verb phrases like "fact check" and "verify the claim that". It clearly distinguishes from likely sibling tools by framing it as a single-call replacement for NL parsing, entity resolution, lookup, and comparison, which separates it from generic ask tools and research tools.

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

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

The description explicitly states "Use whenever the agent needs to check whether something a user said is factually correct." It also provides clear routing guidance: company-financial claims take the SEC EDGAR/XBRL fast path, while all other claims fall through to the grounded pipeline. The "IMPORTANT for callers" note about could_not_verify vs unsupported adds critical usage semantics.

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