Hex Pm

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

Annotations already mark it read-only/idempotent, and the description adds important behavioral context: the default model is free, calling Anthropic requires a BYO API key and costs money, and the response structure is per-model plus combined. This exceeds the annotation baseline with cost and authentication details.

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

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

Three sentences cover purpose, model selection/cost, return shape, and use cases without waste. The most important information is front-loaded, and every sentence adds distinct value.

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

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

With no output schema, the description clearly describes the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers the main parameters and contextualizes the tool's purpose. Minor gaps like the structure of the combined view or what 'signals' contain prevent a 5.

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

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

The input schema has 100% description coverage, but the description adds value by explaining that _apiKey is only needed if 'anthropic' is in models and is passed through to api.anthropic.com, and clarifies the default model behavior. This goes beyond the schema.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs) and the scope (business/brand/product/topic). It distinguishes itself by describing a 0-100 visibility score per model, which is unique among the sibling tools, and lists concrete use cases.

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

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

It states when the tool is useful ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the choice of models (default free Workers AI vs BYO Anthropic key). However, it doesn't explicitly compare with sibling tools like scan_competitor_ai_presence or mention when not to use it.

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

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

Annotations already declare readOnly and idempotent behavior. The description adds meaningful behavioral detail: it routes to one of 5,767 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the 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 long but front-loaded with the most important preference rule and then layers scope, examples, and alternatives. Each section serves a distinct purpose, though some phrasing could be tightened without losing value.

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

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

Given the tool's routing complexity and lack of an output schema, the description covers the key behavioral expectations: input form, example questions, target domains, citation output, and alternative tools. It is comprehensive enough 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 description coverage is 100%, so the schema fully documents the question parameter and its aliases. The description reinforces the idea that the parameter is a natural-language factual question and provides examples, but it does not add meaning beyond the schema.

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

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

The description clearly identifies ask_pipeworx as a router that answers factual questions from authoritative structured data and returns citation-backed answers. It names the specific resource domains and explicitly contrasts itself with web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance with trigger phrases, concrete examples, and a preference rule over web search. It also gives exclusion guidance by pointing to ask_pipeworx_grounded for verbatim-evidence answers and deep_research for broad multi-part questions.

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 readOnly, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: candidate improvements are enabled live, no candidate is currently active, and it is a full working router rather than a fallback. It stops short of detailing potential reliability differences during active experiments, so it doesn't earn a 5.

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 provides distinct information: the beta identity and relationship to ask_pipeworx, the current inactive candidate state, the usage instruction, and a clarification that it is not a fallback. It is detailed without redundancy and front-loaded with the core purpose.

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

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

For a single-required-parameter router with rich annotations and fully-covered schema, the description covers role, current behavior, usage, and relationship to the stable sibling. The lack of an output schema is mitigated by the explicit statement that the response shape is identical to ask_pipeworx.

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 only says 'same arguments' without adding parameter-level detail. All 6 parameters are fully documented in the schema as aliases for 'question', so no additional semantic guidance is needed.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable sibling by explicitly mentioning candidate routing improvements and the experimental edge.

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

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

It gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate so it matches ask_pipeworx exactly) and explains that results are compared against the stable router to decide merges, implying when not to use it.

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

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

Adds significant behavioral detail beyond the annotations: it returns verbatim evidence, explicitly refuses when data isn't sufficient, enumerates refusal reasons, and discloses the extra LLM call cost. This gives the agent a clear model of success and failure behavior.

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

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

The description is dense but every sentence serves a purpose: purpose, mechanism, return shape, refusal behavior, usage guidance, and cost trade-off. It is front-loaded with the core identity and contains 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?

Despite having no output schema, the description fully explains the return contract, including both success and refusal shapes. It also covers the relationship to ask_pipeworx, the cost implication, and the high-stakes use cases, making the tool's behavior sufficiently complete for 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the parameter is a natural-language question and explicitly listing accepted aliases, reinforcing the flexible input format beyond 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 states a specific function: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from fetched tool results. It clearly differentiates from ask_pipeworx by describing the same routing but a stricter, evidence-based extraction and refusal behavior.

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 this tool: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool and gives a cost-based selection criterion, leaving little to inference.

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

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

Beyond the read-only/idempotent annotations, the description discloses extensive behavior: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return status:'market_closed_or_inactive', wide-spread markets carry tradeability:'illiquid_wide_spread', and news fallback fields (_fallback_attempted/_fallback_failed_reason) are documented. It also explains blocking routes and resolution-rule risk. This far exceeds the annotation baseline and adds critical operational context.

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

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

Despite being long, the description is meticulously structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Each section contains dense, non-redundant information that an agent needs for correct invocation and interpretation. 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?

Given the tool's complexity, 3 parameters, and no output schema, the description is exceptionally complete. It covers input formats, classification taxonomy, fan-out examples, response shapes, resolver contract, parent event extraction, news fallback, safety statuses, and resolution-rule risk. This provides sufficient context to invoke the tool correctly and interpret results even without an output schema.

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

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

The schema covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description's first sentence repeats the market parameter's accepted formats (slug, URL, question text), which is already present in the schema. It adds no extra meaning for depth or include_raw parameters, so it does not exceed the baseline.

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

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

