Ssb No

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

Annotations already mark it read-only and non-destructive. The description adds meaningful context: default model is free, passing _apiKey for Anthropic means you pay Anthropic directly, and it returns a per-model plus combined structure. This goes beyond 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 four sentences, front-loaded with the primary action, then defaults/cost, then return shape and use cases. Every sentence earns its place with no redundancy or fluff.

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

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

Given no output schema, the description does a good job summarizing the return shape (per-model {score, confidence, signals, raw_response} + combined view) and use cases. It could elaborate on what 'signals' or 'combined view' means, but annotations and schema already cover safety and parameters, so the description is sufficiently 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%, so baseline is 3. The description adds value by explaining the default model behavior and the cost implications of _apiKey (BYO key, direct payment to Anthropic), which is not in the schema. This extra semantic nuance justifies 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 opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx (which presumably answers questions) and scan_competitor_ai_presence (which focuses on competitors). The outcome (score per model) is explicit.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly state when NOT to use it or name alternative tools, so it stops short of full exclusion 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 mark the tool as read-only, idempotent, and open-world; the description goes beyond this by revealing internal routing behavior, the nature of citations (pipeworx:// URIs), performance characteristics ('one fast call', 'works on every tier'), and that it can cover live news. There is no contradiction, and the added context about citation URIs helps set 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 lengthy but well-organized: it starts with an attention-grabbing 'PREFER OVER WEB SEARCH', then lists content areas, provides example questions, explains when to use alternatives, and ends with a breaking-news note. Every sentence adds value, though it could be tightened without losing its usefulness.

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 massive scope (5,366 tools, 1,396 sources) and the absence of an output schema, the description does a good job of framing the input (natural language questions), the processing (routing and filling arguments), and the output format (structured answer with citation URIs). It does not specify exact response fields or error behavior, but that is a minor gap for such a general-purpose 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 has 100% parameter description coverage for the 'question' parameter and aliases, so the description adds little beyond what the schema already makes clear. The examples in the description demonstrate usage but do not introduce new parameter meaning or constraints. This meets the baseline for full schema coverage.

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

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

The description explicitly states the tool's function: routing questions to one of 5,366 tools across 1,396 verified sources and returning a structured answer with citations. It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternative options, and positions itself as the 'default entry point' and 'right one' for most factual questions.

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

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

Provides explicit 'when to use' guidance with a long list of example domains and query triggers ('what is', 'look up', 'find', etc.), and also gives 'when to step up' instructions directing users to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. It even addresses the news/breaking-news edge case, showing clear differentiation.

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?

Adds valuable context beyond the annotations: it clarifies it is a full working router ('falls back to nothing'), that it is currently identical to ask_pipeworx, and that results are compared against the stable router to decide merges. These details about the beta nature and current state are not provided by the annotations and help set expectations accurately.

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

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

The description is three sentences, each conveying essential information: beta status and identity, current state, and usage guidance. It is well-structured and front-loaded, though slightly dense with many details; still, 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?

For a router tool, the description explains its purpose, how it relates to the stable version, its current operational status, and how to use it. It also reassures that it is a full router, not a fallback. Since there is no output schema, mentioning the same response shape as ask_pipeworx sufficiently covers return behavior. The description is complete enough for an agent to confidently invoke it.

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

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

The schema already covers 100% of parameters with clear descriptions, including aliases for 'question'. The description adds 'same arguments' as ask_pipeworx but does not provide any additional semantic details beyond the schema, so it meets the baseline but not more.

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 it as the beta version of ask_pipeworx, a universal router with the same 5,366 tools and response shape, but with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx by emphasizing its experimental edge and current equivalence. The verb 'ask' plus 'router' and the specific details make the purpose unmistakable.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing' and it notes that it currently matches ask_pipeworx exactly. It implies a preference for experimental use but does not explicitly state when to avoid it or use the stable alternative, though the beta label and 'experimental edge' convey caution.

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 the refusal behavior with specific refusal_reason values, the exact response shape, and the trade-off of one extra LLM call. This gives an agent complete expectations of the tool's behavior without contradicting 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?

Structured in three terse sentences: it front-loads the purpose, clarifies the mechanism, and provides usage guidance. Every sentence contributes unique value without redundancy, making it appropriately compact for the information conveyed.

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

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

Given the simple input schema and rich annotations, the description is fully complete: it specifies the success and refusal response formats, the routing behavior, the use cases, and the cost trade-off. No output schema is needed because the return shape is explicitly documented in prose.

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

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

Schema coverage is 100%; all six parameters are aliases for the same 'question' field and are fully described in the schema. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results, distinguishing it from its sibling ask_pipeworx. The specific verb+resource and explicit scope make the purpose unambiguous.

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

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

It explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an exclusion by noting 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, providing clear guidance on 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 read-only, non-destructive, idempotent behavior; the description goes far beyond by disclosing resolver confidence levels, blocking statuses (low_confidence_match, market_closed_or_inactive), tradeability warnings, fan-out sources, cancellation-rule parsing, and fallback behavior. This is exceptional transparency.

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

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

The description is very long but organized into clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and almost every sentence carries operational detail. However, it is overly verbose in places—e.g., the aside about de-indexed markets could be condensed—and would benefit from tighter prose.

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

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

For a tool with no output schema, the description comprehensively covers return-value shapes, edge cases, statuses, resolver contract, parent-event expansion, news fallback fields, and cancellation-rule risk. It even quantifies a known rules-loss scenario (flat-50¢ void settlements). There are no obvious gaps for an agent selecting or invoking it.

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

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

Schema has 100% coverage with detailed descriptions for all three parameters (market formats, depth selector, include_raw behavior with size implications). The main description adds context about fan-out and output shapes but does not add meaning to individual parameters beyond what the schema already provides, so the 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 opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data') and differentiates from siblings by describing the one-call fan-out and evidence-packet result. It also enumerates concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from arbitrage/edge-scanner 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?

Clearly states when to use the tool via 'Use for...' and gives extensive workflow context. However, it doesn't explicitly name sibling tools as alternatives or state when NOT to use it, so the exclusion guidance is less explicit than the calibration high bar.

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

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

Beyond the read-only annotations, the description details data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, debt, adverse-event counts), fiscal year handling, result sorting by primary metric, and return format with citation URIs. This rich behavioral context 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 front-loaded with trigger phrases and core purpose, followed by type-specific details and output behavior. Every sentence adds value without redundancy, and the structure flows logically despite its length.

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

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

