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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns structured answers with citations but does not contradict the annotations, so transparency is solid.

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

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

The description is verbose and somewhat repetitive, with phrases like 'PREFER OVER WEB SEARCH' and 'START HERE' appearing multiple times, and example lists duplicated. The core information is present but could be more tightly written.

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 gives sufficient context for deciding when to use the tool, including examples, alternatives, and news coverage. It does not describe the exact output format, but given the open-ended nature and lack of output schema, this is acceptable.

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

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

All six parameters are documented as aliases for 'question', and the question parameter description explicitly lists accepted aliases (query, q, prompt, text, input). Schema coverage is 100%, so parameter semantics are fully clear.

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 this tool routes questions to authoritative data sources and returns structured answers with citations. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

The description provides explicit guidance on when to prefer this tool over web search (for current/historical data, factual questions) and when to use alternatives (grounded for single answers, deep_research for broad questions). It also notes its news handling, leaving no ambiguity about usage.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond annotations: no candidate routing improvement is currently active, the tool matches ask_pipeworx exactly today, and its results feed merge decisions against the stable router.

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

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

The description is dense but every sentence earns its place: beta status, parity, usage condition, current candidate state, and experimental nature are all front-loaded. There is no redundant restating of the tool name or 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?

Given the tool is a complex universal router with no output schema, the description appropriately states it has the same response shape as ask_pipeworx and is a full working router. It could describe the response format slightly more, but the explicit sameness to the stable sibling makes it sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, with all six parameters and their aliases documented in the schema. The description only says 'same arguments', which adds no semantic value beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states this is the beta variant of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes the tool from its stable sibling and explains the current parity, leaving no ambiguity about what the tool does.

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

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

It explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, and references comparison against the stable router. It does not explicitly mention ask_pipeworx_grounded or state scenario exclusions, but the stable-vs-beta distinction is clear enough for correct selection.

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

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

The description goes well beyond the annotations by disclosing the refusal behavior, the exact refusal_reason enum values, and the structured success response. It also states that answers are extracted using ONLY the tool result, and that grounded mode costs an extra LLM call. These are important behavioral traits not captured by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

The description is dense but well-organized, front-loading the core purpose, then explaining routing, return behavior, and usage guidance in a logical flow. Every sentence contributes essential information, and the cost comparison with ask_pipeworx earns its place. It is long only because it packs genuinely useful detail.

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

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

Despite lacking an output schema, the description fully specifies the success return shape, refusal shape, refusal reason categories, and high-stakes use cases. It also explains the relationship to ask_pipeworx and when to prefer the cheaper sibling. For a single-parameter tool with rich behavioral nuance, this is complete.

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

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

The input schema already covers all six parameters, with 100% description coverage, documenting 'question' and its aliases. The description adds context about the question being routed and grounded, but does not add new parameter-level semantics. A baseline score of 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description clearly identifies the tool as a hallucination-resistant, grounded answer mode for high-stakes reads, using a specific verb ('extracts the answer') and a concrete resource. It explicitly distinguishes itself from ask_pipeworx by emphasizing that answers are drawn only from tool result content. This lets an agent immediately understand what the tool does and how it differs from its sibling.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. It also names ask_pipeworx as the alternative for casual lookups and explains the cost tradeoff. This fully routes an agent to the correct tool.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is for added context — and the description delivers extensively: auth/tier gating (thorough needs a paid plan), latency expectations (15-60s, up to ~90s), return packet shape (verbatim evidence + confidence + source + fetched_at + gaps[] + contradictions[] + hop + citation_uri), a hallucination guarantee ('never invented'), semantically-excerpted records (not head-truncated), and citation resolvability. This far exceeds the annotation baseline and materially shapes agent expectations.

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

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

The description is long (~250 words), but every one of its twelve sentences carries unique decision-relevant information and it is strongly front-loaded: the auth gate comes first, followed by core purpose, then exclusions, then depth semantics, then return details, then latency. Minor redundancy exists (the 'not open-web search' point appears twice), and the citation_uri sentence is convoluted and could be tightened, so it loses one point from perfection.

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 an extremely complex tool — no output schema, three depth modes, auth tiers, parallel decomposition across 5,804 tools, and a structured findings packet — the description is remarkably complete. It covers return shape (with field names), prerequisites and tier gating, latency, exclusions, alternative routing, and the hallucination guarantee. There is no output schema to fall back on, so the description's honesty about gaps[], contradictions[], and resolvable citations does essential work. Nothing material is missing for an agent to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3 — both question and depth are already well documented in the schema. The description adds non-redundant value: expected latency per depth tier, the 'broad/multi-part is fine' sweet spot reinforced with examples, and prose-level explanation of what each hop mode does and when the contradictions[] scan appears. It elevates parameter understanding beyond the schema's enum text.

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

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