The description names a specific verb and resource ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and clearly distinguishes from sibling tools like polymarket_arbitrage or validate_claim by targeting 'should I bet on X' queries. It also details the fan-out and response shapes, leaving no ambiguity about what the tool does.

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

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

The description explicitly provides usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly name alternatives or exclusions, but the provided guidance is clear and context-rich. It also gives examples of when to check resolution-rule risk, adding practical usage nuance.

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 cover read-only, idempotent, and non-destructive behavior. Description adds significant context: data sources (SEC EDGAR/XBRL, FAERS, FDA), fiscal-year handling, sorting by primary metric, and citation URIs in results—far exceeding 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 dense but every sentence earns its place—trigger patterns, data specifics, sorting behavior, performance benefit. It is well-structured and front-loaded with the most important usage guidance.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs), sorting order, entity count limits, and the distinction between company and drug types. It fully prepares the agent for invocation and interpretation.

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

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

Schema already has good coverage with enum and descriptions, but description elevates it by explaining what each type pulls (10-K financials, FAERS counts, trial counts) and gives concrete examples for values. It also clarifies constraints (2–5 entities) and distinct behavior per type.

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

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

Description explicitly defines the tool as a side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific query trigger patterns. It clearly distinguishes itself from sequential single-entity lookups by noting it replaces 8–15 such lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists concrete user intents (compare, vs, versus, which is bigger) and entity types, making the appropriate invocation clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds substantial behavioral context: parallel decomposition across 5,767 tools, the findings packet shape, gaps[] for unanswered facets, no fabrication, hop depths, contradictions[], excerpting behavior, timing/latency, and citation resolvability. This goes well beyond what the 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 information-dense and front-loaded with the account requirement, but it is long and somewhat sprawling, mixing prerequisite alerts, usage guidance, output format, latency, and edge behavior in one paragraph. Every sentence adds value, though the structure could be tightened with clearer separation of concerns.

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 covers what an agent needs: prerequisites, alternatives, expected latency, result format, citation semantics, gap handling, and depth semantics. For a complex research tool with two parameters, this is complete enough to invoke correctly without further prompting.

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 depth enum is well explained in the schema. The description enriches the parameters by giving practical meanings (depth:'standard' adds gap recovery + contradictions; 'thorough' is paid and adds iterative lead chasing), plus it explains how the 'question' parameter behaves (multi-part is fine). This adds value 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 states a specific verb+resource (grounded multi-source research across Pipeworx's 1506 structured data sources) and clearly distinguishes itself from open-web search and from ask_pipeworx. It names what it is NOT ('NOT open-web search') and gives concrete example questions, so an agent can reliably select it.

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 says when to use it (broad/multi-part questions over structured data) and when not to (a single lookup -> use ask_pipeworx; breaking/current-events -> prefer ask_pipeworx). Also includes account/tier prerequisites and names alternatives. This is excellent selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, and full input schemas including curated examples, and states results are ready to call directly without a second schema lookup. This goes beyond basic 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 well-structured with four purposeful sentences: purpose, when-to-use, return format, and strategic advice. The domain list is long but informative and earns its place by scoping the tool's coverage. No redundancies 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?

No output schema exists, so the description must explain return values and does so explicitly: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Combined with the rich input schema and annotation coverage, this is complete for a discovery tool with a simple query parameter.

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 covers 100% of parameters with detailed descriptions, including the query aliases and limit. The tool description adds no additional parameter detail beyond restating that users describe data/task, which mirrors the query parameter. Baseline 3 is appropriate since the schema does the heavy lifting.

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 'Find tools by describing the data or task' with a specific verb and resource, and the domain list (SEC filings, FDA drugs, FRED, etc.) distinguishes it from action-focused sibling tools. It positions itself as a meta-tool for discovery, which is distinct from tools like ask_pipeworx or bet_research.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and when-not-to-use guidance, effectively differentiating it from tools that answer specific queries directly.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing fan-out behavior across specific sources, soft-fail handling for USPTO patents, what an empty section means, and the resolved:false response for private companies. This gives the agent accurate expectations about partial or empty results and non-fatal source failures.

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 section earns its place: examples at the top convey intent quickly, the fan-out list pre-explains expected results, and edge cases are folded into the parameter explanation. It could be slightly tighter, but it is front-loaded and logically organized.

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

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

With no output schema, the description carries full responsibility for return semantics, and it does so thoroughly: it names every output section, explains URIs, covers source failure, distinguishes expected no-data from bugs, and documents all accepted input shapes. An agent has enough context to invoke the tool and interpret results correctly.

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

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

Although schema coverage is 100%, the description enriches both parameters substantially: it explains that type accepts 'company' or 'ticker' interchangeably, that value can be a ticker/CIK/name, that names resolve via SEC EDGAR, and how unknown or private companies are handled. This is meaningful guidance beyond the bare schema text.

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

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

The description opens with concrete user phrasings and states the verb+resource precisely: build a full cross-source profile of a US public company in one parallel call. It clearly differentiates from simpler single-pack SEC/XBRL/news lookups and sibling tools like resolve_entity or deep_research by emphasizing holistic multi-source aggregation.

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 tells the agent when to prefer this tool: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also specifies accepted input forms (ticker, CIK, company name) and the private-company edge case, leaving no ambiguity about when it applies.

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 description doesn't need to repeat those. It adds minor context about clearing sensitive data, but goes no further in describing side effects, error behavior, or requirements. This is adequate given the annotation coverage, but not exceptional.

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 action, then providing usage context. Every word earns its place with no redundancy or filler.

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

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

The tool is simple (one required parameter), has a full schema, and the description covers purpose, usage conditions, and relations to siblings. No output schema is present, but for a destructive delete operation the description plus annotations give sufficient context for an agent to use it safely.

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% ('Memory key to delete'), so the schema fully explains the only parameter. The description's mention of 'by key' adds no meaningful information beyond the schema. Baseline 3 is appropriate because the schema carries the burden.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly stating the action. It distinguishes from sibling tools like 'remember' and 'recall' by focusing on deletion/removal rather than storage or retrieval.

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

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

Explicitly states when to use ('when context is stale, the task is done, or you want to clear sensitive data') and advises pairing with 'remember' and 'recall', providing clear usage context and sibling relationships. It effectively guides selection among related 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 and destructiveHint=false. The description adds the operational detail that it fetches the page and extracts content, plus the exact output format (standard llms.txt markdown). This goes beyond the annotation hints 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 three tight sentences covering purpose, process, output, and use cases. No filler, front-loaded with the key verb and result.

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 (2 params, no output schema). The description compensates for the lack of output schema by describing the output as a single text blob ready for site-root placement. It could add error handling or limitations, but it's adequate for the tool's complexity.

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

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

Both parameters are fully described in the schema (100% coverage), so the description does not need to add much. The description implies the core parameter (url) but does not mention max_links; baseline 3 is appropriate since the schema carries the load.

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

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

Clearly states the verb 'Generate' and the resource 'llms.txt file', with a specific scope ('for any URL'). Distinguishes from sibling tools by focusing on the llms.txt format and output, unlike other AI visibility/scanning tools.

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

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

The description provides three concrete 'Useful for' scenarios, giving clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, which is a minor gap given the sibling list includes similar AI visibility 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the operation returns specific fields (description, licenses, links, latest version, download counts), but it doesn't disclose behavior on missing packages or any other runtime traits. This adds some value without contradicting the annotations.

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

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

The description is a single, front-loaded sentence with zero wasted words. It states the action, the target, and the exact return payload, all before any 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 read-only lookup with one required parameter and no output schema, the description covers the essential context: the resource type, the lookup key, and the returned fields. Nothing an agent needs to successfully call it is missing.

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

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

Schema coverage is 100% and the single parameter 'name' is described with examples. The description adds context about what the package name refers to (Hex.pm, Elixir/Erlang), but that's more tool-level context than parameter semantics. Baseline 3 is appropriate since the schema already fully documents 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 uses a specific verb ('Look up') with a specific resource ('a single Hex.pm package ... by name'), clearly distinguishing it from sibling search/list tools like search_packages. It also names the target ecosystem (Elixir/Erlang mix) which removes ambiguity.

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

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

The phrase 'a single ... by name' implies this should be used when the exact package name is known, which differentiates it from search_packages or list_releases. However, it doesn't explicitly name alternatives or state when not to use it, so it stops short of full 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 establish that the tool is read-only, idempotent, non-destructive, and open-world. The description adds the set of returned fields, which is useful but does not disclose deeper behavioral traits such as response shape, pagination, availability behavior, or any external dependencies. It neither contradicts the annotations nor goes substantially beyond 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 one compact sentence that front-loads the action and resource, then lists the key output categories without filler. Every word earns its place and the reader immediately understands the tool's purpose.

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

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

For a simple two-parameter read tool with safety covered by annotations and 100% schema coverage, the description is complete: it states the inputs, the target resource, and the expected return contents. There is no output schema, but the description compensates by enumerating the relevant detail fields.

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 'name' and 'version' already have clear descriptions and examples. The description simply reinforces that these identify a specific version but adds no new meaning about parameter constraints, defaults, or formatting beyond what the schema states. The baseline score 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 names a specific verb ('Get'), a precise resource ('a specific version/release of a Hex.pm package'), and the included detail categories: dependency requirements, docs availability, publisher, and downloads. This clearly distinguishes it from sibling tools like get_package or list_releases, which target package-level or list-level 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 implies this tool is for retrieving details about one known package version, which is a clear use case, but it never explicitly says when to choose get_release over alternatives such as get_package or list_releases. No exclusions or alternative routing are provided, leaving the agent to infer the boundary from the phrase 'specific version.'

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 the read-only, idempotent, non-destructive safety profile. The description adds the useful fact that each release comes with its version and publish date, which partially substitutes for the missing output schema. It does not disclose pagination, ordering, or any API limits, but the bar is lower given the strong 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?

A single, front-loaded sentence that states the action, resource, and return details with no filler. Every clause earns its place.

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

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

For a simple one-parameter, read-only list tool, the description is complete: it names the package, the fact that all published versions are returned, and the key fields included. The robust annotations cover safety, and no output schema means the return description is especially valuable.

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 'name' parameter is already fully documented. The description adds that the package is a Hex.pm/Elixir/Erlang mix package, which gives useful context but does not materially expand on the schema's definition.

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

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

The description states a specific verb ('List'), a clear resource ('published versions (releases) of a Hex.pm package'), and the exact fields returned. It is clear and precise, though it does not explicitly differentiate itself from siblings like get_release or search_packages.

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?

There is no guidance on when to choose this tool over alternatives, no exclusions, and no mention of related tools. The purpose is implied, but the description does not help an agent route between list_releases, get_release, or search_packages.

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 non-destructive. The description adds that the response is scoped to the caller's subscriptions, defaults to active only, and lists the exact fields returned. This goes beyond the annotations and explains what the agent can expect.

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

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

Two sentences with no redundancy. The first sentence states purpose and output, the second gives usage guidance. Well 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?

The tool is simple with one optional parameter and rich annotations. The description provides return fields which substitutes for an output schema, and gives context for use with subscription management. Complete for this level of 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 only parameter include_inactive is fully described in the schema with 100% coverage, including default behavior. The description does not mention the parameter, so no additional semantics are added.

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?

Clearly states it lists the caller's active subscriptions, specifying the resource and scope. Distinguishes from sibling subscribe/unsubscribe by being the read-only listing tool. Also enumerates return fields.

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 to use this to review existing subscriptions before adding more or to find an id to cancel. This directly ties to sibling subscribe/unsubscribe actions, though it doesn't name them. Provides clear context for when this tool is appropriate.

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

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

Annotations provide only basic flags (readOnly=false, destructive=false), but the description adds rate-limiting (5/day), cost (free, no quota), the claim_token follow-up workflow, and the team's daily digest/roadmap influence—all valuable behavioral context 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 lengthy but every sentence serves a purpose, covering scope, use cases, exclusions, token flow, and constraints. It is front-loaded with the core purpose, though a slightly denser block than strictly necessary, so 4.

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 still covers the full workflow (how to file, token retrieval, follow-up), exclusions, and rate limits. It does not explicitly describe the response shape beyond the claim_token, but that omission is acceptable for this feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter understanding by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later') and advising to describe issues in terms of Pipeworx tools, which guides the message/context fields.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It further distinguishes the tool from siblings by limiting scope to Pipeworx-served tools and explicitly mentioning bug/feature/data_gap/praise categories.

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 is explicit: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' naming an alternative.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses meaningful behavioral traits: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns (pack, tool, count), and is cached 5min-1h depending on window. This adds value by explaining data provenance, privacy, output shape, and caching behavior.

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

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

The description is well-structured and front-loaded. It opens with the core purpose, then provides a numbered list of use cases, followed by three short clauses on data source, PII, and return format, and ends with caching. Every sentence earns its place; 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 tool has a single optional parameter, no output schema, and strong annotations. The description fully compensates by explaining the return content ('top tools, top packs, and total call volume'), the data format ('pack, tool, count'), and caching behavior. This gives an agent enough context to invoke it correctly and interpret results.

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

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

The schema already covers 100% of the parameter (window) with an enum and description. The tool description reinforces the meaning by embedding the window options and adds behavioral context: 'Cached 5min-1h depending on window.' The schema comment also explains shorter vs. longer windows, so the description and schema together provide rich semantic meaning.

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

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

The description clearly states the tool's function with a specific verb and resource: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes it from siblings like discover_tools or recent_changes by focusing on aggregated agent call patterns.

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: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It also contrasts window durations ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), but does not explicitly name alternatives or exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: the partition filter for placeholder slugs, the semantic similarity threshold (≥0.30 Jaccard), the fill check against live CLOB depth, and the explicit warning that a realizable edge ≤0 means the overround is not tradeable. This goes far beyond the annotations and makes the tool's behavior fully transparent.

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

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

