Macrostrat

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds valuable behavioral context beyond annotations: the default free model, BYO-key billing implications, and the per-model return payload.

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 long, front-loads the primary purpose, and packs essential details without redundancy. Every sentence contributes new information about the tool's function, configuration, output, and use cases.

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 four parameters and no output schema, the description compensates by explaining the return structure (per-model {score, confidence, signals, raw_response} + combined view) and covering the key configuration/billing aspects. For a tool of this scope, it is adequately 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 has 100% coverage for all four parameters, so the description doesn't need to redefine them. It adds semantic value by noting the default model is 'Workers AI Llama-3.3-70b (free)' and that passing `_apiKey` incurs direct Anthropic charges, which is not captured in the schema.

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

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

The description clearly states it 'Probe(s) one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model,' which is a specific verb+resource action. However, it does not explicitly differentiate from closely related sibling tools such as scan_competitor_ai_presence, so it lacks full sibling distinction.

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 identifies concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs Anthropic model choice. It does not mention when to prefer this over related tools, but it provides clear context for when the 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 (readOnlyHint, openWorldHint, destructiveHint false) already cover the safety profile, so the bar is lower. The description adds that it routes to many toolsheb, fills arguments automatically, and returns structured data with stable citation URIs. It doesn't disclose rate limits or auth, but for a read-only query tool that's acceptable. Adds value 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?

Long but well-structured, front-loaded with 'PREFER OVER WEB SEARCH' and includes examples and alternatives. Every sentence adds value; 4.

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

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

Describes output (structured answer with stable citations), mentions routing to 5,581 tools, and alternative tools for different scenarios. Doesn't describe pagination or rate limits, but for a query tool, this is adequate.

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

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

Schema coverage is 100% with property descriptions. The description itself says the question is in natural language and accepts aliases, but the schema already describes this. No additional param semantics beyond schema.

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

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

The description clearly states the tool answers questions by routing to 5,581 tools across 1,463 verified sources and returning structured answers with citation URIs. The verb 'routes' and the resource scope are explicit; the contrast with web search and dedicated alternatives like ask_pipeworx_grounded makes its purpose distinctive.

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

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

Explicitly says 'PREFER OVER WEB SEARCH for questions about...', lists example topics, and distinguishes when to use grounded vs fan-out alternatives. It even gives 'START HERE' guidance and names sibling tools with 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?

The description adds valuable context beyond the annotations: it is a live experimental variant, candidate improvements are enabled only when under test, none are currently active so it matches ask_pipeworx exactly, and it is a full working router rather than a stub. This is honest and useful for an experimental tool.

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 front-loads the core identity and then efficiently covers live status, usage, and fallback behavior. It is a bit longer than strictly necessary, with details like the retirement date, but every sentence contributes meaningful 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 annotations cover safety and idempotency, the description covers the essential behavioral context for a beta router: experimental status, current equivalence to the stable version, and no fallback. The lack of an output schema is partially mitigated by the statement that the response shape is identical to ask_pipeworx, though this assumes familiarity with that sibling.

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 question fully described and five aliases each documented as 'Alias for question.' The description adds no parameter-specific detail, simply saying 'same arguments' as ask_pipeworx, so it relies on the schema, which is adequate but not enhanced by the description.

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

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

The description states this is a beta version of ask_pipeworx, an identical universal router with the same 5,581 tools, arguments, and response shape, and frames it as the experimental edge for routing. It clearly differentiates from the stable ask_pipeworx and from grounded variants, though it still relies on the reader knowing what ask_pipeworx itself 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 you want the newest routing, which is a clear when-to-use condition. It does not explicitly state when not to use it or name alternatives such as the stable ask_pipeworx, but the contrast with the stable router is strongly implied.

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

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

The annotations already mark readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral detail: the tool extracts answers solely from tool results, returns verbatim evidence, and returns explicit refusal reasons when data is insufficient. This goes well beyond what annotations and schema provide.

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

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

The description is dense but every sentence earns its place: core purpose, routing behavior, return shape, refusal reasons, use cases, and cost trade-off. It front-loads the most important grounding guarantee before moving into 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?

Even without an output schema, the description fully specifies the success and refusal return shapes, enumerates refusal reasons, and explains the relationship to ask_pipeworx. The input schema covers parameters, and annotations cover safety, making the tool fully callable based on this description alone.

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

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

Schema description coverage is 100%, so the schema fully documents the question parameter and its aliases. The description adds context about routing and grounding but does not need to repeat parameter details. Baseline 3 is appropriate because the schema carries the parameter-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 states exactly what the tool does: it is a hallucination-resistant answer mode that routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. It clearly distinguishes this tool from its sibling ask_pipeworx by emphasizing groundedness and explicit refusal behavior.

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

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

The description gives explicit when-to-use guidance: use it when answers will be quoted, cited, or acted on and hallucination is unacceptable. It also tells the agent to prefer ask_pipeworx for casual lookups due to the extra LLM call cost, clearly routing between alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, but the description goes far beyond that. It discloses resolution logic (market_match_confidence, market_match_score, alternatives, suggestions), safety mechanisms (short-circuit with status:"low_confidence_match", market_closed_or_inactive, tradeability:"illiquid_wide_spread"), news fallback fields (_fallback_attempted, _fallback_failed_reason, retry_after_sec), and resolution-rule risk (cancellation_rule parsing). This is rich behavioral context that the annotations don't provide.

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

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

