Statfin Fi

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds meaningful behavioral context: the default model (Workers AI free), the ability to probe Anthropic with a BYO key, and direct cost implications. This goes beyond annotations and enriches the agent's understanding of side effects and requirements.

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

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

The description is concise and well-structured: a front-loaded purpose sentence, a second sentence covering defaults and key handling, and a final sentence listing use cases. Each sentence earns its place with no redundancy. It is appropriately sized for the tool's complexity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it routes to the right tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It slightly undersells limitations by saying it returns 'the structured answer' without mentioning any ambiguity-handling behavior, but this is a minor gap.

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 and well-structured: usage preference first, then mechanism, then trigger phrases, examples, and finally alternatives. There is some redundancy ('even if web search could also answer it' appears in spirit in both the trigger section and the 'START HERE' sentence), but each section earns its place and the flow is easy for an agent to parse.

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

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

For a tool with a single required string parameter, no output schema, and rich sibling context, the description is complete: it says what it does, when to prefer it, what kinds of questions work, what happens internally, what the output includes, and when to choose alternatives. Nothing essential 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?

The input schema has 100% coverage for all six properties, all of which are documented as aliases for the natural-language 'question' parameter. The description adds helpful usage examples and trigger phrases, but those are more about when to invoke the tool than about the parameter semantics themselves. Baseline 3 is appropriate since the schema already 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 opens with a clear mandate: prefer this over web search for authoritative structured data, and explicitly routes questions across 5,767 tools to return cited answers. It also names sibling tools like ask_pipeworx_grounded and deep_research, making the differentiation between them and this default tool explicit.

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

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

It gives concrete trigger phrases such as 'what is', 'look up', 'find', 'get the latest', and 'how much', plus real examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It also states when NOT to use it: use ask_pipeworx_grounded for a single grounding answer, and deep_research for broad multi-part questions, with a special note on breaking-news routing.

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 meaningful behavioral context beyond the annotations: it is a beta duplicate of ask_pipeworx, no candidate is currently active, and it behaves identically to the stable version today. It does not contradict the readOnlyHint/idempotentHint annotations. Minor gap: it doesn't state whether answers may be less reliable or how often the routing changes.

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 packs a lot of context into a compact paragraph and front-loads the key fact that it is a beta of ask_pipeworx. Some redundancy exists (repeatedly noting it behaves identically), but overall it is efficient and readable.

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 and simple six-alias parameters, the description covers what matters: current behavior, relation to the sibling, and the experimental purpose. There are no nested objects, enums, or complex return shapes requiring more detail.

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 the main question parameter and aliases fully documented in the schema. The description adds no parameter-specific detail beyond saying the same arguments as ask_pipeworx are accepted, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, a universal router, and explains it has the same tools and arguments. However, it doesn't fully distinguish its unique purpose beyond being an experimental edge with no currently active candidate — some ambiguity remains about what differentiates it from the stable ask_pipeworx right now.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. It also clarifies that it is a full working router, not a fallback/nonfunctional stub, which prevents mis-selection.

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

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

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing the internal routing (5,767 tools across 1506 sources), the strict extraction rule (only what the tool result contains), the exact success and refusal return shapes, enumerated refusal_reason values, and the extra LLM call cost. No contradiction with the annotations — readOnly, openWorld, idempotent, and non-destructive are all consistent with the described read-and-extract flow.

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 (~110 words) but well-organized: purpose is front-loaded, followed by mechanism, return format, refusal behavior, usage scope, and cost tradeoff. Each sentence earns its place given there is no output schema to carry the return-format documentation, though it is slightly longer than strictly necessary.

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

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

Complete for a tool of this complexity: purpose, routing, success/refusal return contracts, enumerated failure modes, usage constraints, and cost tradeoff are all present. Because no output schema exists, the detailed return-format documentation in the description is essential and fully delivered.

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

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

Schema description coverage is 100%, so the schema already documents the sole meaningful parameter 'question' and its five aliases. The description adds no parameter-level detail, but with full schema coverage the baseline 3 applies and no compensation is required.

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 verb and resource: 'Hallucination-resistant answer mode' that routes through Pipeworx and extracts grounded answers. It explicitly differentiates from its sibling ask_pipeworx by naming the same routing but a different extraction behavior, so an agent can distinguish them without opening the schema.

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

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