The description is long but every sentence earns its place. It uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose in the first sentence. Structure is logical: mode selection followed by operational details, response format, and risk caveats. No filler or repetition.

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

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

Given the tool's complexity (multiple modes, thresholds, placeholder filtering, fill checking) and lack of an output schema, the description is remarkably complete. It specifies the return structure (opportunities[], partition_check{...}), the fill check details, the semantic anchor threshold, and the partition filter behavior. It even mentions a sibling tool for custom sizing, covering the full decision context.

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

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

Although schema coverage is 100%, the description enriches both parameters with examples and mode-specific semantics. It explains that `event` is for a specific Polymarket event slug, walks child markets, and computes a partition check, while `topic` is a seed question for cross-event scanning. It even provides example values ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and explains the difference between the two modes, adding meaning beyond the schema's basic 'single-event mode' and 'cross-event mode' 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+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no-args scan, event, topic) and explains what each does, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also recommends `event` for a specific market, explains why cross-event mode catches patterns single-event misses, and directs custom sizing to polymarket_fill_risk. This fully covers when and how to use each mode.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses many behavioral traits: the five model families, the 24h-move warning, the caching at KV level keyed on knobs, limitations of the Fed signal, and the 'rare-by-design' nature of concentrated longshots. This goes far beyond what annotations indicate, providing rich operational context.

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

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