For a tool with no output schema, the description explains key return information (paired data, citation URIs) and sorting behavior. It covers both entity types and data sources, but doesn't mention failure modes or edge cases like invalid inputs, which would make it 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 covers parameters at 100%, but description adds semantic meaning: explains that type='company' maps to 10-K data and type='drug' to FAERS, and clarifies that values are tickers/CIKs for companies and drug names for drugs. It also notes off-calendar fiscal year handling, enriching parameter understanding.

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 does side-by-side comparison of 2–5 companies or drugs in a single call, with specific verb and resource. It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile, making the purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example query patterns. It gives strong when-to-use guidance but doesn't explicitly cover when-not-to-use scenarios beyond comparisons, so it's clear but not fully exclusive.

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), the description reveals rich behavioral detail: account and paid-plan requirements, expected latency (15-60s, up to ~90s), gap recovery and contradiction scanning, semantic excerpting, and explicit assurance that findings are never invented. It also discloses limitations (e.g., empty gaps for news topics). 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 long but front-loaded with the most critical info (account requirement, fallback). It is dense and each sentence adds value, though some depth-level details are repeated from the schema. For the tool's complexity, the length is justified and well-sectioned.

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, so the description adequately explains the return format: a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop/citation_uri fields. It also covers timing, account requirements, and alternatives, making it complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description adds extra semantic context: it clarifies that question can be broad/multi-part, explains the behavioral differences between depth levels beyond the schema, and ties 'thorough' to a paid plan. This supplements rather than merely restates 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 defines the tool with a specific verb and resource: "Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources" and "Decomposes your question into focused facets, routes each to the right one of 5,366 tools IN PARALLEL." It distinguishes from siblings by explicitly contrasting with ask_pipeworx for single lookups and news topics.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: "Best for broad/multi-part questions over structured data," "For a single lookup use ask_pipeworx," and "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx." It also covers account prerequisites and fallback behavior, plus depth-level selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral context beyond annotations: it returns top-N most relevant tools with full input schemas and curated examples, ready to call directly with no second lookup. This clarifies output behavior and immediate usability, though it doesn't detail edge cases like empty results.

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 main purpose. The domain list is long but directly relevant to setting user expectations. Every sentence contributes (purpose, return behavior, usage context), though the list makes it 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?

There is no output schema, so the description compensates by explaining the return format: top-N tools with names, descriptions, and full input schemas. It covers purpose, usage, and output sufficiently for a discovery tool of this complexity, and annotations cover safety.

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

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

Schema description coverage is 100%, with each parameter (including aliases) documented. The description adds domain examples (SEC, FDA, FRED, etc.) that inform query formulation, but it does not add meaning beyond what the schema already provides for individual parameters. 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 starts with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by positioning as a discovery/meta tool, listing covered domains, and stating it returns top-N tools with schemas. This is not a tautology and uniquely separates it from domain-specific siblings.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available.' It also clarifies it is for viewing the option set, not answering a single query, which differentiates from alternative tools.

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

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

The description adds substantial behavioral details beyond the annotations: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields with arbitrary limits (up to 5 filings with URIs), and discloses soft-fail behavior for patents due to API sunset (May 2025). It also explains fallback logic (GDELT→GNews). This is rich context that the annotations (readOnlyHint, openWorldHint, etc.) do not provide. No contradiction exists.

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

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

Despite being a single long paragraph, the description is dense and every clause earns its place: examples, data sources, return structure, limitations, and fallbacks. It is front-loaded with example queries that quickly convey the tool's intent, and the rest flows logically. There is no redundancy or fluff.

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

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

