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?

While annotations already declare readOnly, openWorld, and idempotent hints, the description adds substantial behavioral context beyond those annotations, such as the routing mechanism across thousands of sources, filling arguments, returning pipeworx:// citation URIs, and being fast enough for every tier. It also clarifies that breaking-news queries are handled internally, which is not indicated by annotations.

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

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

The description is long but front-loaded with the key preference directive and uses structured lists and examples efficiently. Every sentence contributes to usage guidance or sibling differentiation, so the length is justified for such a broad default tool, though it could be slightly more condensed 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?

Despite lacking an output schema, the description conveys that the tool returns structured answers with stable citation URIs, covers a wide range of factual domains, and provides examples. It also explains its role as the default entry point and when to use alternatives, making it comprehensive for a complex meta-tool.

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

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

The input schema already fully documents the 'question' parameter with five aliases at 100% coverage. The description includes example queries but does not add substantive semantic details about parameter values or formatting, so it does not exceed the schema's baseline. The examples are helpful but not essential.

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: routing questions to one of 5,366 tools across 1,396 verified sources, filling arguments, and returning structured answers with citation URIs. It explicitly distinguishes itself from ask_pipeworx_grounded and deep_research by naming specific use cases for each sibling.

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

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

Provides explicit when-to-use guidance, including 'PREFER OVER WEB SEARCH' for specific data domains, trigger phrases like 'look up', 'find', 'how much', and concrete examples. It also gives clear advice on stepping up to more specialized tools (ask_pipeworx_grounded, deep_research) for different scenarios, making it highly actionable.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that this is an experimental router with live candidate changes, that it has no fallback ('Falls back to nothing'), and that it is a full working router. It also notes the comparison against the stable router for merge decisions, adding meaningful 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?

Four sentences supply dense, useful details (5,366 tools, exact date, no fallback) without redundancy. The structure front-loads the beta identity, then explains current status and usage. Slightly longer than strictly necessary but each 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?

Given the tool's complexity, the description covers identity, relationship to the stable router, current candidate status, usage instruction, and behavioral caveat (no fallback). Response shape is defined by reference to ask_pipeworx, and with strong annotations and full schema coverage, nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'same arguments' but does not add specific parameter semantics beyond what the schema already documents. The aliases for the question field are already fully described in the schema.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,366 tools, arguments, and response shape. It distinguishes itself by enabling candidate routing improvements when under test, and by comparing against the stable router, setting it apart from the sibling ask_pipeworx and ask_pipeworx_grounded.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. It also explains the current state (no active candidate) so the agent knows when it matches ask_pipeworx exactly, and implicitly recommends ask_pipeworx for stable 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?

Annotations already provide readOnly/idempotent/destructive hints; the description goes further by disclosing refusal reasons (not_in_source, no_tool_match, etc.), the guarantee of using only tool result content, and the extra LLM call cost. This adds significant behavioral detail beyond annotations.

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

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

Every sentence earns its place: purpose, routing process, return format, refusal details, use cases, and cost tradeoff. It is front-loaded with the core purpose and structured logically without redundant repetition.

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

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

Despite no output schema, the description explains both success and refusal response shapes, enumerates all refusal reasons, gives explicit usage scenarios, notes the sibling alternative, and covers cost implications. This is highly complete for an agent to use correctly.

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

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

Schema coverage is 100% (the question parameter and its aliases are fully documented). The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with ask_pipeworx by describing the extra extraction step. The verb+resource is specific and the mechanism distinguishes it from 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?

It explicitly tells when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and when not to: 'prefer ask_pipeworx for casual lookups.' It names the alternative (ask_pipeworx) and provides context (cost of one extra LLM call).

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds rich behavioral context: it never invents answers (explicit gaps[]), returns contradictions[] for standard/thorough, semantically excerpts long records, and discloses expected latency (15-60s, up to ~90s for thorough). 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 densely packed with high-value information, and front-loads the critical account requirement and core purpose. While not as short as ideal, every sentence adds meaningful detail about behavior, usage, or alternatives, making it appropriately sized for a complex tool.

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

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

Given the tool's complexity, the absence of an output schema, and rich annotations, the description fully covers what the tool returns (findings packet, citations, gaps[], contradictions[]), its limitations, alternatives, and timing. It even explains the hop field and citation_uri, leaving no major contextual gaps.

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

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