The description is long but every sentence carries unique information. It is well-structured with headings for segments and knobs, and the core purpose is front-loaded. However, the density and wall-of-text format make it slightly less scannable than ideal, warranting a 4 rather than a 5.

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

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

With no output schema, the description compensates by explaining the response top-level structure (by_segment, fed_candidates, _diagnostics) and why segments may be empty. It covers all 9 parameters, the model families, the caching, and the tradeable-edge logic. For such a complex tool, this is 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?

Despite 100% schema coverage, the description adds significant meaning. The TRADEABLE-EDGE KNOBS section explains why min_partition_leg_kelly exists (partition arbs always return parent-level kelly 0) and how min_liquidity/max_spread_pp should be used. Slippage_pp gets context about Polymarket's zero fees and typical 20-50bp costs. This clearly exceeds the parameter descriptions in the schema.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes the tool from siblings like polymarket_arbitrage by emphasizing the Pipeworx data disagreement core. The 'built for' phrasing further clarifies its intended use case.

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 a clear when-to-use context ('what should I bet on today') and provides detailed knob guidance (e.g., 'Set to 5000 to drop thin-book opportunities'). However, it lacks explicit alternative-tool comparisons or when-not-to-use exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond these: snapshot data gaps, TTL limits, computation on daily closes, and the full response structure. There is no contradiction with annotations.

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

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