With no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: it lists the exact fields (cik, company_name, recent_filings with URIs, fundamentals with particular metrics, patents, news, LEI) and mentions source specifics (USPTO sunset, GDELT→GNews fallback). It also covers input constraints and hints at the parallel-call performance benefit. This is fully complete for an agent to decide when and how to 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 description coverage is 100%, so the baseline is 3. The description does not add much beyond the schema: it repeats the parameter details ('ticker AAPL or zero-padded CIK 0000320193') and the note about names not supported, which are already in the schema's parameter descriptions. While the examples are helpful, they don't offer new semantic knowledge.

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 uses a specific verb ('profile') with a specific resource (US public company) and provides multiple example queries. It also distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentioning it returns a cross-source profile, unlike more focused tools like resolve_entity 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 gives explicit when-to-use guidance: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack lookups.' It also provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This covers both positive and negative usage cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the core behavioral trait is covered. The description adds context about clearing sensitive data and pairing with remember/recall, but does not disclose additional unique behavior beyond what the annotations and schema imply.

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 action, and each sentence earns its place. No fluff or repetition.

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

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

For a simple one-parameter destructive tool with strong annotations and full schema coverage, the description provides enough context. It covers purpose, usage scenarios, and related tools, making it complete for its 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 covers 100% of the parameter with 'key: Memory key to delete', so the description adds no further meaning. The phrase 'by key' is redundant with the schema, yielding the baseline score.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes itself from sibling tools like remember and recall by focusing on deletion. This clearly identifies the tool's unique purpose.

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: 'Use when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with remember and recall. It lacks an explicit 'when not to use' clause, but offers strong contextual guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior. The description adds valuable context: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown as a single blob. This gives the agent a clear model of what happens beyond the annotations.

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

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

The description is two sentences that efficiently cover the core function, process, output format, and use cases. No redundant information; every sentence earns its place and the main purpose is front-loaded.

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

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

For a simple, read-only tool with 2 params and no output schema, the description adequately explains workflow, output format ('single text blob', 'standard llms.txt markdown format'), and practical scenarios. It could include an example, but is sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptive parameter comments for both 'url' and 'max_links'. The description reinforces that the URL can be any site and that links are extracted, but it does not add meaningfully beyond the schema, so a 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 ('Generate a production-ready llms.txt file') with a distinct resource ('for any URL') and explains the process (fetch, extract, emit). It differentiates from sibling tools by focusing on llms.txt generation rather than generic AI visibility scanning.

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

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

The 'Useful for' section lists three concrete scenarios: indexing a client's site, drafting for a personal project, and auditing a competitor. This provides clear context for when to use the tool, though it does not explicitly name alternative tools or 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=true and destructiveHint=false, providing the safety profile. The description adds valuable context beyond annotations by specifying that only the caller's subscriptions are listed and that inactive ones are excluded by default unless include_inactive is true. 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 two sentences: the first front-loads the core action and output, the second gives usage guidance. Every sentence serves a purpose, with no redundancy or fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema, complete annotations), the description covers everything needed: what it does, return fields, default behavior, and when to use it. There are no significant gaps.

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

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

The schema provides 100% coverage for the single parameter include_inactive, including its default value. The description's reference to 'active subscriptions' simply aligns with the schema's 'cancelled subscriptions' but adds no new parameter semantics beyond what the schema already states.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing this from sibling tools like 'subscribe' and 'unsubscribe'. It also specifies the return fields, leaving no ambiguity about the tool's function.

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

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

The description explicitly states when to use it: 'review what you're monitoring before adding more' (i.e., before subscribing) and 'to find an id to cancel' (i.e., before unsubscribing). This gives clear contextual triggers and implies alternatives, making the agent's decision process straightforward.

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?

All annotations are false, so the description carries the full burden. It adds valuable behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against quota, and explains that feedback influences the roadmap. It doesn't mention idempotency or what happens after submission, but the provided constraints are helpful.

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, front-loaded with purpose, followed by usage triggers, a crucial behavioral note about not pasting user prompts, and constraints. Every sentence earns its place; no fluff.

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

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

The tool is simple with no output schema. The description covers purpose, usage, constraints, and context (team reads digests). It doesn't explicitly state the asynchronous nature or lack of a response, but that's not essential for a feedback tool. Overall adequate and 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%, so the baseline is 3. The description adds semantic value by linking enum values to real-world scenarios (e.g., 'bug = returns wrong/stale data') and by advising users to describe issues in terms of Pipeworx tools/packs, which enriches the 'message' parameter guidance beyond the schema.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly defining the action and resource. It explicitly enumerates the feedback categories (bug, feature/data_gap, praise), which distinguishes it from the research and analysis 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?

Provides explicit 'Use when' conditions mapping to feedback types (wrong/stale data for bug, tool not in catalog for feature/data_gap, positive experience for praise). Also includes a negative redirect: 'don't paste the end-user's prompt,' which clarifies boundaries. This is strong usage guidance.

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

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

