Usgs Earthquakes

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 valuable behavioral context beyond these: it discloses that using Anthropic requires a BYO API key and that 'you pay Anthropic directly for those calls,' which is a crucial cost implication. It also notes which models are probed by default and the return shape. This enriches the safety/cost profile without contradicting annotations.

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

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

The description is compact and front-loaded. The first sentence states the core action and result. Subsequent sentences cover default behavior, API key usage, return format, and use cases without unnecessary verbosity. Every sentence contributes valuable information.

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

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

Given that there is no output schema, the description compensates by explicitly listing the return structure: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' Combined with clear parameter documentation and usage scenarios, the description is sufficiently 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?

Input schema coverage is 100%, so the baseline is 3. The description adds some nuance (e.g., 'Default model is Workers AI Llama-3.3-70b (free); pass `_apiKey` to also probe Anthropic'), but most of this is already present in the schema descriptions for `models` and `_apiKey`. The description does not significantly extend parameter 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's specific function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb ('probe') and resource ('LLMs'), and differentiates itself from sibling tools by focusing on multi-model visibility scoring rather than simple Q&A or entity resolution.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives strong guidance on when to use it. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full differentiation among 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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: routing across 5,529 tools, returning structured answers with pipeworx:// citation URIs, being a fast default entry point that works on all tiers, and even how it handles live news. 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 longer than typical but well-structured: it front-loads the key guidance, uses clear sections via sentences like 'START HERE' and 'Step up only when needed,' and includes examples. While a bit repetitive in listing data domains, the length is justified by the need to disambiguate from several siblings.

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, no output schema, and multiple sibling alternatives, the description is highly complete. It explains what the tool does, when to use it, when not to use it, what it returns, and provides concrete examples. It leaves no major gap for an agent to misuse it.

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

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

Schema description coverage is 100%: the 'question' parameter is explicitly described as accepting natural language and the aliases (q, query, prompt, text, input) are documented. The description adds no new parameter-level semantics beyond examples, which are already present in the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with citations. It names the resource (Pipeworx) and the action (ask/routing), and distinguishes itself from siblings by positioning ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description explicitly says to prefer this over web search for an extensive list of domains, provides trigger phrases like "what is" and "look up," and gives direct 'when' and 'when not' guidance by naming when to step up to ask_pipeworx_grounded or deep_research. Examples clarify usage scenarios.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds transparency about experimental status, current parity with the stable version, and that it is a full working router rather than a stub. It is upfront that no candidate is active and that behavior may change when candidates are tested, but does not elaborate on potential failure modes or differences during active tests.

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 composed of four sentences, front-loaded with the core definition and each sentence adding meaningful context. It is efficient and well-structured, with only minor redundancy (e.g., 'identical' repeated) that does not detract from clarity.

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 references 'same response shape' as ask_pipeworx, which is sufficient context for an agent familiar with the sibling. Combined with annotations covering safety and idempotency, it addresses purpose, usage, and current state. It could explicitly state the return format, but the reference to the stable tool's response shape fills this gap.

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

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

The schema provides 100% coverage with aliases for 'question' documented. The description mentions 'same arguments' but adds no new semantic detail beyond what the schema already states. This meets the baseline for parameter semantics when schema coverage is high.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, specifying it is an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing the experimental routing improvements and current parity. The verb 'ask' plus resource 'pipeworx' makes the purpose explicit.

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

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

The description explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It provides clear context for when to use this variant, though it does not explicitly name ask_pipeworx as the stable alternative 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?

Goes well beyond annotations by disclosing the exact return shape (answer, evidence, refusal_reason), refusal scenarios, and the extra LLM call overhead. Annotations only state readOnly/idempotent/destructive hints; the description adds substantial behavioral context without contradicting anything.

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

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

The description is dense but well-structured: it opens with the core purpose, explains the mechanism, details the output contract, and provides usage guidance and cost trade-offs. Every sentence adds distinct information, and the key differentiator ('grounded') is front-loaded.

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

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

Despite lacking an output schema, the description fully specifies the return format (including refusal reasons) and operational behavior (routing, extraction, cost). It also covers use cases, alternatives, and constraints, making it complete for a complex tool.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the question. The description does not add parameter-specific details beyond the schema, which is acceptable at this coverage level, but it also doesn't enrich the semantics further (e.g., no format constraints or examples). 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 function: 'Hallucination-resistant answer mode' and 'EXTRACTS the answer using ONLY what the tool result contains'. It distinguishes from sibling ask_pipeworx by explicitly contrasting 'grounded' vs 'casual' use, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), naming the alternative tool and citing cost considerations. This gives an agent clear decision 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/openWorldHint/idempotentHint, and the description goes far beyond by adding critical behavioral context: resolver contract (market_match_confidence, alternatives, suggestions), parent_event extractor for partitioned bets, news fallback mechanics (_fallback_attempted, retry_after_sec), safety short-circuit status, closed-market status, wide-spread tradeability, and resolution-rule risk. This is exceptionally transparent and directly actionable.

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

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

The description is long but well-structured with CAPITALIZED section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and front-loaded core purpose. Every section earns its place for a complex tool with no output schema, though some fan-out examples and repetition could be trimmed. It's appropriately sized for the tool's complexity but not maximally concise.

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

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