Schema description coverage is 100% for both parameters, so baseline is 3. The description's details about depth behaviors (gap recovery, contradiction pass, paid requirement) largely mirror what is already in the schema, adding no significant parameter semantics beyond it.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources' in one call, decomposing questions into facets and routing them to tools in parallel. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and contrasts with ask_pipeworx for single lookups and current-news topics. It also states the account requirement, sign-in URL, and paid tier for depth:"thorough", plus a fallback instruction to use ask_pipeworx if not signed in.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The annotations provide no behavioral hints (all false), so the description carries the burden. It discloses relevant behaviors: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, and that the team reads digests daily with roadmap impact. It doesn't describe the return value, but for a one-way feedback submission this is structurally 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 well under 100 words but each sentence is dense with useful information. It is front-loaded with the core verb and use cases, then flows into constraints (rate limit, quota) and the team's workflow. No filler or redundant phrasing.

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 has only 3 parameters, a nested optional context object, and no output schema, the description fully covers the needed context. It explains the feedback categories, what message content should look like, the target audience (Pipeworx team), and operational limits. The sibling-tool context is clear: no other tool accepts feedback, so this description is complete for agent decision-making.

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 meaningful guidance beyond the schema by telling how to phrase the message ('Describe the issue in terms of Pipeworx tools/packs') and what not to include (end-user's prompt). This directly informs the 'message' parameter, which the schema only describes as plain text. The enum 'type' is also visually reinforced via the use cases.

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

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

The description opens with a specific verb and object ('Tell the Pipeworx team something is broken, missing, or needs to exist'), immediately clarifying the tool's purpose. It clearly distinguishes itself from all sibling tools by being the only feedback/submission channel, and the enumerated use cases (bug, feature, data_gap, praise) remove any ambiguity.

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 the tool with concrete conditions ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog...'), and also provides an exclusion ('don't paste the end-user's prompt'). It mentions rate limits and quota behavior, giving the agent clear decision rules for when to invoke it.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare the operation safe (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so no behavioral safety caveats are needed. The description adds no extra behavioral details such as pagination, rate limits, or response format expectations, beyond what the schema example shows. It doesn't contradict 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 very short: two sentences, no filler. The key verb and object appear in the first four words, and the rest provides the necessary example. Every sentence serves a purpose.

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

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

For a data-fetching tool with two parameters and rich schema examples, the description is largely sufficient. However, there is no output schema and the return format is only seen in the example, not in prose; still, the example covers it. With strong annotations and a clear example, the tool is adequately contextualized.

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

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

Schema coverage is 100% with clear descriptions for both path and body, so the baseline is a 3. The description goes slightly beyond by labeling body as a 'PxWeb query object' and giving a concrete path example, which helps the agent shape correct calls. It doesn't explain the body structure further, but the schema example does.

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 phrase ('Pull data from a ".px" table'), making the tool's purpose immediately clear. While no sibling is explicitly named, it's naturally distinct from table_meta and search_within. The example path reinforces the resource type.

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 this is the tool for fetching data from .px tables but offers no explicit guidance on when to choose it over siblings like table_meta or search_within. There are no stated exclusions or alternative tool mentions. It relies on the agent to infer from the tool title and sibling names.

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?

Given annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds meaningful behavior: it cascades through multiple lookup endpoints internally, returns citation URIs (pipeworx://...), and auto-disambiguates company names. It also clarifies the returned fields per type, which is beyond the 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?

The description is information-dense but well organized: example queries, instruction, supported types with return details, and a closing note on internal cascading. Every sentence adds value; no filler.

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

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

For a 2-param tool with schema covering 100% and rich annotations, the description covers edges: input variants, output types, disambiguation behavior, and rationale. No output schema exists, so the description appropriately explains returns. Context is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the 'value' parameter by giving concrete examples (AAPL, 0000320193, ozempic) and explaining accepted forms, plus clarifies the 'type' enum with contextual behavior (returns different fields for company vs drug). Worth a 4.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It gives explicit verbs ('resolve', 'look up'), examples of queries, and specifies the supported types (company -> CIK/ticker, drug -> RxCUI). This strongly distinguishes it from sibling entity tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', and notes that it replaces 2-3 manual lookups. It lists supported input forms (ticker, CIK, name) and output formats. Though it doesn't name alternative tools, the guidance is concrete about when to apply it.

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, and idempotentHint, so the safety profile is clear. The description adds useful behavioral context: the tree traversal semantics, the distinction between folders and tables, and the id convention ('.px'). This exceeds simple annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the main purpose, and every clause adds value: the type system, id format, and references to sibling tools. No redundant or filler content.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is largely complete. It explains how to navigate, what the entry types mean, and how to proceed with tables. It does not specify the exact response structure, but that is not critical for a navigation tool. Slight gap for not explaining what happens if a path is invalid, but overall adequate.

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 for the single parameter 'path' is 100%, with the description 'Sub-path under /StatFin/ (default empty = root).' The tool description also mentions using ids for drilling, which mirrors schema examples ('khi', 'synt'). No additional parameter meaning is needed beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Navigate the subject tree') and distinguishes between folder entries (type 'l') and table entries (type 't'), with explicit pointers to sibling tools table_meta and query_table for tables. This makes the tool's purpose unambiguous and differentiated from other 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 implies when to use this tool (for exploring the subject hierarchy) and provides guidance for tables: 'type "t" are tables (id ends in ".px", use with table_meta / query_table).' It gives a clear path-parameter example and root default, though it does not explicitly enumerate scenarios where using this tool would be inappropriate.

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?

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is to add context. It discloses that the result contains dimensions and valid values, and it flags a hard prerequisite on the path format. This goes beyond annotations by specifying output content and input constraint.

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

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

The description is two short sentences, front-loads the core purpose ('Table definition'), and includes a concrete example. Every word earns its place.

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

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

With one parameter, a simple metadata return, and thorough annotations, the description covers the essential context. It explains what the tool returns and the required input format. Minor gap: it doesn't describe pagination or error cases, but these are less relevant for a metadata tool.

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

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

The schema already documents the path parameter with an example at 100% coverage, so the baseline is 3. The description adds the explicit requirement that the path must point at a .px table, which is only implied by the schema's file extension example. This extra constraint raises the score to 4.

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

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

The description identifies the tool as returning a table's definition, including dimensions and valid values, which clearly distinguishes it from data-querying siblings like query_table. However, it lacks an explicit verb like 'retrieve' or 'get,' making it slightly less direct. The example path reinforces the intended use.

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 this tool is for metadata lookup rather than data queries, but it does not explicitly name alternatives or state when not to use it. It does provide a clear constraint (path must be a .px table) and an example, which helps the agent select correctly.

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

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

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it discloses the routing logic (SEC EDGAR vs. grounded), the output components (verdict, actual value, citation, reasoning), and the performance claim of replacing 4–6 sequential calls. This goes beyond what annotations provide without contradicting them.

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

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

The description is long, but the initial trigger-phrase list is functional for intent matching. The structure flows from intents to core function to routing to output, all in a few sentences. While some phrases are redundant (e.g., 'confirm or refute' vs. 'true or false'), the overall density of useful information is high, and no sentence is wasted.

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

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

With no output schema, the description takes responsibility for explaining return values, and it does: verdict types, grounded/structured value, pipeworx:// citation, and reasoning. It also covers the two execution paths and parameter behavior. It's not exhaustive (e.g., no error cases or source list), but it's sufficient for an agent to invoke correctly and understand the outcome.

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

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

Schema coverage is 100% with both parameters described. The description adds value by giving concrete examples for the claim parameter and extra guidance for tolerance_pct—specifically the recommendation to set 1–2 for hallucination detection. This exceeds the baseline 3 because it provides practical usage semantics beyond the raw schema.

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

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

The description opens with natural-language trigger phrases and then states the core function: 'natural-language claim verification against authoritative sources.' It clearly identifies the verb (verify), resource (claims), and distinguishes it from sibling research tools by focusing on fact-checking rather than open-ended research. The two-path routing (SEC EDGAR vs. grounded pipeline) further clarifies 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It also differentiates between company-financial claims (SEC EDGAR fast path) and all other claims (grounded pipeline). It doesn't explicitly name alternatives or exclusions, but the context is sufficiently clear for an agent to select this tool over siblings like deep_research or ask_pipeworx.

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