Annotations already cover read-only, idempotent, and open-world aspects. The description adds valuable context beyond annotations: it reveals the data source ('derived from CF analytics-engine'), privacy ('no PII'), caching behavior ('Cached 5min-1h depending on window'), and output shape ('(pack, tool, count)'). This is substantial behavioral disclosure.

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

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

The description is a single, well-structured paragraph. It front-loads the core purpose, then outputs, then use cases, then data/behavior notes. Every sentence adds value—no redundancy or fluff. The 'Useful for' list is compact and actionable.

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 specifying returns ('top tools, top packs, and total call volume') and the data shape ('(pack, tool, count)'). Combined with comprehensive annotations, a single optional parameter, and clear cache behavior, the description fully contextualizes the tool 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?

The input schema already has 100% coverage with a descriptive enum explanation ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The description only reinforces this by mentioning window options and adding cache-window dependency, which is more of a behavioral note than new parameter semantics. Baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window' and describes it as 'What other AI agents are calling on Pipeworx right now.' This specific verb+resource+output distinguishes it from siblings like discover_tools by focusing on aggregate usage trends 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 three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choices, and checking alignment with agent needs. This gives clear when-to-use context, though it does not explicitly name alternatives or exclusions, preventing a perfect score.

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, but description adds rich behavioral detail: Jaccard similarity threshold, placeholder-slug filtering, partition_check sum interpretation, and fill_check behavior with realizable_edge_pp <= 0 warning. 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?

While long, every section serves a purpose. Uses labeled paragraphs (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize dense technical content. Front-loaded with the primary purpose and mode selection, then details follow logically. 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?

Extremely complete for a complex tool with no output schema. Describes response fields (opportunities[], partition_check{}, fill_check details), explains edge cases (placeholder fraction, realizable edge <= 0), and links to related tools. An agent has all necessary decision-making information.

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

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

Schema already covers both parameters well, but the description adds significant semantics: 'event' walks child markets and runs both monotonicity and partition checks, while 'topic' searches related events and flattens markets. It also clarifies accepted formats (slugs and full URLs), exceeding schema depth.

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 a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' Clearly differentiates from siblings like polymarket_edges (edge detection) and polymarket_fill_risk (execution risk) by focusing on arbitrage detection with explicit check 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?

Explicitly states when to use each mode: no args for trending scan, 'event' for single-market partition check, 'topic' for cross-event scans. Recommends event mode for a specific market, explains the value of cross-event scanning, and directs to polymarket_fill_risk for custom sizing. This is actionable guidance with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds rich behavioral context: hourly KV caching, diagnostics for empty segments, edge computed net of slippage, Kelly caps, the 24h-move warning, and placeholder-slug filtering—going well 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 a single ultra-dense paragraph. It is information-rich and every section serves a purpose, but it lacks visual structure (line breaks, bullets) and includes an obscure 'Run 8' reference that may confuse the agent. It is verbose but not wasteful.

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

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

With no output schema, the description fully explains the response shape: by_segment, fed_candidates/fed_note, and _diagnostics. It details per-opportunity fields, segment filtering rules, and the reason for excluding Fed bets. It leaves no major gap for a complex discovery 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% with detailed parameter descriptions. The description adds cross-parameter semantics by grouping knobs as 'TRADEABLE-EDGE KNOBS' and explaining how min_partition_leg_kelly applies to per-leg Kelly inside partitions, which is not obvious from 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 and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings by framing the tool for opportunity discovery with three model segments, rather than pure arbitrage or tracking.

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 the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when to apply tradeable-edge knobs and warns about unreliable Fed signals. However, it does not name alternative sibling tools for exclusion, so it stops short of full when-not 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 annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds substantial non-obvious behavioral details: the 60-day snapshot TTL, snapshot gaps when no scan occurred, decay computed from daily closes, and adjustments for slippage. 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 carries unique information: the core question, parameter list, response structure, and limitations. It is organized in clear sections (TITLE, DESCRIPTION, Args, RESPONSE, LIMITS) and front-loads the purpose, 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?

With no output schema, the description fully documents the response semantics: tracked[] with time-series and trend, expired[] with lifespan, and snapshot_dates[]. It also covers edge cases (TTL, data gaps) and clarifies computation methodology, making the tool's behavior and output completely understandable.

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

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

Schema coverage is 100% (both days and window are fully described in the input schema). The description reinforces the same semantics (lookback, snapshot family) but does not add meaningful new parameter-level details beyond what the schema already states. 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 opens with a specific statement of what the tool does: "Edge persistence and decay telemetry built from daily polymarket_edges snapshots." It then articulates the exact question it answers ("how long has this edge existed and is it shrinking?"), which clearly differentiates it from siblings like polymarket_edges that likely provide current snapshot data.

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

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

The description gives concrete usage context: "a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)." This effectively tells the agent when to use this tool (when historical persistence matters) without explicitly naming alternatives, but the differentiation from siblings is implicit and strong.

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

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

Annotations already declare readOnly, non-destructive, idempotent. The description goes far beyond by detailing exactly what the tool computes (top_of_book, vwap_fill_price, slippage_pp, etc.), explaining the basket-mode partial-fill risk, and warning about forced directional exposure. This is rich behavioral context that annotations don't provide. 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?

Though long, the description is densely packed with essential information and uses clear structural signposts (SINGLE-MARKET, BASKET). Every sentence earns its place by adding mode-specific behavior, output fields, or risk context. The front-loaded purpose sentence avoids burying the lead.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It enumerates the key return values, explains edge-case behavior (thin legs, forced directional risk, partial fills), and provides a threshold for when the tool is necessary. 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%, but the description substantially augments the parameter semantics. It explains that `market` and `event` select distinct modes, clarifies how `size_usd` is interpreted differently for buys vs sells and for basket mode (settlement notional), and defines the `side` defaults and behavior. This adds meaning well beyond the schema descriptions.

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

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

The description opens with a precise, specific verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly names the two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges), distinguishing itself as the pre-trade risk check.

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 usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This tells the agent exactly when to invoke this tool over alternatives and even explains the failure mode it prevents.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes well beyond these by detailing compatibility_warning conditions, temporal_alignment, and skipped_cross_type/subtype counters. It also honestly states that pre-mapped topics often return warnings and are not tradeable — valuable behavioral transparency.

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

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