With no output schema, the description carries full responsibility for explaining return shapes and edge behavior. It covers response fields (market, analysis, evidence), resolver contract, parent-event partition, fallback handling for news, safety short-circuit, closed/inactive markets, illiquid-wide-spread, and cancellation-rule risk. This is unusually complete for a complex tool with 3 parameters and no 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?

Schema description coverage is 100%, and the schema already describes market slug/URL/question text, depth enum, and include_raw. The description reinforces the market parameter with examples but doesn't add significantly new parameter-level detail beyond the schema. It does, however, contextualize how the market value influences fan-out and response shape, which keeps it at baseline rather than above.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on single-bet research with fan-out, while siblings like polymarket_edges or polymarket_arbitrage target different analyses. The scope is explicit: it resolves the market, classifies the bet, fans out, and returns an evidence packet.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples and safety behavior (low-confidence short-circuit, closed-market handling), which helps agents understand what they'll get. However, it doesn't explicitly say 'when not to use' or name alternative tools for exclusion, 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?

Discloses data sources (SEC EDGAR/XBRL for company financials, FAERS/FDA for drugs), handles off-calendar fiscal years with examples (AAPL Sep, NVDA Jan), explains results are sorted by primary metric, and mentions returns paired data with citation URIs. This significantly exceeds the readOnly and idempotent 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 front-loaded with trigger phrases and a clear purpose statement, then packs essential behavioral details (fiscal years, sorting, data sources) without rambling. Every sentence contributes meaningful guidance; no filler or redundancy.

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

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

For a read-only comparison tool with no output schema, it fully explains returns (paired data + citation URIs), data repositories, sorting behavior, and entity-type specifics. It also notes the efficiency win (replaces 8–15 sequential lookups), making it contextually complete for an agent.

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

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

The schema already provides 100% coverage with descriptions of type and values, including min/max and example formats. The description adds extra examples (AAPL, MSFT, ozempic, mounjaro) and explains what data each type pulls, enriching parameter meaning beyond the basic 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 clear trigger phrases and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' providing a specific verb and resource. It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile by emphasizing the batch comparison nature.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists concrete user phrasing ('X vs Y', 'which is bigger', 'rank these companies', 'head to head'). This gives clear when-to-use guidance and directs away from inferior alternatives.

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

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

Annotations already declare this as read-only, non-destructive, and idempotent. The description adds useful context beyond those annotations: it confirms the operation returns a count rather than events, notes that it is fast, and mentions that it is keyless. This gives the agent important behavioral information 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 just three sentences, with the purpose front-loaded in the first sentence. Each subsequent sentence adds value: the use case, the filter compatibility with search_earthquakes, and the keyless access. No wasted words.

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

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

For a simple count tool, this description covers the main function, the return behavior (count, no events), and authentication (keyless). It references the sibling search_earthquakes for filter details, and the annotations cover safety. It does not specify the exact response format, but given the simplicity of the tool, that is not a major gap.

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

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

The input schema already provides full descriptions for all 7 parameters (100% coverage), so the baseline is 3. The description groups the parameters into categories (time, magnitude, circular area) but does not add significant meaning beyond what the schema already defines. The grouping is helpful but not essential.

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

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

The description clearly identifies the tool as counting earthquakes matching a filter, with the specific verb 'count' and resource 'earthquakes'. It distinguishes itself from sibling tools by explicitly stating 'without returning the events', making it clear that this is the counting counterpart to search_earthquakes.

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

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

The description provides a concrete use case ('how many M5+ quakes in the last month near X') and indicates that filters are the same as search_earthquakes, which helps an agent understand when to use this tool. However, it does not explicitly state 'use search_earthquakes when you need the event details', though the phrase 'without returning the events' implies 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?

The description richly discloses behavior beyond the readOnlyHint annotation: it performs parallel decomposition across 5,529 tools, returns gaps[] for unanswered facets, never invents findings, includes hop fields, contradictions[] for standard/thorough, semantic excerpting rather than head-truncation, and latency expectations. It also explains citation URIs are only present when resolvable. This far exceeds what annotations convey.

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

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

The description is dense and information-rich, with important caveats placed early (account requirement, not open-web search). It is longer than average, but every sentence provides operational or selection value—depth tiers, latency, citation resolvability, and sibling comparisons. A slight trim of repeated depth explanations could improve scannability, but the structure is logical and effectively front-loads critical constraints.

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 (2 params, no output schema, high-stakes research behavior), the description fully compensates: it explains return packets, gaps[], contradictions[], citations, hop semantics, latency, and account tiers. It also orients the agent with clear alternatives for out-of-scope use cases, making it 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?