The description is long and dense, but structurally organized into clear blocks (classifiers, fan-out examples, response shapes, resolver contract, parent-event extractor, news fields, safety, resolution-rule risk). It is front-loaded: the first sentence states the core purpose and the following sentences elaborate on behavior. While every sentence adds some value, there are arguably a few verbose phrases (e.g., the anecdote about 'audited arb-bot ledgers') that could be trimmed, keeping it from a perfect 5.

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

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

This is a complex tool with no output schema, so the description must carry the full burden of explaining return values and edge cases. It thoroughly covers result.market, result.analysis, result.evidence, resolver contract fields, parent_event extractor, news fields, and all blocking/suppression statuses. It even explains the interplay between closed/dead markets and the low_confidence_match path. For the complexity level, this description is exceptionally complete.

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

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

The input schema already has full coverage (100%) for all three parameters, so the baseline is 3. The description adds extra operational semantics: it explains the effect of include_raw on response size (~20KB vs 50-500KB), specifies the default for depth (thorough), and gives concrete examples for the market parameter (slug, URL, question). This goes beyond simply restating the schema, though much of the parameter meaning does live in the schema.

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

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

The description opens with a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It goes on to explain the tool resolves the market, classifies the bet, fans out to category-specific data packs, and returns an evidence packet plus market-vs-model comparison. This clearly distinguishes it from siblings like polymarket_arbitrage or ask_pipeworx, and the explicit use cases ("should I bet on X", "what does the data say about Y", "is there edge in Z") reinforce 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 explicit when-to-use guidance via the use cases and numerous category examples (BTC, Fed, Hormuz, Yankees, etc.). It also gives when-not-to-trust guidance (low-confidence matches, closed/inactive markets, wide-spread illiquidity). However, it does not name alternative sibling tools directly (e.g., no 'use polymarket_arbitrage instead'), so it stops short of the full 5-level criterion of explicit 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 readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral details: specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data with citation URIs.

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, front-loading trigger phrases and purpose. Each sentence provides useful details for a complex tool, though some might find it slightly long.

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

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

Despite lacking an output schema, the description explains the return format (paired data + citation URIs) and sorting behavior. It also covers both entity types' data fields and mentions efficiency gains, making it highly complete for a read-only 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 covers 100% of parameters with descriptions, and the tool description adds richness by explaining what data each type pulls and giving example inputs (e.g., 'AAPL','MSFT'), which clarifies the expected values beyond the schema's basic definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific trigger phrases. It also distinguishes itself from sequential single-pack lookups by explicitly saying to prefer this tool when comparing entities.

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

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

The description provides explicit trigger phrases and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear context for when to use. However, it does not name a specific alternative tool, only referring generically to 'sequential single-pack lookups.'

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

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

The description reveals behavioral traits beyond the annotations: it is 'NOT open-web search', it returns a findings packet with citations, it reports gaps[] rather than inventing answers, it includes contradictions[] in deeper modes, and it semantically excerpts large records. The account/plan limitation is also disclosed. No contradiction with the read-only/open-world/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 long but densely presented, with no filler. It front-loads the account warning and a semantic contrast, while latencies, gap-recovery behavior, and citation semantics follow logically. The length is justified by the tool's procedural complexity, though some redundancy exists (e.g., 'gap-recovery hop' repeated) that could be trimmed.

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

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

Given the tool's complexity and lack of a separate output schema, the description is remarkably complete: it explains what the tool does, when to use it, how to invoke it with depths, the qualification for 'thorough', what output to expect (findings packet with citations, gaps, contradictions, hop field, citation_uri), expected latency, and alternatives. Effectively covers all requirements for safe and 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?

Since schema description coverage is 100%, the baseline is 3. The description adds meaningful extras: depth named, the plan requirement for thorough mode, and notes that question phrasing can be broad since decomposition is the point. It does not restate schema contents, and its extra details are relevant to usage.

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

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

The description states a specific verb+resource: grounded multi-source research across 1463 structured data sources, decomposed into facets and routed in parallel. It explicitly differentiates from open-web search and from sibling ask_pipeworx by describing its unique research-vs-lookup scope.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx if not signed in, use ask_pipeworx for single lookups, use deep_research for broad/multi-part questions. It also names the exact alternative tool, leaving no inference required.

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 disclose safety traits (read-only, open-world, idempotent). The description adds useful behavioral details such as 'capped at 50 results' and 'Keyless' (implying no authentication), which go beyond the annotations. 'Keyless' is somewhat ambiguous but still informative.

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 short but redundant: 'returning lith_id, name, type, group, and class' is repeated verbatim in the second sentence. The standalone 'Keyless.' is cryptic and could be integrated more clearly. Two sentences with repetition means not every part earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description sufficiently covers usage, return fields, and the result cap. The annotations cover safety, and the description covers functional behavior, making it complete for an agent to invoke correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value through concrete examples ('granite', 'limestone') for the 'lith' parameter and explains the behavior when omitted, which is more than the schema description 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 a specific verb+resource: 'Look up Macrostrat lithology definitions by name' and lists the return fields. It distinguishes itself from siblings by focusing solely on lithology definitions, which no sibling tool explicitly covers.

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

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