The description is long but well-structured with bolded labels (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose and each section adds essential detail. It earns a 4 rather than 5 because it is dense and slightly sprawling, but 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 fully explains the response structure (leg-by-leg prices, top_spreads_pp) and all safety fields (compatibility_warning, temporal_alignment, skipped_cross_type). It also covers failure modes. This is complete for a complex cross-venue 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% with basic descriptions, but the description adds significant meaning: it explains the two modes, distinguishes topic shortcuts from explicit ticker/slug pairings, and clarifies that kalshi_event_ticker and polymarket_event_slug override the topic mapping. This is more than the schema alone provides.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage (which likely focuses on intra-venue arbitrage) and polymarket_edges. The two-mode structure is also explicit.

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

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

Provides clear context on when to use: 'when the bet shapes are equivalent' the spread is a real signal, and warns that most pre-mapped topics return compatibility_warning and are not tradeable. It does not explicitly name alternative tools or say 'use this instead of X,' but the guidance is strong. Slight deduction for lacking explicit exclusion of competitors.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond those annotations by explaining that omitted dimensions 'collapse' in the result. This is valuable behavioral information not present in the schema or annotations.

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

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

The description is three short sentences, front-loaded with the core purpose. Each sentence provides distinct, necessary information: what it does, how parameters map, and a key behavioral rule. There is no filler or redundancy.

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

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

With strong annotations, a complete schema example, and a nested body structure, the description is largely adequate. The omission semantics are explained, but the output shape is not explicitly described and the relationship to table_meta is absent, leaving minor 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%, giving a baseline of 3. The description enriches both parameters by identifying 'id' as the SSB table id and 'body' as a PxWeb query object, plus explaining the behavior of omitted dimensions. This adds clarity beyond the schema's structural definitions.

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 and resource: 'Pull data from a table.' It also identifies the SSB table id and PxWeb query object, which distinguishes it from generic data tools. However, it does not explicitly contrast with sibling tools like table_meta, so it misses the full differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives such as table_meta or search_within. The only usage-related note is about omitted dimensions collapsing, which is more about parameter construction than choosing between tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful context by explaining that data is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all keys. This enriches the safety profile without contradicting annotations.

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

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

Three sentences, front-loaded with the primary action, followed by usage context, scoping, and tool relationships. Every sentence serves a purpose 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?

The description covers purpose, usage, scoping, and relationships to remember and forget. Since there is no output schema, the behavior of returning a value or list of keys is clear enough. Annotations cover safety, making this complete for a simple retrieval tool.

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

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

Schema coverage is 100%, and the schema already explains 'omit to list all keys'. The description adds value with concrete examples of key values (target ticker, address, research notes), helping the agent choose meaningful keys. It reinforces the omit behavior without adding new technical details.

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

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

The description clearly states that the tool retrieves a previously saved value or lists all saved keys when the key argument is omitted. This specific verb+resource combination distinguishes it from sibling tools like remember and forget, which save and delete respectively.

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

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

It explicitly says 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It does not include explicit when-not-to-use statements, but the pairing with remember and forget implies the intended workflow.

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

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

The description discloses that setting mark_read:true flags events as read and affects subsequent calls, implying persistent state mutation. However, annotations declare readOnlyHint=true, which signals no side effects. This is a direct contradiction, so the score is 1 per rubric.

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

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

Three tightly packed sentences cover purpose, return fields, filtering, read-flag behavior, and an external mirror endpoint. No redundancy and the main verb is front-loaded.

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

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

Despite lacking an output schema, the description lists the key return fields (source, citation_uri, raw payload) and explains filters and mark_read. The schema covers the remaining parameter details, making the overall package 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?

The schema already covers all 5 parameters with descriptions, but the tool description adds valuable semantics: an example type value ('sec_8k'), clarifies ISO timestamp format for 'since', and explains the behavioral effect of mark_read. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb 'Pull fired events from your subscription feed', clearly identifying the resource (alerts/events) and distinguishing it from siblings like list_subscriptions and recent_changes. It also specifies the return payload (source, citation_uri, raw event payload) and filter options.

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

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

Provides clear context: filtering by type and since, polling guidance, and an alternative endpoint for scripts and dashboards. It does not explicitly name sibling tools or state when not to use this tool, but the context makes the intended usage 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the fan-out architecture, the GDELT→GNews fallback under rate limits or 5xx, and the PatentsView API sunset causing USPTO to soft-fail. It also specifies the return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs), which is not covered by annotations or an output schema.

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 the simplest examples but each sentence delivers distinct value: query paraphrases, source fan-out, parameter details, return structure, and alternative tool guidance. It is dense but not redundant; however, the opening string of query paraphrases could be trimmed slightly for tighter structure.

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

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