Schema coverage is 100% and both parameters (question, depth) are well-documented in the schema. The description adds crucial context on how deep_research interprets depth values (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop) and clarifies that broad/multi-part natural language questions are acceptable, since decomposition is a feature. This adds semantic 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 clearly identifies the tool as grounded multi-source research over structured data sources, explicitly distinguishing it from open-web search and sibling tools like ask_pipeworx. It names the resource (1455 structured data sources, 5,529 tools) and the deliverable (findings packet), and contrasts with single-lookup alternatives.

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 for broad/multi-part questions, and explicit when-not-to-use guidance: prefer ask_pipeworx for single lookups and for breaking/current news topics. Also details depth-level nuances (quick/standard/thorough), and account requirements, all of which help an agent select this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context: returns top-N relevant tools, includes full schemas with examples, and 'each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations to describe output format and readiness.

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, with the main purpose front-loaded. The list of domains is long but purposeful, and the third sentence concisely explains the return value and usage pattern. No fluff, though the domain list could be trimmed 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?

For a tool with no output schema, the description fully compensates by explaining the return payload (names, descriptions, schemas, examples), the fact results are callable directly, and the recommended 'first step' usage. The domain list sets clear expectations for coverage. Completeness is high.

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

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

Schema coverage is 100% – all parameters (query, q, task, limit, search, description) have clear descriptions including defaults and aliases. The description's 'top-N' mirrors schema's limit but adds no additional parameter semantics. 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 uses a specific verb+resource ('Find tools by describing the data or task') and lists many concrete domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools by being the discovery/metacategory tool. It also clearly states what it returns (names, descriptions, full input schemas with curated examples), reinforcing purpose.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available' – gives clear when-to-use instructions and implies the alternative is to directly call a known tool. This strongly frames its place in the workflow.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantial context: it fans out across five sources, returns specific groups (e.g., 'recent_filings (up to 5 with pipeworx://... URIs)'), and discloses that patents soft-fail due to the 'USPTO PatentsView API sunset May 2025'. The GDELT→GNews fallback and single-parallel-call behavior are also transparently noted.

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

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

The description is long but densely packed. It starts with example queries, clearly states core function, then systematically lists sources and outputs. Though structured as a single paragraph, every sentence contributes valuable information, making it efficient for the complexity it covers. Minor improvement would be using bullet points, but it remains readable and 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?

There is no output schema, so the description must explain return values; it does so in detail by listing six output groups (cik+company_name, filings, fundamentals, patents, news, LEI). It also covers limitations (soft-fail patents, name unsupported, zero-padded CIK format) and performance characteristics (one parallel call). For a tool of this complexity, this is exceptionally complete.

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

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

Schema coverage is 100%, with both parameters fully described in the schema (type enum and value description). The description repeats the same examples and the resolve_entity pointer without adding new semantic detail beyond what the schema already provides. Therefore, the baseline of 3 is appropriate because the schema carries the parameter meaning.

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

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

The description clearly states the tool's purpose as 'full cross-source profile of a US public company' and supports it with representative queries like 'Tell me about X' and 'company profile for Microsoft'. It lists concrete sources and output fields, and distinguishes itself from siblings by explicitly preferring this over chaining single-pack lookups for holistic views.

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

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

Explicit 'when to use' guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear 'when not to use': names are not supported, directing the user to 'use resolve_entity first if you only have a name'. This directly addresses alternatives and exclusions.

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

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

Annotations already convey destructive and non-read-only behavior, so the baseline is met. The description adds a precondition ('previously stored') and a use case ('clear sensitive data'), but these are more contextual than additional behavioral traits. It does not contradict the annotations.

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

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

Two concise sentences fully cover the purpose, usage, and related tools. The description is front-loaded with the action and resource, with no wasted words.

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

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

For a simple one-parameter tool with strong annotations and no output schema, the description is complete enough. It covers when and how to use it, but does not explicitly mention the behavior for a non-existent key; this is partially covered by the idempotentHint annotation, so a small gap remains.

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, giving a baseline of 3. The description adds the semantic constraint that the memory must be 'previously stored,' implying the key must reference an existing memory, which provides extra meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Delete a previously stored memory by key.' It distinguishes itself from sibling tools by naming 'remember' and 'recall' as complementary actions, making the purpose unambiguous.

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

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

Explicitly provides when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools (remember and recall) to clarify the workflow, effectively guiding the agent on 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 declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds behavioral context by explaining the tool 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' and that output is a single text blob. This goes beyond the annotations' safety profile.

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

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

The description is three sentences, front-loading purpose and process. The use-case list is compact but adds value. No waste.

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 simple input-output profile. With no output schema, the description compensates by stating the output is 'a single text blob ready to drop at site-root/llms.txt' and explaining the extraction steps. Combined with full annotation coverage, this is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with both 'url' and 'max_links' having descriptions. The description does not add parameter-specific detail beyond the schema (e.g., it doesn't mention max_links), so the baseline of 3 applies.

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

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

The description uses a specific verb ('Generate') with a clear resource ('production-ready llms.txt file') and scope ('for any URL'). It also explains the extraction process and output, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), establishing clear context for when to use it. It stops short of naming specific alternatives but makes the tool's niche obvious.

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, and non-destructive behavior. The description adds that it is 'Keyless' and enumerates the specific data fields returned, providing context beyond the annotations.

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

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

The description is a single sentence with a clear structure: purpose, example, then a list of returned fields. It conveys all necessary information with no wasted words.

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

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

For a single-parameter read-only tool, the description provides a comprehensive list of return fields, notes keyless access, and the schema covers the parameter. No critical gaps remain for an agent to use it effectively.

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

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

The input schema already fully documents the single event_id parameter with an example. The description repeats the parameter semantics but does not add additional constraints, formatting details, or clarifications beyond the schema.

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

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

The description clearly states it retrieves full details for a single earthquake using a USGS event id. The verb 'Get' and the resource 'earthquake detail' distinguish it from sibling tools like search_earthquakes and count_earthquakes.

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 usage when the user has a specific USGS event id, which is clear. However, it does not explicitly mention alternative tools for searching or counting earthquakes, so it lacks explicit exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds value by listing specific return fields and clarifying that only active subscriptions are returned by default, aligning with the include_inactive parameter.

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 that front-load the purpose, then list return fields, then provide usage context. Every sentence earns its place without wasted words.

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

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

For a simple read-only list tool with one optional parameter and strong annotations, the description covers purpose, return fields, and usage context. No significant gaps remain.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3. The description's mention of 'active subscriptions' indirectly references the default behavior of include_inactive but adds no new details beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying the exact resource and verb. It also distinguishes itself from sibling tools like subscribe and unsubscribe by noting it's for reviewing and finding ids to cancel.

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

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

Provides clear when-to-use guidance: before adding more subscriptions or to find an id to cancel. It implies alternatives (subscribe/unsubscribe) without explicitly naming them, which would have made it 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 are all false and provide no safety guidance, so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota independence ('Free; doesn't count against your tool-call quota'), and the claim_token workflow ('Filing without an account returns a claim_token; pass it back later ... to read whether it was fixed and what changed'). This exceeds transparency expectations.

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

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

While long, every sentence earns its place. It front-loads the purpose, then provides conditional usage, exclusions, the claim-token flow, reader cadence, and rate limits without redundancy. No filler or repetition of schema details.

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

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

No output schema exists, so the description explains the return behavior: 'Filing without an account returns a claim_token' and that later calls with it return status and resolution details. It covers scope boundaries, feedback types, rate limits, and the optional context structure entirely, making the tool self-contained for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds genuine value beyond the schema, especially for claim_token: 'pass the pwfb_… token that filing returned, with no other arguments' and what it returns. It also clarifies message length ('1-2 sentences typical, 2000 chars max') and type semantics, pushing above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by scoping to Pipeworx tools and covering bug/feature/data_gap/praise, which no sibling 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?

Explicitly lists when to use (bug, feature, data_gap, praise) and when not to use: 'if the tool came from a different MCP server in your client ... we cannot fix it and reporting it here only delays you; file it with that server instead.' Also clarifies how to identify Pipeworx tools ('Pipeworx tool names are the ones this connection lists').

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, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: self-aggregating from CF analytics-engine, no PII, and caching behavior (5min-1h depending on window). This gives the agent expectations about freshness and privacy 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 well-structured: a clear opening statement, an enumerated 'useful for' list, and concise notes on data source, privacy, and caching. Every sentence adds value without redundancy, and it is front-loaded with the core function.

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

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

Despite lacking an output schema, the description specifies the return components (top tools, packs, call volume), the data shape (pack, tool, count), and behavioral nuances (caching, window meaning). Combined with thorough annotations and a simple schema, it fully covers what an agent needs to decide and invoke correctly.

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

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

Schema description coverage is 100% and the single parameter 'window' already includes semantic detail (default, meaning of shorter vs longer windows). The description reinforces this but adds no new param-level info beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb ('returns') and resource ('top tools, top packs, and total call volume') over a defined window, clearly distinguishing it from sibling tools like ask_pipeworx or discover_tools. It answers 'what does this tool do?' precisely.

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 three explicit use cases (discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs) that signal when to use it. However, it does not explicitly name alternatives or state when not to use it, though 'before asking your own question' implies a comparison to QA 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?

Beyond the annotations (read-only, open world), the description discloses rich behavioral detail: walks child markets, checks date-axis/threshold-axis ordering, computes partition sums, applies semantic anchor Jaccard similarity, filters placeholder slugs, and performs a fill check against live CLOB depth with the warning 'realizable_edge_pp ≤ 0 ... do not trade it.' No contradiction with annotations.

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

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

The description is long but well-structured with bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded purpose statement. Every sentence carries useful information, though it could be tightened for a perfect score.

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

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

This is a complex tool with no output schema, but the description fully covers the response shape (opportunities[], partition_check), edge cases (placeholder filters, low similarity), and trade advisories. It also mentions the alternative sizing tool, making it complete for an agent to decide and invoke correctly.

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

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

Although the schema already covers both parameters, the description adds substantial semantics: concrete examples like 'fed-decision-may-2026', explains the exact behavior in each mode, and notes that full Polymarket URLs are accepted. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' — a specific verb, resource, and method. It distinguishes this from sibling tools like polymarket_edges by focusing on arbitrage rather than just edges or tracking.

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

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

Explicitly describes three usage modes: no-args trending_scan, event mode, and topic mode, with clear recommendations ('event (recommended for a specific market)'). It also points to an alternative for sizing: 'For custom sizing use polymarket_fill_risk,' and explains the relative advantages of cross-event scanning.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: caching ('Cached 1h at the KV level keyed on all knobs'), diagnostic output to explain empty segments, per-model family logic, a 24h-move warning, and the specific caveat about Fed signal reliability. This is exactly the kind of context that helps an agent interpret results.

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

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

The description is long but well-structured with clearly labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loaded with the core purpose. While some details (like per-sport α values) could be seen as verbose, they support understanding of the output. It is appropriately sized for the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining the response structure. It fully covers top-level segments (by_segment, fed_candidates, _diagnostics), fields carried by every opportunity, and why segments may be empty. It also explains caching and limitations. This gives an agent everything needed to invoke and interpret the tool.

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

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

The input schema already documents all 9 parameters thoroughly (100% coverage), giving a baseline of 3. The description adds extra meaning by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining nuanced behavior (e.g., min_partition_leg_kelly applies to per-leg Kelly because parent-level Kelly is always 0 for partitions). This elevates it above 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also clarifies the intended use case ('what should I bet on today') and differentiates from sibling tools by focusing on Pipeworx-driven edge discovery rather than generic arbitrage or tracking.

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

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

It clearly states when to use the tool ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and gives behavioral expectations like 'rare-by-design' for concentrated longshots and the exclusion of Fed bets. However, it does not explicitly name alternative tools or state when NOT to use this tool, 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?

The description adds substantial behavioral detail beyond the annotations: explains snapshot timestamps are written on cache-miss, gaps indicate no scan, history is bounded by a 60-day TTL, decay is computed from daily closes net of slippage, and expired opportunities are tracked with lifespan. This goes far beyond the read-onlyHint and provides valuable 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?

Although longer than a typical description, every sentence earns its place: it is structured into purpose, parameter clarification, response schema explanation, and limitations. The information density is high, and the phrasing is front-loaded with the core question the tool answers.

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

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

For a tool with no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and including field-level details like trend, decay_pp_per_day, and lifespan_days. It also covers edge cases like missing snapshots and historical depth limits, making it complete for the tool's complexity.

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

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

Schema coverage is 100% and both parameters have descriptions, so the baseline is 3. The tool description adds value by clarifying that 'days' is a lookback and 'window' refers to the snapshot family (24hr/1wk/1mo), reinforcing the semantic meaning and tying them to the polymarket_edges concept.

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

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

The description clearly identifies the tool's purpose: tracking edge persistence and decay from daily polymarket_edges snapshots. It answers a specific trading question about how long an edge has existed and whether it is shrinking, which distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage that focus on current opportunities.

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 strong context on when to use the tool by framing it around the question of edge persistence versus freshness, and it explains the significance of edge age for trading decisions. It does not explicitly name alternative tools or say when not to use it, but the implied use case is clear enough for a 4.

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

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

With annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds extensive operational detail: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, per-leg fill detail, thin_legs, and forced_directional_risk. This far exceeds the annotations' baseline and aligns with them, though it doesn't address potential errors or rate limits, which is acceptable given the rich annotation set.

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

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

Although long, the description is tightly structured with labeled modes (SINGLE-MARKET, BASKET) and enumerates return fields. Every sentence carries operational weight—defaults, choices, risk warnings—without tautology or filler. The density is appropriate for a complex tool with dual modes and many outputs.

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 complex (two modes, 4 parameters, no output schema), but the description compensates comprehensively: it explains both modes, all parameters, all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk), and usage context. It is self-contained for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic depth by clarifying that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode (shares per leg, each paying $1 at resolution). It also documents the default size (1000) and clamp range, enhancing the schema's concise 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 states a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' and clearly delineates single-market vs basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than arbitrage detection or edge calculation.

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 prescribes when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional positions), going beyond simple timing to give strategic rationale.

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?