Provides explicit when-to-use guidance with concrete high-stakes domains ('financial verdicts, legal claims, medical lookups, public statements'), and explicit when-not-to-use guidance ('prefer ask_pipeworx for casual lookups') with the cost reason stated. No inference required.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: account requirements, paid tier for 'thorough', parallel decomposition into facets, output shape (findings with evidence/confidence/source/fetched_at/citation/gaps[]), the gap-recovery hop, contradictions[] scan, non-invented findings, semantic excerpting rather than head-truncation, and expected latency. This is a rich behavioral disclosure that goes far beyond the annotations. No contradiction with annotations exists — the tool is read-only and idempotent, and the description never claims mutations.

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 earns its length. It front-loads the most decision-relevant constraints (account required, signup link, paid tier) and the main capability, then adds usage guidance and behavioral details. It is somewhat long and could be tightened, but every sentence adds value for selection or invocation correctness. Minor structural friction: the depth details are split between the intro and the schema, and some parentheticals are long. Still, for a tool of this complexity, the length is justified.

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

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

The tool has no output schema, so the description carries the burden of explaining return values. It does so thoroughly: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[] array, contradictions[] for standard/thorough, hop field, citation_uri. It also covers latency expectations, input expectations, account prerequisites, and fallback routing to siblings. For a complex research tool with only two parameters, this is complete — an agent has everything needed to select, invoke, and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by defining the three depths in practical terms ('quick=3 single hop', 'standard' adds gap recovery, 'thorough' is paid and adds iterative lead-chasing), tying them to the annotations about open-world research and the research packet contents. It also describes what kind of question the `question` parameter should contain ('broad/multi-part is fine — decomposition is the point'), which goes beyond the schema's natural-language description. This genuinely helps an agent choose parameter values.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx and ask_pipeworx_grounded. It also clearly states the intended use case: 'Best for broad/multi-part questions over structured data.'

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 and when-not-to-use guidance. It states 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' It also contrasts with ask_pipeworx for breaking/current news topics. It names alternatives and the conditions that select them.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavior: it returns top-N tools with full schemas and examples, ready to call directly with no second lookup. This explains output format and usability beyond the annotations.

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

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

The description is relatively long but every part serves a purpose: purpose, domain list, return behavior, and usage guidance. The opening sentence is direct, and the domain list is compact. No filler or redundancy, though it could be slightly shorter without losing value.

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

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

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

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

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

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

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

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

The description clearly states the tool's purpose with a specific verb ('Find tools') and resource ('by describing the data or task'). It also lists comprehensive domains and distinguishes itself from siblings by stating 'Call this FIRST' and returning the option set, making it unique among sibling tools.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and even hints at excluding cases where a specific tool is already known.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses important behaviors: parallel fan-out across many sources, soft-fail on USPTO sunset, empty sections meaning real no-data rather than a bug, and resolved:false with a notes line for private companies. It even explains expected empties for fda_products, which prevents false failure interpretations. 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 it is front-loaded with examples and a one-line core purpose, then organized by return sections with necessary caveats. Almost every clause adds required behavioral or semantic detail. It could be restructured into bullets for easier scanning, but it earns its length.

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

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

With no output schema, the description bears the burden of explaining return values, and it does so thoroughly: lists cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, plus sources_used/sources_failed. It covers input formats, failure semantics, and edge cases like private companies. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable meaning beyond the schema: that 'type' values are interchangeable, that 'value' can be a ticker, CIK, or name, how name resolution works via SEC EDGAR, and what happens for private companies. This extra contextual mapping elevates the score.

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

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

The description opens with concrete user phrasings and the core statement 'full cross-source profile of a US public company in ONE parallel call', naming the exact verb, resource, and scope. It distinguishes itself from chaining single-pack lookups and from siblings like resolve_entity by emphasizing the holistic, cross-source profile 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', which is clear when-to-use guidance. It also covers accepted input shapes (ticker, CIK, name) and the private-company fallback. However, it doesn't explicitly state when not to use it versus siblings like compare_entities or deep_research, leaving some ambiguity at the boundary.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Description uses specific verb 'Delete' plus resource 'previously stored memory by key', clearly distinguishing from siblings like remember (store) and recall (retrieve).

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with remember and recall, providing workflow context.

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

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

The description discloses the end-to-end process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds value beyond the annotations (readOnly, idempotent, openWorld) by explaining internal behavior and output format. No contradictions with annotations.

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

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

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

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

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