The description is dense but every sentence earns its place. Purpose is front-loaded, followed by clear sections for arguments, response structure, and limits. It is well-organized and contains 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?

Even without an output schema, the description thoroughly documents the response fields (tracked[], expired[], snapshot_dates[]), their semantics, and edge cases (gaps, TTL). It covers calculation details and practical implications, making it fully usable by an agent.

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

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

Schema description coverage is 100%: both parameters (days with default/clamp, window with allowed values) are fully described. The description repeats defaults and calls window a 'snapshot family' but adds no new meaning beyond the schema. Baseline 3 is appropriate when the schema carries full descriptive 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?

Purpose is unambiguous: the first sentence states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and the description answers a specific analytical question. It clearly distinguishes from sibling tools like polymarket_edges by focusing on historical time-series rather than current edge values.

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 for when to use the tool: to understand edge persistence and decay, with a concrete example. It also documents history limits (60-day TTL) and data gaps. However, it does not explicitly name alternative tools or state when not to use it, 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses critical behavioral traits: it 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), and warns that partial basket fills 'convert an arb into an unhedged directional position (the dominant loss mode)'. It also explains how size_usd is interpreted differently per mode. This adds substantial context that annotations do not provide.

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

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

The description is long (~200 words) but front-loaded with the core purpose and logically structured via 'SINGLE-MARKET:' and 'BASKET:' delineations. Every sentence adds necessary detail for a tool with two modes and rich return fields. It is not bloated, though it could be slightly trimmed without losing essential information. Thus a 4, not a 5, reflecting that it is appropriately sized for complexity but not minimalist.

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 takes on full responsibility for explaining return values, which it does comprehensively: single-market returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket returns (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers parameter semantics, mode selection, and practical usage guidance, making it a complete picture for a 4-parameter 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 all 4 parameters with descriptions (100% coverage), setting a baseline of 3. The description goes beyond by explaining mode-specific meanings: e.g., size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also clarifies side options and defaults in each context, adding genuine value over 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 a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by positioning this as the fill-risk validation step before executing arb signals. The two modes (single-market and basket) are explicitly named and explained.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books are not capturable, partial fills create directional risk), giving clear context for when this tool is needed over alternatives. The mode-selection rule (market vs event) is also specified.

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

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

Annotations only disclose read-only, idempotent, open-world, non-destructive behavior; the description adds substantial context beyond that: compatibility_warning/codes can be non-empty even on returned pairs, temporal_alignment null means unknown rather than aligned, every spread is gross of Kalshi fees, unknown legs are never paired, and skipped comparison counters are exposed. No contradiction with annotations exists.

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

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

The description is dense and front-loaded with the core purpose, then organized under clear labels like TWO MODES, RESPONSE, and SAFETY FIELDS. It is long, but nearly every clause carries an important caveat an agent needs to interpret results correctly; minor trimming could improve readability without losing value.

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

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

With no output schema present, the description carries the full burden of explaining the response shape, and it succeeds: leg-level prices, top_spreads_pp, skipped_unclassified, low_confidence_pairs, fees_note, temporal_alignment, and every compatibility code are explained. An agent has enough information to invoke the tool and interpret its results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful mode semantics: topic auto-fetches a pre-mapped event set, explicit parameters override each venue side, and both modes run the identical token-overlap matcher with the same disclosures. This is genuine enrichment beyond the schema's short parameter descriptions.

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

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

The description opens with a very specific verb+resource statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates this from the financial sibling tools by emphasizing same-question cross-venue comparison and explicitly describing two pairing modes.

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 explains exactly when to use the topic shortcuts versus explicit kalshi_event_ticker and polymarket_event_slug parameters, and warns that pre-mapped topics frequently return compatibility warnings and are not automatically tradeable. It does not name a specific alternative sibling or state when-not-to-use the tool, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extra scoping context (anonymous IP, BYO key hash, account ID) beyond the structured annotations, which is valuable. It does not describe the return format, but the safety profile is already covered by annotations.

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

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