The description provides clear usage context with 'by name' and examples, and explicitly mentions that omitting 'lith' lists all lithologies. However, it does not mention alternatives or exclusions, 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?

The description adds valuable behavioral context beyond the annotations: it returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.' This discloses output format and convenience behavior, complementing the readOnly/idempotent hints without contradiction.

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

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

The description is efficiently organized: purpose, usage context, domain list, return behavior, and a directive to call first. Every sentence earns its place; the domain list is long but informative, not filler. It is front-loaded with the core action and remains scannable.

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

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

With no output schema, the description takes responsibility for explaining return values, and it does: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also covers the tool's role as an initial discovery step. For a simple read-only lookup tool, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema; the schema already explains 'query', 'limit', and aliases. The description's mention of 'top-N' correlates with 'limit' but does not clarify syntax or defaults beyond what the schema states.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by positioning itself as a meta-tool for discovering other tools, not answering a query directly. The list of domains (SEC, FDA, FRED, etc.) reinforces its unique scope.

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

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

Explicit guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to invoke it and frames it as a precursor to other tool calls, which is highly actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context: parallel fan-out across multiple sources, specific return structure, a degraded source (USPTO PatentsView API sunset with soft-fail), and a fallback chain (GDELT→GNews). No contradictions with annotations.

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

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

The description is a dense single paragraph, but every sentence earns its place: examples, prioritization, fan-out details, return fields, constraints, and known failure modes. It could be structured with bullets for readability, but for a complex tool the length is justified.

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

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

With no output schema, the description carries the full burden of explaining return values. It enumerates the exact fields returned (cik, company_name, recent_filings with URIs, fundamentals with specific metrics and sort order, patents with soft-fail, news via fallback, LEI via GLEIF) and covers input constraints and alternatives. This is complete for a multi-source read 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 schema already fully describes both parameters ('type' enum with only 'company', 'value' with ticker/CIK and name exclusion). The description reinforces with concrete examples ('AAPL', '0000320193') but adds no new semantic meaning beyond the schema.

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

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

The description uses a specific verb-phrase ('full cross-source profile of a US public company in ONE parallel call') and clearly differentiates from siblings like deep_research and compare_entities. Examples of user queries ('Tell me about X', 'research Acme', 'brief me on Tesla') ground the purpose, and the explicit 'ALWAYS PREFER' statement further disambiguates from chaining single-pack lookups.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use it ('names not supported (use resolve_entity first if you only have a name)'). It also names the alternative tool (resolve_entity) for the unsupported case, providing clear guidance.

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

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

Annotations already cover the read-only, idempotent, and non-destructive nature. The description adds value by noting 'Keyless' and listing the exact return fields, which provides useful behavioral 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?

Three concise sentences, front-loaded with the tool's purpose, and every sentence adds relevant information. No fluff or redundancy.

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

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

For a simple two-parameter read-only tool with no output schema, the description adequately covers what it does, the inputs needed, and the structure of the result. It is 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% with clear descriptions for both lat and lng. The description only repeats 'Provide lat and lng' without adding semantic meaning beyond what the schema already provides, earning the baseline score.

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

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

The description uses a specific verb 'List' with a clear resource 'stratigraphic columns' and geographic scope 'near a geographic point'. It distinguishes itself from siblings like find_units by explicitly naming the resource type.

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

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

States the required inputs (lat/lng) and notes that it is keyless, giving clear usage context. It does not explicitly name alternatives or exclusions, but the context is sufficient for a simple lookup 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 state readOnlyHint=true, destructiveHint=false, etc., and the description adds useful behavioral context beyond that: 'Keyless' (no authentication needed), 'North America and beyond' (geographic scope), and the return fields ('formation/group, stratigraphic column, bottom/top ages (Ma)...'). This adds meaningful operational knowledge 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 four sentences, each earning its place: purpose, input options, return values, and key facts (keyless, scope). It is front-loaded with the most important information and contains 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?

Given the absence of an output schema, the description adequately covers what the tool returns and general context (geographic scope, keyless access). It does not mention pagination or exact-match behavior, but with 6 optional params and examples in the schema, it is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the three search modes (lat+lng, strat_name, lith) and the optional age, but this adds little beyond what the schema already describes for each parameter (e.g., lit says 'Lithology to match'). The description does not provide additional semantic details about parameter behavior or combinations.

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 'Find geologic rock units from Macrostrat by location + age, by stratigraphic name, or by lithology,' which clearly specifies the verb (find), resource (geologic rock units from Macrostrat), and the three distinct search modes. This distinguishes it from sibling tools like define_lithology (which likely defines a lithology term) and find_columns (which finds columns), making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use the tool: 'Provide lat+lng (optionally with age...), or a strat_name (e.g. "Hell Creek"), or a lith (e.g. "granite")'. This gives clear context for input selection, but it does not explicitly mention exclusions or alternative tools, so it falls short of a 5.

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

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

Annotations already declare destructiveHint true and idempotentHint true. The description adds the context that the deletion targets 'a previously stored memory,' but does not provide additional behavioral nuance beyond what annotations cover, such as behavior for non-existent keys.

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

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

The description is two sentences, front-loaded with the primary action, and contains no redundant or tangential information. Every sentence earns its place.

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

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