Given the tool's simplicity (2 params, full schema coverage, no output schema) and rich annotations, the description provides sufficient context. It explains the output format ('single text blob', 'standard llms.txt markdown'), making it complete for an agent to select and use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, such as mentioning 'any URL' and the extraction of key links, but does not elaborate on max_links behavior. This matches the baseline for well-documented parameters.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with a specific verb ('generate') and resource ('llms.txt'). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility scanning rather than file generation.

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

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

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

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and emphasizing 'caller's' subscriptions, providing scoping context beyond the annotations.

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

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

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

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

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

For a simple list tool with one optional parameter, the description fully covers return fields, usage context, and relationship to sibling tools. The lack of an output schema is compensated by explicitly listing return fields, making the tool complete for agent invocation.

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

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

Schema coverage is 100% with a single well-documented boolean parameter (include_inactive). The description's mention of 'active subscriptions' implicitly aligns with the default false, but it does not add new semantic details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

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

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

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

The description explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly references sibling tools (subscribe/unsubscribe) and provides clear usage context.

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

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

With all annotations false, the description carries the full burden and excels. It discloses the rate limit (5 per identifier per day), that it is free and does not count against tool-call quota, and details the claim_token behavior (returned when filing without an account, usable later to check status). It also notes that the team reads digests daily—important for expectation-setting. No contradiction with annotations.

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

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

The description is longer than average but every sentence serves a distinct purpose: purpose, usage categories, exclusion clause, token flow, rate limit, and cost. It is front-loaded with the main action and progressively adds important context. It could be slightly tightened, but the structure is logical and free of fluff.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is compact and well-structured: a lead summary, a bullet-style 'Useful for' list, then a technical note. No wasted words.

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

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

Without an output schema, the description compensates by listing return items (top tools, top packs, total call volume) and even the tuple format '(pack, tool, count)'. Combined with annotations and low parameter complexity, it is highly complete.

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

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

The sole parameter 'window' is fully described in the schema with enum values and semantics. The tool description mentions the windows but does not add new meaning, so baseline 3 applies.

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

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

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

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent demand. It does not mention exclusions or alternative tools, so it lacks the full 5 but gives clear context.

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

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

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

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

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

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

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

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

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

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

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

While the schema already has 100% coverage with descriptions for both `event` and `topic`, the tool description adds meaningful depth: concrete slug examples, clarification that full URLs are accepted, and a detailed explanation of how each mode behaves. This is a clear enhancement over the schema alone.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (default trending scan, event-specific, topic cross-event), making it easy to understand what the tool does and how it differs from siblings.

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

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

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

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

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

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

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

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

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

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

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

With 9 parameters, no output schema, and no nested objects, the description carries the full burden of explaining the response. It does so comprehensively: top-level response layout (by_segment, fed_candidates/fed_note, _diagnostics), what each segment contains, why segments might be empty, and caching behavior. It is complete for a tool of this complexity.

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

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

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

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

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

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

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

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

The description gives strong context for when to use the tool (discovering betting opportunities, scanning top markets) and operational guidance via knob explanations (e.g., 'Set to 2 to require tight books'). However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it state when not to use it. This is clear context without exclusions, so a 4 is appropriate.

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

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

Annotations declare read-only/idempotent, and the description adds substantial behavioral detail: snapshot TTL limits, cache-miss gap semantics, daily-close vs intraday data, response structure, and signed edge_pp_net meaning. It also explains the response fields in detail, going far beyond the structured hints.

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

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

Long but dense: each section (Args, RESPONSE, LIMITS) is clearly labeled and every sentence contributes a distinct fact. The format is front-loaded with the core question, and the structure makes the length appropriate for the complexity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond these by disclosing behavior such as 'walks the ladder', the returned fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and the risk of 'forced_directional_risk' and 'thin_legs'. It also warns that 'partial basket fills convert an arb into an unhedged directional position'—a crucial behavioral consequence not captured by the annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With readOnlyHint, idempotentHint, and openWorldHint already present, the description adds substantial behavioral context on top: compatibility_warning and compatibility_codes may be non-empty even when pairs are returned, temporal_alignment null means unknown rather than aligned, fees are gross not net, and unclassified legs are never paired. These details go far beyond the annotations and tell an agent exactly what to expect from the response. There is no contradiction with the annotations.

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

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