Despite having no output schema, the description fully specifies the return format, the data sources and their failover behavior, and the acceptable `since` formats. It is complete enough for an agent to select the tool and interpret the result without further documentation.

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

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

Schema coverage is 100% (all three parameters have descriptions). The description adds a minor recommendation to use '30d' or '1m' for typical monitoring, but it largely echoes the schema's parameter descriptions without introducing significant new semantics. 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 concrete user queries and explicitly defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It enumerates the data sources (SEC, GDELT/GNews, USPTO) and distinguishes itself from sibling entity_profile by noting that entity_profile provides a static profile regardless of window.

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

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

The description provides explicit when-to-use guidance via natural language paraphrases and directly names the alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This is a clear when-not/alternative statement.

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, the description discloses key details: scoping by identifier, persistence differences for authenticated vs. anonymous sessions (24 hours), and the intended pairing with recall/forget. This adds meaningful behavioral context without contradicting any 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 contributes value: the main action, when to use, how it's stored, retention policy, and companion tools. The structure is front-loaded and concise 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?

For a simple 2-parameter tool with annotations and full schema coverage, the description is complete. It covers purpose, usage, persistence, and relationships with siblings, leaving no obvious gaps for an agent to misuse 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% for both key and value, providing a solid baseline. The description enhances this by showing real-world examples of keys and values and explaining the scoping aspect, though it doesn't introduce fundamentally new parameter semantics beyond the schema.

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

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

The description clearly states the tool saves data for reuse, specifying the resource as a key-value pair. It also distinguishes itself from sibling tools by explicitly pairing with recall and forget, making its unique function 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: 'Use when you discover something worth carrying forward...' and gives concrete examples (resolved ticker, target address). It also names alternatives (recall to retrieve, forget to delete), clarifying the workflow.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context beyond annotations: that each call cascades through several lookup endpoints internally, that it auto-disambiguates, and that it returns citation URIs. This is valuable transparency 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 moderately long but densely informative. It is front-loaded with examples and the core purpose. Every sentence contributes: examples, supported types, return details, and a usage pointer. The structure with SUPPORTED TYPES is clear. Slightly verbose but justified by the need to explain two distinct entity types.

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 explains what the tool returns for each type, including citation URIs and data sources. It also covers the use case, input flexibility, and internal behavior. For a simple two-parameter tool with no output schema, 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?

Schema coverage is 100%, but the description goes further by detailing what each type returns (ticker + CIK + company_name for company; RxCUI + ingredient + brand for drug) and clarifies that input value accepts ticker, CIK, or name with auto-disambiguation. This adds meaning beyond the schema's property descriptions, which are already good but less rich.

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 that the tool resolves a user-spoken name to the canonical/official identifier needed by other tools. It provides concrete examples (ticker, CIK, RxCUI) and distinguishes itself from sibling tools as an ID lookup prerequisite. The verb 'resolve' plus the resource 'entity name to identifier' is specific and unique.

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: 'Use FIRST whenever you have a name but need an ID.' It also explains that using the tool replaces 2-3 manual lookups. While it doesn't explicitly list alternatives, it clearly scopes when to use it and what it does, which is more than enough for this context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavior: probes each entity, ranks by score, surfaces most/least recognized, and describes output fields (score, confidence, signal density). This goes 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?

Three focused sentences: first explains the action and output, second states use case with an illustrative question, third lists return fields. No unnecessary words; every sentence earns its place.

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

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

Given no output schema, the description compensates by naming the return elements (ranked list with score, confidence, signal density). Combined with full parameter documentation and safe read-only annotations, the agent has enough context to invoke correctly. It lacks only an explicit note about error/edge cases, which is less critical here.

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

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

Schema coverage is 100% and each parameter already has descriptive text (entities role, models supported, _apiKey requirement, context purpose). The description reinforces the first-entity-subject concept but provides little additional parameter-level meaning beyond what the schema already offers.

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

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