The description opens with a precise verb+resource statement: 'Grounded multi-source research across Pipeworx's 1518 STRUCTURED data sources... in ONE call'. It then details the mechanism (decomposes question into facets, routes to 5,804 tools in parallel) and explicitly distinguishes itself from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx'. An agent cannot confuse this with ask_pipeworx, search_within, or validate_claim.

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

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

The description gives explicit when-to-use ('Best for broad/multi-part questions over structured data' with concrete examples), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even a fallback condition tied to auth state ('If you are not signed in, use ask_pipeworx instead'). This is the gold standard for routing an agent to the correct tool.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses soft-fail behavior for USPTO PatentsView, the meaning of empty FDA sections, and that sources_used/sources_failed reflect real no-data. It also specifies resolved:false with notes for private companies, giving the agent accurate expectations.

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

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

The text is long, but it is front-loaded with trigger examples and a routing directive, and the rest is dense with necessary output semantics. A bulleted structure would aid scannability, but every sentence contributes operational information.

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

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

With no output schema, the description carries full responsibility for explaining return values, and it does: it enumerates every returned field, explains edge cases (no FDA products, empty sections, failed sources), and covers accepted inputs. Nothing an agent needs to invoke it correctly appears missing.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds operational nuance: type values are interchangeable, value can be ticker/CIK/name, and names resolve via SEC EDGAR company-name match, which goes beyond the schema text.

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

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

The description opens with concrete trigger phrases and states a precise verb-object: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chained single-pack lookups and implies a single-entity scope that separates it from siblings like compare_entities and resolve_entity.

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

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

It gives an explicit 'ALWAYS PREFER' instruction for holistic-view requests and explains when name resolution succeeds or fails, including private-company behavior. It does not name sibling tools as alternatives, but the guidance around prefer-over-chaining and accepted inputs is clear enough for routing.

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

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

Annotations already 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing matching methodology (keyword and word overlap, not shared resolution source), the gross-vs-net fee caveat, the fact that 'unknown' legs are never paired, and the meaning of temporal_alignment_unknown versus confirmed alignment. These are substantial behavioral details that materially affect interpretation of 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-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Each sentence carries substantive caveats or behavioral disclosures, though some points are repeated (e.g., EITHER mode, matching method) and the length could be trimmed without losing 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 there is no output schema, the description carries the full burden of explaining the response shape, safety fields, compatibility codes, skipped counters, and fee treatment. It covers what an agent needs to interpret results correctly, including non-obvious warnings like compatibility_codes being non-empty even when matched_pairs > 0.

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 describes all three parameters with 100% coverage, and the description adds significant interaction semantics: topic is a pre-mapped shortcut list, explicit ticker/slug overrides the topic-mapped side, and both modes run the identical matcher. This clarifies how parameters combine, which the schema alone does not convey.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, and it explains the two modes ('topic' shortcuts and explicit ticker/slug pairings). However, it does not explicitly name sibling tools such as polymarket_arbitrage or state how this differs from them, so the differentiation is implicit rather than 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 gives strong situational guidance: when to use pre-mapped topics versus explicit pairings, and it warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped does not mean tradeable. It does not explicitly contrast this tool with sibling alternatives like polymarket_arbitrage or polymarket_edges, so alternative-routing guidance is 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?

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?

Despite the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral detail: behavior on ambiguous matches (returns figi_candidates), explicit listing of unresolved identifiers under `unresolved`, graceful degradation when GLEIF/OpenFIGI is unavailable, and the nuance that issuing entity resolution via ISIN covers non-US issuers. These go well beyond the static 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 purposeful information. Every sentence provides distinct value—supported types, identifier sources, fallback behavior, and usage caveats. It is structured logically: opening question examples, type-specific details, then operational notes. No fluff or repetition, making it 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?

Given there is no output schema, the description must explain what the tool returns. It does so thoroughly: identifiers with source labels, `figi_candidates` for ambiguity, `unresolved` for failed resolutions, and fallback behavior. It covers input validation (entity name only) and edge cases (non-US issuers). All necessary operational details are present for an agent to call and interpret results correctly.

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

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

The input schema covers 100% of parameters with descriptions, but the description adds extra semantic guidance: detailed input formats (e.g., 'AAPL', '0000320193'), the instruction to pass only the entity name and not full noun phrases, and the specific types of values expected per type. This enriching detail helps agents avoid common errors.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to canonical/official identifiers, with specific verbs like 'resolve' and lists of example queries ('What's the ticker for…', 'find the CIK for…'). It distinguishes itself from sibling tools by explicitly naming supported types (company, drug) and the identifier sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm). This is clearly distinct from other tools like entity_profile or compare_entities.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also describes the cascading lookup as replacing 2-3 manual lookups, setting clear expectations. It explains when to use company vs drug types and how to handle ambiguous names. While it doesn't explicitly list 'when NOT to use', the strong directive and input constraints effectively cover usage conditions.

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.