Even with readOnly/idempotent annotations, the description adds detailed behavioral context: it explains compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It discloses edge cases where spreads are meaningless, which is far beyond what annotations provide. No contradiction with annotations.

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

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

The description is long but dense, with each sentence carrying useful information. It is front-loaded with purpose and modes, then details response and safety fields. While lengthy, the structure is logical and justified given tool complexity, so it is not overly verbose.

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 structure: leg-by-leg prices, matched spreads, and safety fields. It covers the main use cases, edge cases, and limitations (temporal alignment, compatibility warnings). This is highly complete for a complex cross-venue tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by explaining how the `topic` parameter maps to macro shortcuts and how explicit `kalshi_event_ticker` and `polymarket_event_slug` override the mapped side. It clarifies the relationship between parameters and the two modes, enriching the schema descriptions.

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

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

The description states a specific verb+resource: it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes from sibling tools by emphasizing the two-venue comparison and the notion of spread. The two modes (topic and explicit) are clearly explained, making the purpose unambiguous.

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

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

The description gives clear context on when to use the tool: for comparing Kalshi vs Polymarket pricing on the same event, with two usage modes. It also offers strong when-not guidance, stating that most pre-mapped topics are not tradeable and that compatibility_warning indicates non-equivalent bet shapes. However, it does not explicitly reference alternative sibling tools or name conditions for switching.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond these: scoping by identifier ('anonymous IP, BYO key hash, or account ID') and the behavior of listing all keys when key is omitted. This is meaningful but not exceptionally detailed, so a 4 is appropriate.

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

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