The description uses specific verbs and resources: 'Compare AI visibility across multiple entities side-by-side', distinguishes from siblings by explicitly referencing ai_visibility_check and the competitive audit use case. It clearly conveys what the tool does and how it differs from a single-entity check.

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 clear context: 'Useful for competitive AI-marketing audits' and an example question. It implies this tool is for multi-entity comparison rather than single checks, but does not explicitly list alternatives or when-not-to-use.

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

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

Annotations already establish read-only and idempotent hints, and the description adds valuable behavioral context: external service fan-out, graceful degradation of partial failures, potential 5-30s latency on first bundlephobia measurement, and the sources_failed field. No contradiction with annotations.

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

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

The description is longer than average but every sentence is dense with information: composite nature, data sources, use cases, return fields, ecosystem limits, and failure behavior. The structure flows logically and earns its length.

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

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

With no output schema, the description explicitly enumerates the summary block fields, advisories, links, and alternative versions. It also accounts for partial failures and timing, making it complete for a complex tool with external dependencies.

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 schema already documents both parameters well, and the description does not significantly add parameter-level meaning. It does clarify defaults and scoped package acceptance, but this is minimal added value beyond schema.

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

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

The description states a specific composite check for npm packages, fanning out to deps.dev and bundlephobia with concrete data points. It clearly distinguishes itself from sibling tools (e.g., scan_competitor_ai_presence) by focusing on dependency health and adoption cost.

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 an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides an exclusion: NPM only, with alternative guidance that PyPI/Maven/etc. fall under deps.dev:version directly.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral detail: it returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and truncates inputs over 200K chars with a flag. 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 five dense, front-loaded sentences, each carrying unique information: core action, usage scenario, return format, companion tool, and technical constraints. There is no tautology or wasted wording, and the content is efficiently organized from 'what' to 'when' to 'how'.

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 explicitly states the return shape (passages with offsets and scores), the input size cap, truncation flagging, and the companion-tool workflow. For a three-parameter tool with no output schema, this is fully sufficient 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond field descriptions: it explains the shape of results ('top-N passages with character offsets and similarity scores'), the embedding/window technique, and the truncation behavior affecting the text parameter. This enriches the schema's existing parameter docs.

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 'Semantic search INSIDE a fetched record,' naming a specific verb, resource, and scope. It clearly differentiates from siblings by contrasting with ask_pipeworx_grounded and emphasizing local search over already-pulled text.

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 an explicit trigger: 'Use when the record is too big to cram into the prompt.' It also names a companion tool and workflow ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages') and provides concrete examples of acceptable inputs (SEC 10-K body, article, long tool result).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details: default root path, recursive child-node returns with {id, type, text}, folder vs leaf type semantics, and examples. It omits edge-case behavior like invalid-path handling, but still enriches beyond annotations.

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

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

The description is three dense sentences: purpose, mechanics, and examples. It is front-loaded with 'Navigate the subject tree,' and every sentence contributes essential information—no filler or redundant repetition of schema fields.

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

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

For a tool with one optional parameter, no required fields, and no output schema, the description is remarkably complete. It covers parameter defaults, response structure, node type meanings, and even ties to sibling tools (table_meta/query_table). The only missing detail is behavior on invalid paths, but for this simple read-only navigator, that is a minor omission that does not hinder correct 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?

The schema already describes 'path' as a sub-path under /table/, but the description elevates this by explaining it is a node id path, how folder/leaf types determine traversal, and providing concrete examples. This adds meaningful guidance beyond the schema's property description, compensating for any ambiguity in the 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 opens with 'Navigate the subject tree,' a specific verb+resource pairing that clearly defines the tool's role. It further distinguishes from siblings by explaining the hierarchical path traversal and how leaf table IDs connect to table_meta/query_table, making its unique purpose unmistakable.

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

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

The description implicitly provides usage guidance by explaining the path mechanics and giving examples ('' - root, 'be' - Population, 'be05' - Population count tables). It also notes that leaf table IDs are passed to table_meta/query_table, signaling the workflow context, though it does not explicitly say 'use this when...' or exclude other tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these: it requires OAuth (auth caveat), explains the feed is always-on and how to pull it, and discloses SMS verification and rate caps. It is consistent with annotations, so 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 a single dense paragraph that front-loads purpose, followed by auth, types, and delivery details. Every sentence contributes useful information without fluff, though it is slightly long and could be broken into clearer sections.

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 complexity (nested objects, multiple enums, delivery options), the description covers the key contextual aspects: purpose, auth, return value, supported types, delivery channels, and rate limits. The schema covers all parameter details, and the description handles the rest well. Minor omission: webhook is not mentioned in the description but is fully explained in the schema.

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

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

Schema description coverage is 100% and includes detailed examples for all parameters and nested objects. The description adds a minor semantic explanation (e.g., items:["5.02"] = officer change) but largely overlaps with the schema. It meets the baseline for high schema coverage but doesn't significantly enhance param understanding.

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

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