For a simple one-parameter tool with robust annotations (destructive, idempotent) and no output schema, the description fully covers purpose and usage. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%; the key parameter is already described as 'Memory key to delete.' The description's 'by key' adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (store) and recall (retrieve).

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

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

It provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, offering relationship context without explicitly naming alternatives for non-use.

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

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

The description discloses the tool's behavior: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies that the output is 'a single text blob ready to drop at site-root/llms.txt.' This adds value beyond the readOnly/idempotent hints by explaining the process and output format.

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

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

The description is concise and front-loaded with the primary purpose. It uses two succinct sentences plus a list of use cases, with no wasted words. Every sentence earns its place.

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

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

The description fully covers the tool's function, process, output format, and use cases. Given the annotations (readOnly, idempotent, non-destructive) and the simple parameter schema, 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?

The input schema already provides full descriptions for both parameters (url and max_links), including default and max values. The description adds no new detail about parameter semantics beyond what the schema covers, so a 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 the tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the input (a URL) and the output (a text blob in llms.txt markdown format). It also differentiates from sibling tools by mentioning the fetch/extract/emit process and specific use cases like 'drafting llms.txt for your own project.'

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 'Useful for' list with concrete scenarios: getting a client's site indexed, drafting for a project, or auditing a competitor. It does not explicitly mention alternatives or when not to use this tool, but the use cases are clear and contextually grounded.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is well covered. The description adds value by listing return fields and stating the 'caller's' subscriptions scope. However, it doesn't disclose more complex behaviors like how include_inactive affects the 'active' qualifier.

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, zero wasted words. The action, output, and use cases are all present in a compact form.

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 listing tool with one optional parameter and no output schema, this description covers the core purpose, return format, and usage intent. The only minor gap is not explicitly mentioning the include_inactive behavior, but the schema fills that.

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

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

The input schema has only one optional parameter (include_inactive) with a complete description, so schema coverage is 100%. The tool description doesn't need to elaborate further, but it also doesn't add any additional context about this parameter.

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

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

The description opens with 'List the caller's active subscriptions' – a specific verb, resource, and scope. It also enumerates the return fields, which clearly differentiates it from sibling subscribe/unsubscribe tools.

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

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

The second sentence gives explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This implies when to use in relation to subscribe/unsubscribe, though it doesn't name alternatives explicitly.

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, so the description carries the full burden. It discloses that filing without an account returns a claim_token, and explains the follow-up workflow to read status and fixes. It also mentions rate limiting ('Rate-limited to 5 per identifier per day') and that it is free and doesn't count against quota, adding behavioral context beyond the schema.

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

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

The description is dense but well-structured: it opens with purpose, then usage, exclusions, token workflow, and practical notes (rate limit, quota). Every sentence adds value, though it is slightly long. It remains appropriate 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?

There is no output schema, so the description needs to explain return behavior. It does: 'Filing without an account returns a claim_token' and later 'returns the status and, once resolved, what actually changed.' Combined with the schema's parameter descriptions and the explicit usage/exclusion guidance, the description is complete for an agent to correctly select and invoke the tool.

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

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

The schema covers 100% of parameters with descriptions, but the description adds semantic value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users to describe issues in terms of Pipeworx tools/packs, which aligns with the 'context' parameter. This goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs and resources, and explicitly distinguishes this from sibling tools by stating it is ONLY for tools served by this Pipeworx connection, not other MCP servers.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.'

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, and non-destructive behavior. The description adds valuable context: data source ('CF analytics-engine'), privacy guarantee ('no PII'), response structure ('(pack, tool, count)'), and caching behavior ('Cached 5min-1h'). This exceeds what annotations provide.

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

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

Four sentences with a clear flow: what it does, use cases, technical caveats. The bullet-style 'Useful for' list improves scannability, and every sentence contributes unique information without redundancy.

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

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

Despite having no output schema, the description tells the agent exactly what the response includes (top tools, top packs, total call volume), how the data is derived, and privacy/caching details. This fully covers the tool's low-complexity contract.

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 'window' parameter, with the schema itself already explaining enum values and window semantics. The description only mentions the windows parenthetically and does not add deeper syntactic or format 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 states exactly what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb and resource, and the phrase 'What other AI agents are calling on Pipeworx right now' clearly distinguishes it from siblings like ask_pipeworx and discover_tools.

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

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

The description provides three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It clearly implies when to use this tool before other actions, though it does not name alternative tools for contrast.

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 (readOnly, openWorld, idempotent). It discloses the fill-check logic (realizable vs theoretical edge, thin_legs), the semantic anchor threshold (≥0.30 Jaccard), the placeholder filter (>20% drop), and warns 'do not trade it' when realizable_edge_pp ≤ 0. These are important behavioral traits not inferable from annotations.

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

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

The description is long but every sentence earns its place, covering modes, filters, response format, and fill check in a structured, front-loaded manner. It avoids redundancy and is organized logically—each section (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) adds essential detail without fluff.

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

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

With no output schema, the description fully compensates by specifying the response format: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge-case behaviors and fill-check nuances, making the tool's behavior fully transparent 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?

Although the schema already covers both parameters (100% coverage), the description adds substantial value: concrete event slug examples ('fed-decision-may-2026'), acceptance of full URLs, seed question examples for topic, and explains what each mode does with parameters. This enriches the parameter semantics beyond 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 opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', which is a specific verb, resource, and method. It clearly differentiates from sibling tools like polymarket_edges (edge detection) and polymarket_fill_risk (fill risk), while also detailing three distinct modes (trending_scan, event, topic) that define its scope.

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

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