Three sentences, front-loaded with the core action, no wasted words. It efficiently covers behavior, use case, scoping, and companion tools.

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 1-parameter tool with strong annotations and no output schema, the description is fully complete. It explains what the tool does, when to use it, how it is scoped, and its relationship to remember and forget.

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 baseline is 3. The description repeats some schema info ('omit the key argument') and adds a reference to the remember tool, but does not fundamentally exceed what the schema already documents.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb (retrieve) and resource (saved values/keys), and distinguishes it from sibling tools remember and forget.

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 to look up context the agent stored earlier...' and it explains when to use vs alternatives by mentioning 'Pair with remember to save, forget to delete.' This clearly positions the tool relative to its siblings.

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

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

The description says mark_read:true flags returned events read and changes future calls, which is a mutating side effect. This directly contradicts the annotations readOnlyHint:true and idempotentHint:true, which imply the tool is read-only and idempotent. This is a serious annotation contradiction.

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

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

The description is a bit long but front-loaded with the core action. It uses multiple sentences to convey return format, filtering, state-changing behavior, and alternative access. Some redundancy exists between 'Pull fired events' and 'Returns the most recent alerts', but overall it is structured logically.

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 feed-reading tool with no output schema, the description explains the returned event structure (source, citation_uri, raw payload), offers filtering options, clarifies mark_read side effects, and even provides an equivalent URL for scripts/dashboards. It covers all necessary usage context, with pagination/limit details available in the schema.

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

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