The description is two sentences, front-loaded with the main action and directly supported by examples. Every sentence contributes meaning, with no filler or redundant detail.

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 one optional parameter, and the description covers purpose, usage, scoping, and relationships to sibling tools. Annotations and schema provide the remaining context, so the description is fully complete 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% with a clear description for the 'key' parameter ('Memory key to retrieve (omit to list all keys)'), so the description adds little extra semantic value. It reinforces the omit behavior but does not deepen the understanding beyond what the schema already provides.

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

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

The description clearly states the tool retrieves saved values or lists keys, using specific verbs and a clear resource. It distinguishes from siblings by mentioning 'remember' and 'forget' and provides concrete examples of what can be retrieved.

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

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

The description explicitly says 'Use to look up context the agent stored earlier' and shows when not to re-derive information. It also names alternatives ('Pair with remember to save, forget to delete'), giving clear usage context and relationship to sibling tools.

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

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

The description states that setting mark_read:true 'flag returned events read' and 'the next call only shows newer ones', which implies a mutating side effect. This directly contradicts the readOnlyHint annotation that declares the operation as read-only. Therefore, the description contradicts the annotation, warranting a score of 1.

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, and every sentence provides useful information without redundancy. It efficiently covers output fields, filtering, stateful behavior, and an alternative access method.

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 5 optional parameters and no output schema, the description sufficiently explains the return payload (source, citation_uri, raw event payload) and key behaviors. It does not mention unread_only and limit, but those are well-covered in the schema. The external endpoint note adds completeness. Minor gap: no mention of pagination or what happens with mark_read when combined with unread_only.

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 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by providing a concrete type example ('sec_8k'), explaining the ISO timestamp for 'since', and clarifying the effect of mark_read on subsequent calls, which adds meaning beyond the schema.

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

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

The description uses a specific verb 'Pull' and resource 'fired events from your subscription feed', clearly distinguishing it from sibling tools like list_subscriptions or recent_changes. It explains the returned payload and filtering capabilities.

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 for use: retrieving alerts from the feed, support for polling, and filters. It also offers an alternative endpoint for scripts/dashboards. However, it does not explicitly name when NOT to use this tool or compare it to sibling tools like recent_changes.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), the description discloses substantial operational behavior: fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO patent search with known sunset that causes a soft-fail. It also notes parallel execution and structured returns, which are not inferable from annotations alone.

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?

Six sentences efficiently cover purpose, data sources, fallback behavior, parameter syntax, return shape, and sibling differentiation. Every sentence contributes new information with no redundancy or filler, making it easy for an agent to parse in one pass.

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

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