Explicit usage guidance is given: 'Call with NO args for a `trending_scan` of the top ~200 markets by weekly volume; pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It even recommends which mode to use for a specific market and directs to sibling tool polymarket_fill_risk for custom sizing. This is clear when-to-use and alternative 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?

Goes far beyond annotations by detailing model families, Kelly capping at 0.25, the 24h-move warning, Fed bet exclusion reasoning, diagnostics funnel counters, and KV-level caching. Annotations already declare read-only/idempotent, and the description adds rich behavioral context without contradiction.

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

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

The description is very long but well-structured with uppercase section headers and dense, high-value content. Every sentence carries meaningful information for a complex tool, though the algorithmic detail could be trimmed for brevity without losing key guidance.

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

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

Since there is no output schema, the description compensates by specifying top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity), and caching behavior. It is thorough enough for an agent to understand what to expect.

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

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

Schema covers 100% of parameters, but the description adds crucial interaction semantics (e.g., min_kelly never filters partition arbs because parent-level kelly_fraction_half=0, min_partition_leg_kelly applies to per-leg Kelly). Also explains why slippage_pp default is 0.3 based on Polymarket spread behavior.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like polymarket_arbitrage by targeting edge discovery for daily betting decisions.

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 usage context ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and explains knob interactions (e.g., min_partition_leg_kelly for per-leg Kelly). However, it does not explicitly name alternative sibling tools for when this tool shouldn't be used.

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. The description adds crucial context beyond that: the 60-day snapshot TTL limit, that decay is computed from daily closes (not intraday), that snapshots are written on cache-miss (gaps mean no scan), and the signed semantics of edge_pp_net. These are non-obvious behavioral traits the agent needs.

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

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

Though long, the description is tightly organized with ARGS, RESPONSE, and LIMITS sections. Every sentence carries information: defaults, time-series details, field definitions, and caveats. No fluff. The front-loaded question immediately anchors the purpose.

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

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

There is no output schema, so the description fully specifies the response shape: tracked[] with edge_pp_net time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. It also explains limitations (TTL, snapshot gaps, close-based decay). This is a complete, self-contained description for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'window family' concept and restating defaults/clamps, plus the RESPONSE section shows how parameters affect the result (e.g., which snapshots are included). This is helpful but not a massive addition beyond the schema, so a 4 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a clear question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical decay rather than current edges.

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

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

It implies when to use this tool: when you care about edge age/decay, contrasting 'a fresh wide edge and a 3-week-old wide edge' as different trades. It does not explicitly name alternative tools or state 'when not to use,' but the context strongly implies it complements polymarket_edges. Slight gap for explicit 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 goes far beyond the readOnlyHint/idempotentHint annotations by detailing the order-book walking behavior, return values (top_of_book, vwap_fill_price, slippage_pp, etc.), and the risk of partial basket fills converting an arb into an unhedged directional position. This is rich behavioral disclosure that helps the agent anticipate outcomes.

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

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

The description is long but every sentence serves a purpose: it introduces the tool, defines two distinct modes, enumerates return fields for each, and provides a risk warning. It is front-loaded with the core purpose and uses clear uppercase labels for modes, making it easy to parse despite its length.

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

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

Given the tool's complexity (dual modes, no output schema), the description is remarkably complete. It lists all key return fields for both single-market and basket modes, explains the auto side default, and warns about thin legs and forced directional risk, leaving little ambiguity for an agent deciding whether 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?

Even though schema coverage is 100%, the description adds crucial meaning: it explains the difference between single-market and basket size_usd interpretation, default side behavior, mode switching based on market vs event, and the 10–1,000,000 clamp. This is valuable beyond the schema's raw parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes modes (single-market vs basket) and names sibling tools like polymarket_arbitrage and polymarket_edges, 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?

It explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the required input modes (market or event) and what to expect in each, providing clear contextual guidance.

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

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

Even with strong annotations (readOnlyHint=true, idempotentHint=true), the description goes far beyond them. It discloses complex behavioral details: compatibility_warning triggers and conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the math implication of aligned:false. It also reveals that many pre-mapped topics are not tradeable, a key caveat. No contradiction with annotations exists.

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

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

The description is long but well-structured with titled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the primary purpose and then systematically details modes, outputs, and edge cases. While some redundancy exists (e.g., repeating caveats), the length is justified by the tool's complexity and the need to warn about non-obvious failures.

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 thoroughly explains what the response contains: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It covers input modes, output structure, safety behavior, and semantic caveats. For a tool with optional parameters and high complexity, this is fully complete and leaves no 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?

Although the schema covers all three parameters with descriptions (100% coverage), the description enriches their meaning significantly. It explains the interaction between topic and explicit overrides ('Overrides the topic-mapped...'), defines the two operational modes, and lists example values for topic. This contextual adds clarity beyond the raw schema definitions.

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

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