Schema has 100% coverage for all 5 parameters, so baseline is 3. The description adds meaningful context beyond the schema by explaining the effect of mark_read (next call shows only newer ones), giving a type example (sec_8k), and describing the returned event fields. This elevates it to 4.

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

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

The description clearly states the tool pulls fired events/alerts from the subscription feed, specifying the resource (persisted feed) and the action (pull/return). It distinguishes from siblings like list_subscriptions (which lists subscriptions, not events) and recent_changes (likely a different feed).

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 implies use for retrieving and filtering alerts, with guidance on filtering by type/since and setting mark_read. It also notes polling is fine and mentions an alternative external endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like recent_changes, so exclusions are missing.

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?

Discloses internal behavior such as fan-out to multiple sources, GDELT→GNews fallback on rate-limits/5xx, and USPTO soft-fail after sunset. It also describes the return structure (changes[] grouped by source, total_changes count, and citation URIs), going beyond the annotations.

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

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

Every sentence in the description carries essential information: query intents, source details, fallback behavior, return format, and alternative tool. Despite length, it remains dense and well-structured.

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 sources, fallback logic, failure modes, return format, and provides clear alternative guidance. Given the tool's complexity and no output schema, it is sufficiently complete for an agent to invoke effectively.

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 description adds minimal extra parameter meaning. It does include a helpful usage tip for 'since' ('Use 30d or 1m for typical monitoring'), but the schema already documents accepted formats and 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 clearly states the tool's purpose: a change feed for a company in the last N days/weeks/months, covering filings, news, and patents. It explicitly distinguishes from sibling tool entity_profile by noting to use that instead for static profiles.

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 specific guidance on when to use this tool (recent changes) and when to use entity_profile (static profile). It also recommends typical monitoring values like '30d' or '1m' and explains fallback behavior for news sources.

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

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

While annotations already indicate the tool is idempotent (idempotentHint=true) and not destructive (destructiveHint=false), the description adds valuable behavioral context: persistence differences between authenticated (persistent) and anonymous (24 hours) users, and key-value storage scoped by identifier. It does not contradict any annotations.

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

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

The description is four sentences, each earning its place: purpose, usage trigger, storage behavior, and pairing with siblings. It is front-loaded with the core function and avoids fluff or repetition of schema details.

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

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

For a simple save tool with two well-documented parameters, the description covers purpose, usage, persistence semantics, and sibling relationships. It does not describe the return value, but that is often unnecessary for a store operation. The omission of overwrite behavior (what happens when key exists) is a minor gap given the tool's simplicity.

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

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

Schema coverage is 100% with key and value both already described with examples. The description reinforces the key-value nature but adds no new parameter meaning beyond what the schema provides. Baseline for high coverage is 3, and the description earns that baseline without elevating it.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later.' It also distinguishes from siblings by explicitly mentioning recall for retrieval and forget for deletion, and provides concrete examples like 'resolved ticker' and 'user preference'.

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

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

The description gives explicit usage guidance: 'Use when you discover something worth carrying forward...' This clarifies when to invoke the tool versus alternatives. It further reinforces by pairing with recall and forget, effectively defining the memory workflow and when each sibling 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses detailed behavior: identifiers are labelled with source, unresolved identifiers are explicitly listed rather than omitted, and LEI/FIGI enrichment degrades gracefully with EDGAR identifiers still returning if downstream providers fail. This adds significant contextual value.

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, opening with user-intent examples and then systematically covering purpose, supported types, sources, and degradation behavior. Every sentence contributes useful information, though it could be tightened slightly without losing clarity.

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

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