The description uses a specific verb+resource ('Create a proactive monitoring subscription to a live-data event stream') and explicitly distinguishes itself from siblings like list_subscriptions/unsubscribe by focusing on creation. It also states the return value ('Returns the new subscription id'), leaving no ambiguity about what the tool does.

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

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

The description gives clear usage context: it's for proactive monitoring of live data events, requires a Pipeworx OAuth account (excluding anonymous/BYO users), and enumerates supported types and delivery channels. It doesn't explicitly name alternatives like query_table or recent_alerts, but the context is strong enough to infer when to use it versus other tools.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds context about the dynamic nature ('drawn from the live catalog of thousands of tools') and the structure of the response (category-bucketed examples with tool+argument shape), which is beyond what annotations convey.

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

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

The description is a bit longer than average but every sentence earns its place: query examples, purpose, output details, usage, and alternatives. It is well-structured and front-loaded with user intents.

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 what is returned: category-bucketed example questions with exact tool+argument shape. It covers what, when, and how, making it fully self-contained for a new 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 already fully describes the `topic` parameter with allowed values. Description adds practical meaning by giving concrete examples ('finance', 'pharma', 'betting') and explaining the effect of omission ('full spread' vs. focus).

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

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

The description uses a specific verb and resource: it is 'the onboarding entry point' that 'returns category-bucketed example questions' and provides exact tool+argument shapes. It clearly distinguishes from siblings by orienting new agents and mentioning meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also gives guidance on calling with no arguments vs. passing a `topic` to focus.

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 behavior. The description adds context about what the output contains (variables/dimensions and valid values) and clarifies the 'id' as a numeric SSB table id, which is useful 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 a single sentence that is front-loaded with the core purpose and includes a clarifying example. Every word earns its place with no redundancy.

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

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

This is a simple read-only lookup tool with one parameter, a fully descriptive schema, and rich annotations. The description explains the output nature and parameter semantics, making it complete for the tool's simplicity.

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

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

Schema description coverage is 100% and already explains 'id' as a numeric table id. The description adds the 'SSB' qualifier and repeats the example, which is marginal value. Baseline 3 is appropriate given the schema carries the semantic weight.

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 tool provides 'Table definition (variables/dimensions and valid values)', which clearly identifies the resource and output. It lacks an explicit verb like 'retrieve' or 'get', but the noun phrase is unambiguous and distinguishes it from sibling tools like query_table.

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

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

Usage context is implied: use this tool when you need table metadata (schema) rather than actual data. No explicit when-to-use or alternatives are mentioned, but the resource type makes the intended use reasonably 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?

Beyond the annotations (readOnlyHint false, destructiveHint false, idempotentHint true), the description adds valuable behavioral context: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation logic ('row is deactivated not deleted, so historical events stay available'). This transparency goes above and beyond what annotations provide, and there is no contradiction.

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

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

The description is two sentences, front-loaded with the core action. Every sentence earns its place: the first states the purpose, the second explains key behavioral constraints. 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?

For a simple one-parameter tool with no output schema, the description covers all essential aspects: how to use it (by id), what happens (deactivation), and the consequence for historical data (stay available via recent_alerts). Combined with the annotations, the description is fully complete for its complexity level.

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 description coverage (the single 'id' parameter is described as 'Subscription id (uuid) returned by subscribe'), the schema does the heavy lifting. The description adds minimal new meaning beyond restating the action, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', using a specific verb and resource. It also distinguishes itself from siblings like subscribe and list_subscriptions by detailing the deactivation behavior instead of deletion, 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 provides clear context for when to use the tool: when you have a subscription id and want to cancel it. It implies the prerequisite of owning the subscription via 'Ownership is enforced', and the mention of recent_alerts suggests a follow-up usage. However, it does not explicitly name alternative tools 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 read-only/idempotent/non-destructive; description adds rich behavioral context: two-path routing (SEC EDGAR vs grounded pipeline), output verdict types, verbatim citation, and replaces 4-6 sequential calls. No contradictions.

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

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

The description is about 120 words, front-loaded with trigger phrases, and each sentence adds value (trigger examples, usage, routing, outputs, performance). Slightly long but well-structured and justified.

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

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

With no output schema, it fully specifies the return value (verdict, grounded value with citation, reasoning) and covers claim types and fallback behavior. The distinction between financial and general claims is complete for a complex 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?

Input schema covers both parameters with detailed descriptions (claim examples, tolerance_pct semantics, defaults). Description adds no extra parameter information beyond context already in schema; baseline 3 is appropriate due to 100% coverage.

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

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

The description clearly states it verifies factual claims against authoritative sources, with explicit usage examples ('fact check', 'true or false'). It distinguishes financial vs non-financial paths, making its scope and function clear beyond the generic name 'Validate Claim'.

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

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

Explicitly instructs when to use ('Use whenever the agent needs to check whether something a user said is factually correct'). Provides distinct routing for company-financial vs other claims, giving clear context. It doesn't name alternative tools or list exclusions, but the trigger examples are strong.

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