The description is long, but nearly every sentence carries a distinct, relevant fact: mode behavior, safety fields, flag meanings, fee treatment, and skipped-leg semantics. It is front-loaded with the core purpose and then proceeds into details. The main weakness is that it is a dense wall of text rather than structured bullets, which makes it slightly harder for an agent to parse, but not at the cost of completeness.

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, three parameters, and no output schema, the description is unusually complete. It documents the return fields it promises (leg-by-leg prices, top_spreads_pp, spread.skipped_unclassified, spread.low_confidence_pairs, temporal_alignment, fees_note), explains the compatibility codes, and even clarifies null semantics. An agent has enough detail to call the tool correctly and interpret its results in either mode.

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, but the description adds meaningful extra semantics: it explains that 'topic' selects one of 10 pre-mapped shortcuts, that explicit ticker/slug create custom pairings, and that both modes share identical matching and disclosure behavior. This goes beyond the schema's one-line descriptions, particularly in clarifying the interaction between the modes and the response caveats.

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

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

The description states a clear purpose: it returns the cross-venue spread between Kalshi and Polymarket for the same resolving question, with two input modes. It does not explicitly name sibling tools, but the 'cross-venue spread' framing and the emphasis on the same outcome distinguish it from related tools like polymarket_arbitrage or polymarket_edges. The purpose is specific enough for an agent to understand what it computes, though it could more directly state when this tool is preferred over those 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?

The description gives clear operational guidance: it explains the two modes (pre-mapped topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug), notes that both modes run the same matcher, and warns that 'pre-mapped ≠ tradeable.' It provides context about when the user should verify alignment themselves, but it does not explicitly state when to use this tool instead of an alternative sibling, 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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the upstream path rewrite, automatic resolution of labels against table metadata, defaulting to latest year and totals for unnamed dimensions, and the `selection_resolved` feedback channel. No contradiction with annotations — the description reinforces the read-only, non-destructive nature.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of omitting the key to list all keys. No contradictions with annotations, and it avoids repeating what annotations already state.

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

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

The description is two to three sentences, front-loaded with the primary function, and every sentence earns its place. It includes purpose, usage guidance, scoping, and pairing with related tools without excessive verbosity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states that polling works fine, which is useful implementation guidance, and notes the feed is also available via direct HTTP GET for scripts/dashboards, giving an alternative path. It does not explicitly name alternative tools or when not to use it, but the context strongly implies its niche among siblings.

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

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

Beyond the readOnly/idempotent hints, the description discloses source fan-out (SEC, GDELT/GNews, USPTO), fallback logic (GNews on rate limit/5xx), future failure mode (PatentsView sunset), and return structure. This is rich behavioral context that the annotations do not capture.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Provides explicit when-to-use signals through natural language examples and directly names entity_profile as the alternative for static profiles. This gives the agent clear decision boundaries, exceeding simple 'use when' guidance.

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

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

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

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

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

The description is concise yet comprehensive, with each sentence adding value: purpose, usage, storage details, and companion tools. It is front-loaded with the main action and efficiently structured without redundancy.

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

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

For a simple key-value store with no output schema, the description covers essential aspects: what to store, when to use, persistence rules, and relationships to other tools. It could mention return value or error scenarios, but for this low-complexity tool, the existing information is sufficient.

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

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

The input schema already covers both parameters with examples (key and value). The description does not add new parameter-specific semantics, but it contextualizes them through usage examples. With 100% schema coverage, this is a solid baseline; no additional parameter info is needed.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb (save) and resource (data). It distinguishes itself from siblings by explicitly pairing with recall and forget, making its role in the memory system unambiguous.

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

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

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

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses several important behaviors: graceful degradation when enrichment sources are unavailable, ambiguous matches returning `figi_candidates` instead of asserting a single answer, explicit reporting of unresolved identifiers under `unresolved`, and the internal cascading across multiple endpoints. These details go well beyond what annotations or schema provide.

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

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

The description is long but densely packed with useful information; no sentence is filler. It is front-loaded with query examples and the core directive. However, it could be better structured (e.g., with paragraphs or bullet points) to improve scannability. Given the tool's complexity, the length is justified but slightly exceeds what is strictly '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?

Despite having no output schema, the description thoroughly explains what the tool returns (CIK, ticker, LEI, FIGI, RxCUI, and behavior like `figi_candidates` and `unresolved`). It also details input handling, degradation, and supported types. For a tool with two parameters and rich behavior, 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?

Although the schema already documents both parameters (100% coverage), the description adds substantial meaning: it explains the 'type' enum semantics and gives detailed guidance for 'value', including examples, the instruction to pass the entity name only, and a critical caveat for bonds about matching instrument names rather than full noun phrases. This clarifies nuances that the schema alone cannot convey.

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

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