Given the tool's complexity (two entity types, multiple external sources, cascading lookups, fallback behavior), the description is remarkably complete. It covers input variations, output identifier types, source attribution, unresolved handling, and graceful degradation—all without an output schema. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% and includes examples, so baseline is 3. The description enriches semantics by detailing what each type resolves to (e.g., company returns CIK, ticker, name, LEI, FIGI; drug returns RxCUI, ingredient, brand) and the exact accepted value formats (ticker, CIK, name for company; brand/generic for drug). This adds meaning beyond basic 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 clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes multiple user-intent examples and distinguishes itself from siblings by being the 'FIRST' step for name-to-ID lookup, supporting company and drug entity types with specific identifier sources.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is clear usage guidance. It also notes that it replaces 2-3 manual lookups. However, it does not explicitly name alternative sibling tools or state when to avoid using this tool, though implications are present.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond this by stating it probes each entity via ai_visibility_check, ranks results, and returns score/confidence/signal density. This gives the agent a clearer picture of what happens during execution 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?

Three sentences deliver a wealth of information: the core action, the underlying mechanism, the ranking behavior, a concrete use case, and the return format. No redundant words or filler. The most important information is front-loaded.

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

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

Despite having no output schema, the description explicitly states what is returned (ranked list with score, confidence, signal density per entity). It also explains the probe mechanism, the subject-first ordering, and the intended use case. Combined with a fully documented schema and appropriate annotations, this gives the agent everything needed to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not significantly expand on parameter semantics; it only mentions 'your brand + N competitors' which is already reflected in the entities parameter description. The output details are useful but not parameter-specific, so no extra credit beyond baseline.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check by emphasizing multi-entity comparison, ranking, and surfacing most/least recognized. The example use case further clarifies its unique role.

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 context: competitive AI-marketing audits, with an illustrative question. It implies when to use it (comparing multiple entities) but does not explicitly mention alternatives or when not to use it. Since it references ai_visibility_check, an agent might infer that single-entity checks are handled elsewhere, but the exclusion is not stated.

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive. The description adds extra behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list it if it times out. This goes well beyond the safety profile provided by annotations, helping the agent set expectations and handle delays.

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

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

The description is dense but well-structured. It leads with the core purpose, then usage guidance, return contents, ecosystem scope, and failure behavior. Every sentence adds value; despite its length, it avoids redundancy and remains thoroughly readable. The format allows quick scanning of the most critical information.

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

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

Given the tool's complexity (two external data sources, multiple output categories, partial-failure behavior), the description covers all essential aspects: what it returns (summary block, per-advisory detail, links, alternatives), the NPM-only limitation, and failure handling. No output schema exists, so the description carries the full burden of explaining outputs, and it does so thoroughly.

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

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

The input schema already documents both parameters (package and version) with descriptions, achieving 100% schema coverage. The description does not add additional parameter-level semantics beyond what the schema provides; it only mentions them implicitly in the context of usage. For a schema with full coverage, a baseline score of 3 is appropriate, as 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 this is a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It explicitly lists the categories of information gathered (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), making the tool's purpose unmistakable and distinguished from any sibling tool for dependency analysis. The resource (npm package) and action (scan) are specific and concrete.

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

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

The description gives explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides exactly the type of when-to-use and alternative guidance needed, including what not to use it for.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context: 'Keyless' (no API key required), real-time and historical coverage, and the compact list return format. No contradiction with annotations, and the added keyless disclosure is a genuine behavioral trait not captured 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 with no filler. It is front-loaded with the primary action and resource, conveys the key filtering capabilities, mentions the return fields, and adds the keyless note. Every sentence earns its place.

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

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

With 11 parameters but all optional and fully described in the schema, plus an output schema present, the description provides sufficient context. It communicates the catalog source, filter types, return summary, and keyless access. It does not need to explain defaults or return value structure since those are covered by the schema and 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?

Schema description coverage is 100%, with every parameter documented. The description summarizes filter categories (time window, magnitude, depth, circular area) which helps group the parameters, but adds little new meaning beyond the schema's own per-parameter descriptions. Baseline 3 is appropriate given the high schema coverage.

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

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

The description states 'Search the USGS earthquake catalog...' with a specific verb and resource, and clarifies the return type as a compact list with magnitude, location, time, etc. This clearly distinguishes it from sibling tools like count_earthquakes and get_earthquake.

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

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

The description clearly implies the use case for querying seismic events with filters (time, magnitude, depth, area) and returns a list of quakes. While it does not explicitly name alternative sibling tools or when not to use it, the 'compact list' wording and filter scope provide 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?