The description opens with the core function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool's scope from sibling tools like polymarket_arbitrage by focusing on same-question spreads and explicitly describing two modes (topic shortcuts and explicit tickers). The purpose is specific, actionable, and immediately understandable.

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 how-to guidance: users can either use pre-mapped macro shortcuts ('fed', 'btc', etc.) or specify custom ticker/slug pairs. It also sets expectations by warning that most pre-mapped topics currently return compatibility_warning and that 'pre-mapped ≠ tradeable.' However, it does not explicitly say when to choose this tool over sibling alternatives like polymarket_arbitrage, leaving some comparative guidance implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context about scoping to an identifier and the dual behavior of retrieving a single value vs. listing all keys when the key argument is omitted. This goes beyond what annotations alone provide, though it doesn't describe error handling or return formats.

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 concise sentences that front-load the main purpose and then provide usage context, scoping, and related tools. Every sentence adds value, with no fluff or redundant information. It is structured logically: function, use case, and ecosystem.

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 low complexity (one optional parameter, no output schema), the description covers all necessary aspects: what it does, when to use it, how it scopes data, and how it relates to the memory system (remember/forget). It is complete and self-contained for an agent to decide invocation.

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

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

Schema coverage is 100%: the single 'key' parameter is fully documented in the schema with 'Memory key to retrieve (omit to list all keys)'. The description repeats this and adds examples of key types, but the core semantics are already present. Since the schema carries the heavy lifting, a baseline of 3 is appropriate; the extra examples are helpful but not transformative.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It uses specific verbs (retrieve/list) and explicitly distinguishes itself from sibling tools like remember and forget by naming them and describing the relationship.

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 context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names the complementary tools 'remember' and 'forget', providing a clear when-to-use vs alternatives. The scoping detail ('Scoped to your identifier') adds important context for the agent.

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

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

The description states 'Set mark_read:true to flag returned events read' implying a state-changing side effect, directly contradicting the readOnlyHint:true annotation. This is a serious inconsistency that can mislead an agent into believing the tool has no side effects. Despite useful context about event payload and polling, the contradiction undermines transparency.

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

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

The description is a single, dense sentence but front-loads the core purpose. It packs essential details without fluff, though splitting into two sentences would improve readability. Every clause adds value, so it earns a 4.

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

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

Given no output schema, the description appropriately details what each event carries (source, citation_uri, raw payload) and explains the read-tracking behavior. It also notes the HTTP endpoint alternative and confirms polling suitability. The only missing piece is an explicit mention of limit/unread_only interactions, but those are in the schema and the tool is relatively simple.

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

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

The schema covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds meaningful context beyond the schema: it clarifies the type filter with an example, explains mark_read's effect on future calls, and mentions ISO timestamp format. 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 'Pull fired events from your subscription feed' – a specific verb and resource. It clearly identifies the tool's function of retrieving alerts from a persisted feed, distinguishing it from sibling tools like list_subscriptions or subscribe. It also specifies the contents of each alert, making the purpose unambiguous.

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

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