The description states a specific verb ('resolve') and resource ('a user-spoken NAME to the canonical/official identifiers'), and immediately differentiates itself from sibling tools by naming the exact identifier types it returns. The examples ('What's the ticker for…') make the purpose unmistakable, and it clearly distinguishes from entity_profile by focusing on ID resolution rather than profiling.

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 'Use FIRST whenever you have a name but need an ID', giving a direct usage trigger. It also enumerates the types of inputs accepted (ticker, CIK, ISIN, company name, drug name), which tells an agent when this tool is appropriate. However, it does not state when NOT to use it or provide alternatives (e.g., when a user wants a full profile rather than an ID), so it lacks explicit exclusionary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: that it 'probes each entity with ai_visibility_check' (indicating external AI API calls) and that it returns a ranked list with score/confidence/signal density. This goes beyond the annotations and clarifies the external, idempotent read behavior without contradiction.

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

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

The description is three sentences: it states the core action, a practical use-case with an example, and the return value. Every sentence earns its place, and the most critical information is front-loaded. No fluff or redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Despite readOnlyHint already marking this as safe, the description adds valuable behavioral context: it fans out to external services, handles partial failures gracefully, and warns that the first bundlephobia measurement can take 5-30s with sources_failed as the failure signal. This goes well beyond the annotations.

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

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

The description is moderately long but every sentence carries functional value: composite purpose, use cases, output fields, ecosystem limits, and failure behavior. It is well structured and front-loaded, though slightly dense.

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

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

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

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

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

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

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

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

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

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also names an alternative for non-NPM ecosystems (deps.dev:version directly), providing clear boundaries and exclusions.

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

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

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

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

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

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

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

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

With no output schema, the description compensates by explaining return values (top-N passages, offsets, similarity scores). It also covers usage context, pairing with another tool, and a hard limit (200K chars). Missing minor details like error behavior or auth, but these are not critical for this read-only, self-contained tool.

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

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

Schema description coverage is 100%, so the structured data already documents all three parameters well. The description adds some context (e.g., 'text you already pulled', example queries) and references the truncation cap, but it does not significantly enhance parameter understanding beyond the schema. It meets the baseline but does not excel.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The schema already covers the 'path' parameter with a description and examples (coverage 100%). The tool description enriches it by explaining the meaning of folder IDs (e.g., 'vkour' for education) and how they are used to drill in, adding context beyond the schema's basic definition. This is a meaningful enhancement over the baseline of 3.

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

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

The description explicitly states the tool browses the StatFin subject tree, lists the topics covered, and distinguishes folders (type 'l') from tables (type 't'). It also differentiates itself from siblings by explaining that table IDs are passed to table_meta and query_table, making it clear this tool is for discovery, not querying.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The tool is simple (one optional parameter, no output schema), and the description covers purpose, return contents, parameter semantics, and invocation timing. For an onboarding tool, this is complete: an agent can decide whether to use it and how to call it correctly.

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

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

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

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

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

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

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the two invocation modes—no arguments for the full spread, or with a `topic` to focus—and gives concrete examples of topic values.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description explains that the tool returns all valid values and that dimension codes are native Finnish and cannot be derived from English titles. This gives agents a clear expectation of the output's nature and the necessity of the path parameter, adding significant behavioral context.

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

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

The description is longer than typical but each sentence adds necessary context (purpose, usage timing, code examples, path format). The purpose is front-loaded, and the detail is warranted given the non-obvious Finnish codes. It is somewhat verbose but not wasteful.

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

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

With only one parameter, no output schema, and rich annotations, the description fully covers the tool's functionality, including examples and important cultural background. An agent can call it correctly without needing further specification.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is two sentences long, immediately states the primary action, and packs the ownership and deactivation details into the second sentence without wasted words. It is perfectly front-loaded and concise.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no output schema, the description thoroughly explains return values (verdict types, actual value, citation, reasoning) and edge cases (could_not_verify vs. unsupported). It also covers the two processing paths and performance benefit, making it complete for an agent to invoke and interpret results even without a schema.

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

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

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

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

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

The description clearly identifies the tool as claim verification with verbs like 'fact check' and 'verify the claim that', and distinguishes it from siblings by scoping to factual claim validation with a verdict. It also differentiates the SEC/XBRL fast path for financial claims versus a grounded pipeline for other claims, which sets it apart from general ask/query tools.

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

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

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

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