Even though annotations already provide readOnly/openWorld/idempotent hints, the description adds significant behavioral detail: embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flag, and the return of character offsets and similarity scores. It also mentions the ability to verify verbatim quotes—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 slightly long but every sentence carries distinct information: purpose, use case, pairing, technical mechanism, and limits. It is front-loaded with the core purpose in the first sentence and avoids redundant phrasing. Would earn 5 if slightly trimmed of minor technical details that could be inferred.

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 retrieval tool with no output schema, the description explains the return format (passages with offsets and similarity scores), states input cap and truncation behavior, and covers the main use case. It also contextualizes the tool within the sibling ecosystem (ask_pipeworx_grounded) and explains the algorithm. This is complete enough for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by giving concrete examples for the 'text' param (SEC 10-K body, article, long tool result) and example queries for 'query' (supply-chain risk, fiscal year revenue). It also clarifies the 'limit' param's role implicitly via 'top-N passages' and the default. This goes beyond mere schema labels.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which names the specific verb, resource, and scope. It clearly distinguishes itself from sibling tools by contrasting with ask_pipeworx_grounded and emphasizing it operates on already-fetched text rather than fetching or grounding over whole documents.

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 the record is too big to cram into the prompt' and notes it 'saves context.' It also names the alternative approach (ask_pipeworx_grounded) and explains the intended pairing ('fetch with the gateway, ground over the relevant passages'), giving concrete usage context.

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

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

Adds substantial behavioral context beyond annotations: OAuth account requirement, returns new subscription id, phone verification with a daily cap, webhook HMAC signing, and auto-disable after 10 failures. 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?

Dense but well-structured; purpose, auth requirement, types, and delivery channels are each covered in a logical order. Every sentence contributes value 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?

Very thorough for a 3-param nested tool: covers auth, return value, type examples, and delivery behavior. However, the description lists only three of the five supported types (omits patent_grant and clinical_trial), which the schema covers but may reduce agent awareness of all options.

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 already 100%, but the description adds examples for each type (e.g., 'items:["5.02"] = officer change') and expands on delivery semantics (email templating, SMS verification, webhook details), giving meaning well 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?

Description starts with 'Create a proactive monitoring subscription to a live-data event stream.' Uses a specific verb 'Create' with a clear resource 'subscription', and differentiates from siblings like unsubscribe and list_subscriptions.

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

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

Clearly states when to use (creating subscriptions) and details delivery channel options (feed, email, sms) with prerequisites. Does not explicitly name alternative tools or say 'when not to use', but the context is strongly implied enough for an agent to select it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context by explaining the output (category-bucketed example questions with tool+argument shapes), the source (live catalog), and the optional topic filtering. 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 longer than many, but every sentence serves a purpose: example queries, the return type, the tool-source context, and usage instructions. It is front-loaded with practical questions and structured logically from purpose to invocation.

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 single optional parameter and no output schema, the description is fully complete: it explains what the tool does, when to use it, how to call it with or without arguments, and what the output contains. No important gaps remain.

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

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

Schema description coverage is 100%, with a clear description for the optional `topic` parameter. The description reinforces the parameter meaning with examples ('finance', 'pharma', 'betting') and clarifies the no-argument behavior, but it adds only marginal value beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape needed to answer them. It is specific about the resource (Pipeworx's live catalog) and distinguishes itself from siblings by framing itself as the 'FIRST' tool to use when unfamiliar with Pipeworx.

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 this FIRST when you do not yet know what Pipeworx can do for you,' providing strong usage context. It also gives example queries and mentions that it can teach how to call meta-tools. However, it does not explicitly name alternate tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds valuable context beyond annotations: ownership enforcement and that the row is deactivated (not deleted) preserving historical events. This aligns with destructiveHint=false and provides extra behavioral nuance. No contradiction.

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

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

The description is three sentences, each delivering distinct value: action, constraint, and side-effect. It is front-loaded with the action and has zero fluff or redundancy.

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

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

For a single-parameter cancellation tool with good annotations, the description covers the key aspects: what it does, who can use it, and the subtle non-deletion side effect. It is complete enough for an agent to select and invoke correctly without needing return-value details.

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 'id' already described as 'Subscription id (uuid) returned by subscribe.' The description only restates 'by id' without adding new semantic detail. Baseline 3 is appropriate since the schema carries the parameter meaning fully.

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 action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by emphasizing the cancellation action and the ownership constraint. No 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 description implies usage context: you can only cancel your own subscriptions, which gives a clear prerequisite. It also explains the effect (deactivated, not deleted) relevant for choosing this over deletion tools. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so a 4 is appropriate.

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

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

Beyond readOnlyHint and idempotentHint, the description explains the critical semantic of could_not_verify (check did not happen, not evidence) and unsupported, plus the two execution paths (SEC EDGAR fast path vs grounded pipeline). This is substantial behavioral disclosure that prevents misuse.

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

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

The description is long but well-structured, with front-loaded trigger phrases, a clear purpose, and a crucial warning. Every sentence adds value, though it could be slightly tighter.

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

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

For a tool with no output schema, the description covers the return values (verdict, value, citation, reasoning), special verdict meanings, and routing behavior. It fully compensates for the lack of an output schema and leaves no major usage question unanswered.

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

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

Schema coverage is 100% with detailed descriptions for claim and tolerance_pct. The description mentions 'exact percent-delta math' but does not add parameter-specific details beyond the schema, so baseline 3 applies.

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

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

The description opens with concrete trigger phrases and states 'natural-language claim verification against authoritative sources.' It clearly defines the tool's scope (financial vs other claims), lists verdicts, and distinguishes itself from multi-call pipelines, making it unmistakably specific.

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

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

Provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the automatic routing for financial vs non-financial claims, though it does not name alternative tools or explicitly state 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.