Even though there is no output schema, the description specifies the return format (structured changes[], total_changes count, pipeworx:// citation URIs) and explains parameter syntax, source behavior, and failure modes. This is complete for a tool of this moderate 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 input schema already fully describes all three parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics for `since` by enumerating accepted formats (ISO date vs relative shorthand like '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring—value that goes 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 explicitly states the tool is a 'change feed for a company in the last N days/weeks/months in ONE parallel call', with concrete example queries like 'What's new with X'. It also distinguishes itself from sibling `entity_profile` with a direct pointer to when the sibling should be used instead.

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

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

The description provides explicit usage context through example queries and clearly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives the agent solid guidance on when to select this tool over a sibling.

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

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

Beyond annotations, the description reveals important behavioral details: scope ('scoped by your identifier'), persistence ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and cross-session behavior. These are not available in annotations and materially affect usage. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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 efficiently structured: first the core action, then when to use, then storage mechanics, then persistence, then related tools. Four sentences, no redundancy, all information earns its place.

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

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

For a simple two-parameter key-value save tool, the description covers purpose, usage conditions, storage semantics, persistence, and related tools. With no output schema needed and annotations covering safety, this description 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?

While schema coverage is 100%, the description adds substantial semantic context by giving concrete examples of what to store ('a resolved ticker, a target address, a user preference, a research subject') and explains the key-value pairing. This goes beyond the schema's generic descriptions and helps the agent choose appropriate keys and values.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('save') and resource ('data for reuse'), and distinguishes itself from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete.'

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 when-to-use guidance is provided: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives and complements: 'Pair with recall to retrieve later, forget to delete.' This clearly differentiates from siblings and gives practical 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, openWorldHint, idempotentHint, and non-destructive behavior, so the bar for adding value is higher. The description adds substantial context beyond annotations: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` entries rather than silent omission, source-labelled identifiers, and `figi_candidates` when ambiguity exists. No contradiction with annotations is present.

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 and dense, but the length is justified by the tool's complexity and the need to distinguish two entity types with different resolver behavior. It front-loads example queries and primary purpose before diving into edge cases. Slightly more formatting—such as bulleted sub-sections—would improve readability, but it is not wasted text.

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

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

Given no output schema, the description carries the full burden of explaining what the tool returns and how it behaves. It covers company and drug types, identifier sources, ambiguous matches, unresolved identifiers, fallback behavior, and input format constraints. An agent has enough context to select and call this tool correctly in almost all cases.

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 compensates with valuable guidance beyond the schema. It clarifies accepted inputs (ticker, CIK, ISIN, name) and adds a critical caveat: pass only the entity name, not trailing security-class words, because FIGI lookup matches instrument names. This materially improves correct invocation.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It immediately lists supported entity types (company, drug) and distinguishes the tool's role from siblings like entity_profile or compare_entities by focusing on identifier resolution rather than profiles or comparisons.

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 FIRST whenever you have a name but need an ID,' giving direct routing guidance. It also provides nuanced when-to-use details, such as handling non-equity instruments without tickers, ISIN-to-LEI resolution for non-US issuers, and what happens when a name matches multiple instruments.

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

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

With annotations (readOnlyHint, idempotentHint, openWorldHint) already covering safety, the description adds process details: it probes each entity via ai_visibility_check, ranks results, and surfaces most/least recognized. It also discloses output fields (score, confidence, signal density). This provides useful behavior beyond the annotations, though it does not mention potential external API calls or cost implications.

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

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

The description is three sentences, front-loaded with the core purpose, then expands with process, use case, and output details. Every sentence contributes substance without 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?

For a tool with no output schema and moderate complexity, the description covers what it does, how it works (via ai_visibility_check), what it returns (ranked list with specific fields), and when to use it. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds critical semantic context for the 'entities' parameter: the first entry is treated as the 'subject' and the rest as competitors. This clarifies how the tool interprets the array, which is valuable beyond the schema's basic type description.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from the single-entity 'ai_visibility_check' sibling. It explains the process (probes with ai_visibility_check, ranks by score) and the intended outcome, 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 a clear use case ('competitive AI-marketing audits') with a concrete example, and implies that this is for multi-entity comparison versus the single-entity ai_visibility_check. It does not explicitly mention when not to use it or name alternatives, but the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: possible 5-30s delay on first bundlephobia measurement, graceful partial-failure behavior with sources_failed, and the combined-output nature of the tool. 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 compact relative to the tool's complexity; it front-loads purpose, then delivers usage, output fields, ecosystem limitations, and failure behavior without filler. Every sentence contributes actionable information.

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

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

No output schema is present, but the description compensates by naming the full set of return fields, per-advisory details, links, alternative versions, and failure behavior. It fully covers the composite nature, latency, and scope, making the tool self-sufficient 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 fully documents both package and version, including that version defaults to latest when omitted. The description does not add new parameter-level meaning beyond the schema, so the high-coverage 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 composite npm dependency vetting check, enumerating the exact data sources (deps.dev and bundlephobia) and the question it answers (should I add this package). It distinguishes itself from direct deps.dev lookups by noting when the direct tool applies instead.

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 usage triggers are given, such as 'is X safe / popular / small' or 'what does adding lodash cost me'. The description also provides an exclusion: non-NPM ecosystems should go to deps.dev:version directly, which is clear when-not-to-use 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 establish readOnlyHint and idempotentHint, so no side-effect warning is required. The description adds value by disclosing that the operation returns a list of package metadata (descriptions, latest versions, downloads), which is not present in the input schema or an output schema. It does not discuss result limits or matching semantics, but these are minor given the safety annotations.

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

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

Two short sentences, front-loaded with the action and registry, then the result content. There is no filler, repetition of schema details, or unnecessary context.

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 read-only search tool with full schema coverage, the description is sufficient: required query behavior is clear, optional page and sort are documented in the schema, and the return shape is summarized because there is no output schema. Annotations cover safety and idempotency, so no hidden side-effect context is needed.

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?

All three parameters are already described in the schema, including defaults and the enum for sort. The description's 'by keyword' merely mirrors the query parameter and adds no new parameter semantics, so the baseline score 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?

States a specific action—searching the Hex.pm registry by keyword—and specifies the result as a list of matching packages with descriptions, versions, and downloads. This is clearly distinct from sibling tools like get_package or list_releases even without naming them.

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 phrase 'by keyword' clearly identifies the intended use case: keyword-based package discovery. It does not explicitly mention alternatives like get_package for exact-name lookups or search_within, so it lacks exclusions, but the context is otherwise 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, idempotent, non-destructive), the description reveals algorithm details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation flagged. It also describes the output structure (passages with offsets and scores), which is not in 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 densely informative yet compact. Every sentence earns its place: purpose, parameter guidance, use case, companion tool, and technical constraints are packed into four sentences without redundancy. Main purpose is front-loaded with 'Semantic search INSIDE a fetched record'.

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

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

Even though there is no output schema, the description explains return values (passages, offsets, scores), limitations (200K cap, truncation flag), use cases, and integration with a sibling tool. This is complete for an agent to select and invoke the tool correctly.

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

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

The input schema already covers 100% of parameter descriptions, so baseline is 3. The description adds useful semantics: examples of what 'text' should contain (SEC 10-K body, article), example queries, and the default/range context for 'limit'. This is above baseline but not exhaustive.

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: semantic search inside an already-fetched record, returning passages with offsets and scores. It distinguishes itself from siblings by emphasizing 'inside' and explicitly positioning 'Pairs with ask_pipeworx_grounded' rather than searching the whole document.

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

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

Explicit use guidance is provided: 'Use when the record is too big to cram into the prompt — search_within saves context...'. It also names a complementary tool (ask_pipeworx_grounded) and contrasts with whole-document grounding, giving clear when-to-use and alternative context.

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

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

The description adds substantial behavioral context beyond annotations, such as requiring a Pipeworx OAuth account, SMS verification and 10/day cap, and the always-on feed. Annotations indicate a write operation (readOnlyHint=false) and non-destructive behavior, which the description aligns with while adding operational details.

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

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

The description is long but well-structured, starting with the purpose and account requirement before listing types and delivery options. It is front-loaded and each sentence provides necessary information, though it could integrate webhook details from the schema to avoid omission in the main text.

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

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

The description covers the essential aspects: return value, authentication, type-specific params, and delivery details. However, it omits webhook as a delivery channel in the main description (present only in the schema), which is a minor gap given the absence of an output schema. Overall, it is sufficiently complete for a complex subscription 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 provides 100% coverage with detailed descriptions and examples for all parameters. The description adds semantic value by explaining the meaning of item codes (e.g., items:['5.02'] = officer change) and giving concrete examples for certain types, enhancing understanding beyond the structured 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 'Create a proactive monitoring subscription to a live-data event stream', which is a specific verb+resource statement. It clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and noting the returned subscription ID.

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 on when to use the tool, including account prerequisites and type-specific examples, but does not explicitly name alternatives or exclusions. It implies usage by detailing supported subscription types and delivery channels, which is sufficient given the sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: results are 'drawn from the live catalog of thousands of tools,' are category-bucketed, and can be filtered by topic. This enriches the model 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?

The description is verbose but every part earns its place: it opens with realistic example queries, then explains the purpose, return structure, categories, and usage. It is front-loaded with the most important info (what it returns, when to use it) and avoids filler, though it could be slightly tightened without loss.

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

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

With only one optional parameter, full annotations, and no output schema, the description provides everything an agent needs: what it returns (category-bucketed example questions with tool + argument shape), how to call it (no args or topic), and when to use it (first-time onboarding, learning meta-tools). It is complete for selection and 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 input schema provides 100% coverage for the single `topic` parameter, including the enumerated list (finance, pharma, economics, etc.) and the omit-for-default behavior. The description's mention of `topic` with examples (e.g. 'finance', 'pharma') closely mirrors the schema, adding no significant new semantics. 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 defines the tool as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking,' with a specific verb (returns) and resource (category-bucketed example questions with tool + argument shape). It effectively distinguishes itself from siblings by positioning as the 'FIRST' tool to use when unfamiliar with Pipeworx, and it explicitly lists the meta-tools it helps learn.

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

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

It gives an explicit directive: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides a clear when-to-use and an implicit when-not-to-use (when you already know). It also specifies two invocation patterns: no arguments for the full spread, or pass 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?

Beyond annotations, the description explains a key side effect: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This complements the destructiveHint=false annotation and adds the non-obvious behavior of logical deactivation. Ownership enforcement is also a behavioral trait not in annotations. No contradiction found.

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 brief (three sentences) and front-loaded with the core action. Every sentence adds value: purpose, ownership constraint, and behavioral consequence. No redundant or filler content.

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

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

For a simple one-parameter tool with rich annotations, the description covers the essential aspects: what it does, who can use it (ownership), and the deactivation behavior. It does not mention return values, but given the tool's simplicity and absence of an output schema, this is not a critical gap. Slight room for noting error behavior, but overall complete.

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

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

The input schema describes the sole parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description adds no new parameter meaning beyond saying 'by id'. Since schema coverage is 100%, the description's contribution is minimal; 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 the tool's purpose: 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription' are specific, and it distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation.

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 usage context: 'Ownership is enforced — you can only cancel your own subscriptions.' This is an exclusion that guides when the tool can be used. It also hints at the alternative of keeping history via recent_alerts, but does not explicitly name an alternative tool. Overall, context is clear with one exclusion.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds valuable behavioral nuance: the two pipeline routes, the meaning of 'unsupported,' and the critical warning that 'could_not_verify' means the check did not happen and must not be treated as evidence. This goes beyond what annotations provide, though it stops short of covering rate limits or auth details.

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

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

The description is long but information-dense and well-structured: trigger phrases, usage statement, pipeline explanation, return contract, and a highlighted 'IMPORTANT for callers' note. Every sentence contributes value, though the length is slightly more than necessary for a simple read-only tool. It remains appropriately sized for the complexity of the tool.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases. It enumerates the verdict enums, mentions the pipeworx:// citation, and provides explicit semantics for 'could_not_verify' and 'unsupported.' It also notes the tool's efficiency benefit. This is a complete, self-contained description for a claim-verification tool with two distinct processing paths.

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% (both parameters have detailed descriptions), so the baseline is 3. The description does not add much about the parameters themselves—it mentions 'exact percent-delta math' but does not explicitly explain tolerance_pct beyond what the schema already says. It places the claim in a natural-language context, but the schema already provides examples.

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

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

The description opens with a clear verb phrase ('natural-language claim verification against authoritative sources') and a full set of trigger examples. It distinguishes itself from siblings by specifying the structured SEC/EDGAR path for company financials versus a grounded pipeline for everything else, and by naming its verdict set. This makes the tool's scope unmistakable.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives a clear when-to-use signal. It also differentiates internal paths (company financials vs. other claims) and notes it replaces 4-6 sequential calls, implying efficiency. However, it does not explicitly name sibling tools as alternatives or provide 'when-not-to-use' exclusions.

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