The description explains when to use this tool ('Polls work fine') and provides an alternative access method via the HTTP endpoint, which aids decisions between interactive and scripted use. However, it does not explicitly contrast with sibling tools (e.g., search_within) or mention when not to use this tool, so it falls short of full guidelines.

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 signal readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail: multi-source fan-out, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to API sunset, and the exact return structure (changes[], total_changes, pipeworx:// URIs). This goes well beyond the annotation baseline and fully discloses expected behavior.

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

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

Though lengthy, the description is dense and well-structured. Every sentence adds unique value: example queries, source logic with fallbacks, parameter format details, return shape, and an alternative-tool pointer. It is front-loaded with purpose and proceeds logically, without redundancy.

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

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

Given the tool's complexity (three data sources, fallbacks, flexible `since` parsing, return structure, and no output schema), the description is remarkably complete. It covers all invocation aspects and alternative use cases, making it fully contextual for an AI 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 descriptions cover all three parameters, but the description adds valuable semantics: `since` accepts ISO or relative shorthand with concrete examples ('7d', '30d', '3m', '1y') and a recommended '30d'/'1m'; `value` is illustrated with ticker and CIK examples; `type` explicitly limited to 'company'. This enrichment aids agent selection and correct invocation.

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

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

The description clearly explains that the tool returns a change feed for a company in a given time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It provides natural-language example queries and mentions the single parallel-call architecture. It also distinguishes itself from entity_profile, making the purpose unmistakable.

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

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

The description offers explicit usage guidance with sample queries like "What's new with X" and "updates on Acme," and directly recommends an alternative: 'Use entity_profile instead when you want the static profile.' It also suggests typical windows ('30d' or '1m'), giving the agent clear context for when and how to use the 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds extra behavioral context by explaining 'Stored as a key-value pair scoped by your identifier' and that 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This goes beyond the schema and annotations, giving the agent essential information about scoping and persistence.

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 around 60 words and contains no fluff. Sentences are front-loaded with the core purpose, followed by usage triggers, then behavioral details, and finally sibling links. Every sentence earns its place without redundancy.

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

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

For a simple storage tool, this description covers everything an agent needs: what it does, when to use it, how data is stored and scoped, persistence rules, and how to retrieve/delete it later. The absence of an output schema is acceptable because the operation is a save, and the description implies the effect without needing to enumerate return values.

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

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

The input schema already has 100% coverage with descriptions for 'key' and 'value'. The description reinforces the relationship between the two by calling it a 'key-value pair' and adds the scoping behavior ('scoped by your identifier'), which adds meaning beyond the schema. The examples in the schema further clarify parameter usage.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('Save'), names the resource (key-value data), and distinguishes itself from its siblings (recall, forget) by mentioning pairing and retrieval.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also differentiates between authenticated and anonymous sessions, clarifying persistence expectations. It explicitly references siblings with 'Pair with recall to retrieve later, forget to delete.'

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 significant behavioral context beyond annotations: it describes graceful degradation ('LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), cascading internal lookups, identifier labelling with sources, and explicit unresolved identifiers. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, which the description confirms (no mention of side effects). The only minor gap is no mention of rate limits or error handling for failed resolution beyond graceful degradation.

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, starting with query examples and usage guidance, then detailing supported types. It front-loads the key action ('resolve a user-spoken NAME') and usage instruction ('Use FIRST'). Slightly verbose in the 'company' type description, which could be tightened (e.g., the parenthetical about ISIN-to-LEI mapping could be a separate sentence). However, every sentence earns its place by providing actionable detail for an agent. It is not overly long for the complexity.

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

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

Given the tool's complexity (multi-source cascade, two entity types), no output schema, and no nested objects, the description is thorough. It covers return format details (identifiers labelled with source, unresolved stated explicitly) and graceful degradation. The only gap is lack of explicit mention of return value structure (e.g., JSON shape) since no output schema exists. For an agent, the description is complete enough to understand what it gets back, but a sample or schema for the response would push this to 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant parameter context by enumerating accepted input formats for each type (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company; 'brand or generic name (e.g., "ozempic", "metformin")' for drug) and explains how ISIN resolves via GLEIF mapping. This goes well beyond the schema's short descriptions, justifying a 4. It doesn't, however, cover every nuance (e.g., case sensitivity, special characters), but the additional value is substantial.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers, giving specific verb-resource pairs ('resolve a user-spoken NAME to the canonical/official identifiers'). It distinguishes from siblings by noting it replaces 2-3 manual lookups and lists supported types (company, drug) with detailed resolution sources, though siblings like 'compare_entities' or 'entity_profile' are related but the description doesn't directly contrast them. The concrete query examples ('what's the ticker for…') make intent immediately clear.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It gives specific when-to-use context with examples of queries that trigger this tool. It also implicitly warns about alternatives by noting 'resolve_entity replaces 2-3 manual lookups', implying deeper investigation might need lookup chains. However, it doesn't explicitly state when NOT to use it (e.g., if you already have an ID), but the guidance is strong enough for an agent to infer.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that it internally calls ai_visibility_check for each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds operational clarity without contradicting annotations.

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

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

Three efficient sentences convey the purpose, method, use case, and output format. No filler or redundancy; 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?

With no output schema, the description adequately explains the return shape (ranked list with score, confidence, signal density). Given the moderate complexity, the annotations cover safety, and the schema covers parameters, the description provides sufficient contextual completeness.

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

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

The schema provides 100% coverage with detailed descriptions for all four parameters, including the 'first entry treated as subject' rule. The description echoes this rather than adding new semantics, so it meets the baseline but does not elevate further.

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: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from single-entity tools like ai_visibility_check by emphasizing the comparative, multi-entity nature and the ranking/surfacing behavior.

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

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

Provides a concrete use case ('competitive AI-marketing audits') and an illustrative question ('does Claude know about us as well as our competitors?'). It implies that for a single entity, one would use ai_visibility_check instead, but does not explicitly state alternatives or exclusions.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds critical behavioral context: the composite fan-out across two services, potential 5-30s latency on first measurement, graceful partial-failure handling, and the sources_failed field. This goes well beyond what annotations provide.

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

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

The description is dense but well-organized: it front-loads the core purpose, lists return content, specifies ecosystem scope, and discloses potential latency and failure modes. Every sentence provides necessary information without redundancy or fluff.

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

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

Given the tool's complexity (composite of two services, multiple output elements, potential timeouts, ecosystem restrictions), the description is remarkably complete. It covers the return summary fields, per-advisory detail, links, alternative versions, latency behavior, and graceful degradation, all without an output schema.

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

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

The input schema already documents both parameters fully (package name, optional version with default). The description does not add new parameter-level semantics beyond what the schema states, so the baseline of 3 for high schema coverage applies.

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

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

The description clearly defines the tool as a composite check for deciding whether to add an npm package, detailing the specific data sources (deps.dev, bundlephobia) and the exact metrics involved (license, advisories, bundle size, etc.). This unambiguous verb+resource combination distinguishes it from all sibling tools.

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

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

It explicitly states when to use the tool ('whenever an agent asks is X safe / popular / small') and provides a direct alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This offers clear usage guidance and exclusions.

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

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

Annotations only say readOnly/idempotent/openWorld, but the description adds concrete mechanics: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also discloses that every passage carries an offset and similarity score, which is more than the annotations reveal. 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?

Three sentences, each earning its place: first the core action, second the usage scenario and pairing, third the technical details. Highly efficient 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?

For a tool with no output schema, the description fully prepares the agent: tells what to expect (passages, offsets, scores), how to use it with examples, technical limits (truncation), and integration with ask_pipeworx_grounded. No significant gaps.

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

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

The schema describes all three params, but the description enriches them with real-world examples ('a SEC 10-K body, an article, a long tool result') and clarifies the query style ('natural-language query'). It also clarifies the limit as 'top-N passages' and ties the text param into the usage context.

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

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

The description opens with a specific action: 'Semantic search INSIDE a fetched record,' which clearly names a verb (search) and resource (record). It distinguishes itself from siblings like ask_pipeworx_grounded by explaining this tool is for searching within already-fetched text, not for a broader Q&A flow.

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 when-to-use: 'Use when the record is too big to cram into the prompt.' It also pairs directly with ask_pipeworx_grounded, telling the agent exactly how to combine it with a sibling tool: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 idempotent and not read-only, but the description adds critical behavioral details: auth requirement for persistence, one-time webhook signing secret, auto-disable after 10 consecutive failures, sms 10/day cap, and phone verification. This goes well beyond the structured annotations and matches the openWorldHint by acknowledging the live-data stream nature.

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, front-loading the purpose and then methodically covering supported types and delivery channels. Every sentence adds value, though it is somewhat long. It avoids redundancy and earns its length given the tool's complexity.

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

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

The description covers the core invocation contract: returns subscription id, prerequisites, supported types with examples, and delivery options including webhook signing. It lacks some lifecycle context (e.g., how to later cancel), but given no output schema, it adequately tells the caller what to expect and what constraints apply.

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 description mirrors the schema's parameter examples (e.g., sec_8k items['5.02'], polymarket_edge topic:'fed', fred_series series_id:'UNRATE'). The description adds little meaning beyond the schema's per-parameter descriptions, so a baseline 3 is appropriate.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream', which is a specific verb+resource pair that clearly states what the tool does. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and it identifies the return value (new subscription id).

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

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

The description provides clear context for when to use the tool (proactive monitoring) and prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It also explains delivery channel choices and limits (sms verification/cap). However, it does not explicitly name alternatives like list_subscriptions or recent_alerts as exclusions, only implying the always-on feed as a pull option.

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, open-world safety; the description adds substantial behavioral context: returns category-bucketed examples with exact tool+argument shapes, no-args returns full spread, and topic narrows it. No contradiction exists.

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

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

The description is long but densely packed with valuable information. The opening list of example phrasings partially restates the title, but every clause contributes substance, making the length acceptable.

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

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

Without an output schema, the description supplies return semantics, invocation modes (no-args vs. topic filter), and clear usage context. It also connects to sibling meta-tools, making it complete for an agent onboarding scenario.

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 for the single optional `topic` parameter, including enumerated focus areas and omit behavior. The description only repeats this with redundant examples, adding no new semantic meaning.

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

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

The description clearly states a specific verb and resource: it is the onboarding entry point that returns category-bucketed example questions. It distinguishes itself from sibling tools by focusing on suggesting questions and teaching meta-tool usage rather than executing queries.

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, or to learn how to call the meta-tools.' It names meta-tools as alternatives for actual execution, though it does not explicitly spell out when not to use sibling discovery tools.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false), non-destructive (destructiveHint=false), idempotent, and has external effects (openWorldHint=true). The description goes further by explaining ownership enforcement and the deactivation (not deletion) behavior, which preserves historical events. This adds meaningful context beyond the annotations and is consistent with them.

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

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

The description is three sentences, each earning its place: the action performed, the ownership constraint, and the deactivation effect. It is concise and front-loaded with the primary purpose, 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?

For a tool with a single parameter and no output schema, the description covers the essential behavioral caveats: ownership restriction and soft-delete with historical availability. It also references recent_alerts for historical events, making the tool complete for an agent to use correctly without needing further clarification.

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

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

The input schema has 100% coverage for the single parameter 'id', describing it as 'Subscription id (uuid) returned by subscribe.' The description merely says 'by id' and doesn't add new semantic details beyond what the schema already provides. Baseline of 3 is appropriate because the schema handles the parameter semantics 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.' This is a specific verb (cancel) targeting a resource (subscription) with a clear method (by id), and it distinguishes itself from sibling tools like subscribe 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?

The description provides context on when to use the tool: canceling your own subscription, with ownership enforced. It also notes the soft-delete behavior and that historical events remain available via recent_alerts, implying an alternative for viewing history. However, it does not explicitly name other alternatives or state when not to use it beyond ownership.

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 exposes pipeline routing, return verdicts, citation format, and critical caller rules: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source exists. It also discloses tolerance behavior and the grounded/structured fallback.

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

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

The description is long but front-loaded with purpose and trigger phrases, then compactly covers routing, verdicts, citations, and warnings. Some details are dense, but every sentence carries meaningful guidance; it could be slightly tightened without losing value.

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

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

With no output schema, the description fully specifies return values (verdicts, actual value with citation, reasoning), interprets edge-verdict states, and documents pipeline fallback. It leaves no material gap for callers on how to act on results.

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

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

Schema coverage is 100%, but the description adds substantial meaning by explaining tolerance_pct defaults, override behavior, the cap at 5, and its use for hallucination detection. Claim examples show expected natural-language format beyond the schema's generic description.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that' and a specific verb-resource pair: verifying factual claims. It also distinguishes subpaths for company-financial vs other claims and states it replaces 4-6 sequential calls, separating it from siblings.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and lists financial vs grounded routing. It does not explicitly state when not to use the tool (e.g., subjective or non-factual questions), but the factual-claim scope and important could_not_verify handling provide clear usage context.

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