Abn Lookup

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by revealing that this is an external ABR web-service lookup requiring a user-supplied GUID, which is not obvious from annotations alone. It also discloses the kind of data returned without contradicting any annotation.

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

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

The description is compact and front-loaded, covering purpose, return fields, prerequisite, registration link, and an example in a short space. The 'BYOK' abbreviation is jargon but is immediately clarified by the next sentence. Overall, every sentence contributes meaningful value.

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

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

For a simple two-parameter read-only tool with no output schema, the description is self-sufficient: it lists the main return fields, states the external dependency and key requirement, gives the registration URL, and provides a complete invocation example. An agent has enough context to select and call 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%, with detailed descriptions for both abn (format, spaces, example) and _apiKey (GUID, registration link). The description reinforces _apiKey's role and provides an example, but adds little semantic information beyond what the schema already provides. Baseline 3 applies.

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

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

The description uses a specific verb and resource: 'Look up an Australian Business Number (ABN)', then enumerates the exact returned fields (legal entity name, entity type, ABN status, GST registration, address, business names). This clearly distinguishes it from siblings such as abn_search (search vs lookup by number) and acn_lookup (different identifier 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?

The description clearly establishes when to use this tool: when you have an ABN and want entity/business registration details. It also communicates the BYOK prerequisite, the required _apiKey, and where to register for one. It does not explicitly name alternatives or exclusions, but the usage context is clear.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds non-obvious behavioral context: this is a BYOK tool that calls an external ABR web service, so there is no platform-managed key. It also says results are ranked, though it does not explain ranking details, rate limits, or error behavior.

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

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

The description is compact and front-loaded: it starts with the critical BYOK caveat, states the core action, explains the key requirement with a registration link, and finishes with a concrete example. 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 four-parameter tool with rich schema coverage and safety annotations, the description plus schema cover the prerequisite, required parameters, optional filtering, and the general result type. The main missing contextual items are more detail about the return fields and an explicit comparison against abn_lookup, so it is not fully complete.

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

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

Schema description coverage is 100%, and each parameter already has a useful description, so the baseline applies. The description's example demonstrates the required name and _apiKey combination, which adds a little clarity, but it does not add substantial meaning beyond what the schema already provides.

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

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

The description names a specific resource (Australian Business Register) and a concrete verb (search by entity/business name and return ranked ABN matches), and it includes a working example. It is not a tautology and is clear enough to know what the tool does, but it does not explicitly differentiate it from the sibling abn_lookup tool.

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

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

The description clearly states the prerequisite: the caller must provide their own ABR web-services GUID and register for a key. However, it does not explicitly say when to use this tool instead of alternatives such as abn_lookup, nor does it give any when-not-to-use guidance.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds meaningful behavioral context beyond those annotations: it requires a caller-provided ABR web-services GUID, explains the BYOK model, and gives the registration path. It also names the returned fields, so the agent knows what to expect from the response.

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

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

The description is compact and front-loaded: it opens with the critical BYOK constraint, then states the purpose and return fields, then the requirement and an example. Every sentence earns its place, and the example makes the expected invocation unambiguous.

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 two-parameter read-only lookup with strong annotations, the description is complete: it covers purpose, expected return fields, authentication prerequisite, registration path, and an example call. There is no output schema, but the listed return fields are sufficient for an agent to understand what will come back.

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 already documents both acn and _apiKey well. The description adds a concrete usage example and reinforces the meaning of _apiKey, but it does not provide substantial semantic value beyond what the input schema already says. 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 states a specific verb and resource: 'Look up an Australian Company Number (ACN)'. It also clarifies what data is returned and explicitly distinguishes this from abn_lookup by saying it returns the same detail for the company's associated ABN. An agent can immediately tell what the tool does and how it relates to its sibling.

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

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

The description gives clear context: use an ACN as input and get the same details as abn_lookup, with an explicit BYOK prerequisite and registration link. It does not explicitly state 'use abn_lookup when you have an ABN', but the phrasing strongly implies the ACN-vs-ABN routing and names the sibling tool that provides the parallel behavior.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable behavioral context: the free default model, the BYO-key arrangement for Anthropic (including that the user pays directly), key passthrough, and the return shape. This goes beyond the annotation baseline without contradicting it.

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: core action and score range, configuration/default model and key handling, then return shape and use cases. The most important information is front-loaded, with no filler.

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

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

Despite having no output schema, the description fully explains what the tool returns (per-model {score, confidence, signals, raw_response} plus combined view), how to configure models, cost implications, and when it is useful. The only minor gap is sibling differentiation, which was already penalized under usage guidelines. Overall, an agent can invoke this tool correctly with confidence.

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 meaning on top of the schema: it specifies the default model, explains that _apiKey is only needed for Anthropic and is passed straight through, and notes the cost implication (BYO key, paid directly to Anthropic). This gives the agent operational context not present 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 names a specific verb ('probe') and resource (LLMs), and clearly defines the output as a 0-100 visibility score per model. It is unambiguous and detailed, but it does not explicitly distinguish itself from close siblings such as scan_competitor_ai_presence, so it falls short of a 5.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which implies when to use the tool. However, it never contrasts the tool with alternatives like scan_competitor_ai_presence or compare_entities, leaving the agent to infer selection boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so no safety contradiction exists. The description adds real behavioral context: it autonomously routes and fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. This goes beyond the annotations without being excessive.

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 the length is justified for a router tool with broad scope and multiple sibling alternatives. Core guidance is front-loaded with 'PREFER OVER WEB SEARCH' and 'START HERE', followed by examples and escalation paths. Some redundancy exists in the long domain list, but every sentence earns its place overall.

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 highly complex routing tool with no output schema, the description is remarkably complete: it covers scope, examples, citation behavior, tier availability, and explicit alternatives for advanced use cases. The annotations handle safety traits, while the description covers the practical invocation context. Nothing essential is missing for an agent to decide when and how to call it.

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

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

Schema description coverage is 100%, with question and all five aliases documented in the input schema. The description reinforces that the tool takes a natural-language question and does argument filling, but it does not add parameter-level meaning beyond the schema. Baseline 3 is appropriate because the schema already carries the full parameter documentation burden.

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

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

The first sentence states a specific action: route natural-language questions to the correct tool among 5,798 tools across 1,517 verified sources and return a structured answer with citations. It clearly lists domains (SEC filings, FDA, FRED/BLS, patents, etc.), so an agent knows exactly what this tool is for. It also differentiates itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', establishes it as the default entry point, and gives concrete trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It even states when to step up to ask_pipeworx_grounded or deep_research, providing clear when-to-use and when-not-to-use guidance with examples.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the additional behavioral context is a bonus. The description discloses experimental status, the possibility of candidate routing improvements being live, current lack of an active candidate, and that it falls back to nothing—a full working router rather than a stub. This goes beyond the structured annotations by explaining the operational state and comparison workflow.

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 detailed but every sentence earns its place: identity, equivalence, current status, usage guidance, and fallback behavior. The key point about being identical to ask_pipeworx is front-loaded. The only minor redundancy is restating 'same arguments' and 'same response shape' in close succession, but this is acceptable for emphasis.

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 usefully states that the response shape is identical to ask_pipeworx, covering the return contract. It also explains current runtime state and how to choose between beta and stable variants. The main gap is that it doesn't describe what kinds of 'routing improvements' might be active, but that is not required to invoke the tool correctly.

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

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

Schema description coverage is 100%, so all six parameters are already documented, with five labeled as aliases for 'question'. The description adds no new parameter-level semantics beyond saying the tool takes the same arguments as ask_pipeworx. This meets the baseline for high schema coverage but adds little extra 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 states this is a beta version of ask_pipeworx: an identical universal router that handles 5,798 tools with the same arguments and response shape. It clearly differentiates from the sibling ask_pipeworx by framing itself as the experimental counterpart. The purpose—acting as the latest-routing variant of ask_pipeworx—is 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 explicitly says to 'use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router. It explains that results are compared against the stable router to decide merges, which tells an agent when this variant is preferred. It also clarifies that no candidate is currently active, so behavior currently matches ask_pipeworx exactly, removing guesswork.

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 read-only, open-world, idempotent, non-destructive behavior; the description adds further transparency by disclosing that it only uses tool-result content, that it returns verbatim evidence or null with a specific refusal_reason, and that it costs an additional LLM call. No contradiction with annotations.

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

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

The description is dense but every clause earns its place: mode, routing, extraction rule, return shape, refusal reasons, use cases, and cost comparison are all packed into a compact paragraph with clear front-loading.

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

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

With no output schema present, the description carries the full burden of explaining return values, which it does with the success shape and refusal alternatives. Together with the annotations and sibling differentiation, an agent has everything needed to invoke and interpret this tool correctly.

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

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

The schema already covers the question parameter at 100%, including aliases, so the baseline is 3. The description adds use-case context that implies the question should be verifiable, but it does not add concrete format, length, or style guidance for the question parameter beyond the schema.

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

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

The description opens with a precise verb and resource: 'Hallucination-resistant answer mode for high-stakes reads' and specifies the mechanism: it routes to the same tool pool as ask_pipeworx but extracts answers only from tool results. It differentiates from the sibling ask_pipeworx by promising verbatim evidence and explicit refusals.

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

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

It gives explicit when-to-use guidance — 'whenever an answer will be quoted, cited, or acted on' and the agent must not invent facts — plus an explicit alternative preference: 'prefer ask_pipeworx for casual lookups.' The cost tradeoff is quantified as one extra LLM call.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral detail: blocker statuses like low_confidence_match and market_closed_or_inactive, the resolver contract with match confidence and alternatives, spread illiquidity warnings, news fallback fields, and cancellation-rule risk. It even warns the agent to inspect resolver fields before trusting the analysis block. Nothing in the description contradicts 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 long, but the structure is effective: core purpose and usage come first, followed by captioned blocks for classifiers, fan-out examples, response shapes, resolver contract, safety, and cancellation risk. Each block adds necessary operational detail for a complex tool with no output schema. Some repetition around blocking behaviors could be tightened, but the length is largely 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?

For a three-parameter tool with no output schema, the description is unusually complete. It describes return-shape keys, resolver confidence fields, parent-event partitions, news fallback behavior, blocking statuses, and cancellation-rule variants. An agent can predict what the tool returns and which edge cases to guard against without needing 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?

Schema description coverage is 100%, with all three parameters documented and examples provided. The description reinforces accepted market formats but does not add new semantics for depth or include_raw beyond what the schema already states. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.

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

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

The description uses a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states accepted inputs (slug, URL, question text), the resolution/classification/fan-out behavior, and the return artifact (evidence packet + market-vs-model comparison), making it easy to distinguish from sibling Polymarket 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 gives explicit use cases: 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z'. It also provides concrete fan-out examples. However, it does not explicitly say when to prefer a sibling tool such as polymarket_edges or polymarket_arbitrage, nor does it state exclusions or when not to use bet_research.

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

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

Despite strong annotations (readOnly, idempotent, openWorld, non-destructive), the description adds meaningful behavior: data sources (SEC EDGAR/XBRL, FAERS, FDA), exact metrics pulled, correct handling of off-calendar fiscal years, sorting by primary metric, and pipeworx:// citation URIs. No statement conflicts with the annotations.

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

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

The description is dense but front-loaded with triggers and the key preference rule before source details. The 'Replaces 8–15 sequential lookups' phrase is mildly promotional but not redundant; overall it earns its length.

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

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

With no output schema, the description covers return expectations (paired data, sorting, citation URIs), the two entity types, input constraints, and important domain caveats. An agent has enough context to select and invoke the tool correctly without needing additional metadata.

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

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

Schema coverage is already 100%, but the description enriches both parameters: type='company' maps to LATEST 10-K financial metrics and type='drug' maps to adverse-event/approval/trial counts. It also clarifies values as tickers/CIKs vs drug names, going well beyond the schema's short 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 names a specific verb-resource pairing ('side-by-side comparison of 2–5 companies or drugs') and lists natural-language triggers ('X vs Y', 'which is bigger', 'rank these companies'), making the tool's purpose unmistakable. It also differentiates from sequential lookups, so it is not confused with entity_profile.

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

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

It explicitly states when to use the tool via user-phrase examples and says to 'ALWAYS PREFER' it over 'sequential single-pack lookups' for comparison tasks. This provides a clear selection rule relative to the closest alternative, even though the sibling tool name isn't spelled out.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses account/paywall gating, parallel decomposition across tools, the explicit gaps[] never-invented guarantee, contradictions[] behavior for certain depths, citation fetchability semantics, semantic excerpting, and latency expectations. These are substantive behavioral facts an agent needs and are not present in annotations. No contradiction found.

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

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

The description is long but every sentence adds distinct operational value: account requirement, fallback tool, core behavior, output packet fields, depth variants, contradiction scans, excerpting, and latency. It is front-loaded with the most critical prerequisite 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?

Despite having no output schema, the description enumerates the findings packet contents (verbatim evidence, confidence, source, fetched_at, stable citation), the gaps[] field, contradictions[], the hop field, citation_uri fetchability, and latency ranges. Combined with full schema coverage for the two parameters, an agent has everything needed to call and interpret 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%, and the schema already thoroughly describes both 'question' and 'depth', including enum values, defaults, and hop behavior. The tool description adds contextual routing and depth-specific caveats but no new parameter-level semantics. Therefore the baseline of 3 applies.

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

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

The description names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources'. It explicitly differentiates itself from alternatives: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx instead.' This gives an agent a precise, unambiguous idea of what the tool does and how it differs 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples. It also states when not to use it and which alternative to choose: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' This is clear routing with 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?

The description goes beyond annotations by disclosing the return format: top-N relevant tools with names, descriptions, and full input schemas, ready to call directly without a second lookup. This is useful behavioral context. It doesn't contradict the readOnlyHint, idempotentHint, or destructiveHint annotations.

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

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

The description is front-loaded with the core purpose, then provides return details and usage guidance. The domain list is long but serves to clarify the scope. Each sentence earns its place, though the list could be slightly trimmed without losing meaning.

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-discovery tool with no output schema, the description sufficiently explains both invocation and expected results. It names the input type, the output fields, and the ready-to-call nature of results, making the tool fully usable with the schema 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 coverage is 100%, so the baseline is 3. The description reinforces that the query is a natural-language task description and mentions top-N results, but it doesn't add meaning beyond what the schema already documents for each 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 clearly states the tool's purpose: finding tools by describing the data or task, and explicitly lists the covered domains. It distinguishes itself from sibling tools by being the meta-search layer, not a domain-specific data lookup tool.

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 tells the agent when to use this tool: when browsing, searching, looking up, or discovering tools, and instructs to call it FIRST when many tools are available. This provides clear routing guidance even though it doesn't name a specific alternative, since no sibling serves the same discovery role.

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

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

Despite readOnlyHint/openWorldHint/idempotentHint already covering the safety profile, the description adds substantial behavior: source fan-out, empty-section semantics ('a real no data, not a bug'), USPTO soft-fail, GDELT→GNews fallback, and resolved:false handling for private companies. No contradiction with annotations.

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

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

The description is front-loaded with trigger phrases and the primary usage directive, and the long output specification is justified by the tool's complexity. It loses a point for redundancy: value shapes and type behavior are restated from the schema, and the dense semicolon list is harder to scan than structured bullets.

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 fields and failure semantics, and it does so thoroughly: resolved status, recent filings URIs, fundamentals sort, sources_used/sources_failed, no-data expectations, and input resolution rules. Nothing needed to call or interpret the tool is missing.

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

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

The schema already documents both parameters at 100% coverage, including the interchangeable type behavior and accepted value shapes. The description adds only minor extras such as examples and resolved_from/resolved_to context, 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 concrete user phrasings and states the deliverable: 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates from single-purpose lookups and lists exactly what the fan-out covers, so an agent can match it to holistic company-profile requests.

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 tells the agent to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, and explains the private-company fallback. It does not name specific sibling alternatives or state when not to use it, so it stops just short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the description's explicit 'Delete' is consistent. The description adds context about when deletion is appropriate but does not disclose potential irreversibility or lack of output, though with annotations present this gap is acceptable.

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

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

The description is compact, front-loaded with the core action, and every sentence adds value: what it does, when to use it, and how it relates to sibling tools.

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

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

For a simple single-parameter destructive tool with strong annotations and a clear schema, the description provides sufficient context for an agent to select and invoke it correctly. It does not detail the return value, but a delete operation of this simplicity does not require it.

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

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

Schema description coverage is 100%, and the schema already describes key as 'Memory key to delete.' The description's 'by key' reinforces this but does not add new semantic detail beyond the schema.

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

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

The description states a specific action ('Delete') and a specific resource ('a previously stored memory by key'). It clearly differentiates from sibling tools remember and recall by focusing exclusively on deletion of stored memory.

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 conditions: stale context, completed task, or clearing sensitive data. It also references sibling tools remember and recall for pairing, though it does not explicitly state when not to use forget or contrast it in detail with those tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful internal context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' plus the output placement. There is no contradiction with annotations — fetching and generating is consistent with read-only, idempotent 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?

Three sentences with the core purpose front-loaded, followed by the internal process and then the use-case list. Every sentence earns its place, the 'Useful for' list is compact, and there is no redundant boilerplate.

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

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

With no output schema, the description compensates by specifying the return value: 'Output is a single text blob ready to drop at site-root/llms.txt.' Combined with two fully-documented parameters and complete annotations, the description covers process, output, and use cases. The only gaps are edge-case behaviors like unreachable URLs or error handling, which are minor for a simple read-only fetch 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 input schema fully documents both url and max_links, including the default (25) and max (50) for max_links. The description's 'any URL' and 'key links' phrasing aligns with the parameters but does not add syntax, constraints, or examples beyond what the schema already provides, so it stays at 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 states a precise verb+resource: 'Generate a production-ready llms.txt file for any URL so AI crawlers (ChatGPT, Claude, Perplexity) can index the site cleanly.' It names the downstream consumers and the exact output format ('standard llms.txt markdown format'), making the tool's function unambiguous and distinguishable from siblings like ai_visibility_check.

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

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

The description gives three concrete invocation scenarios: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This is clear contextual guidance, but it never names alternatives or states when not to use the tool, leaving the potential overlap with siblings like scan_competitor_ai_presence 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 safety is covered. The description adds meaningful behavioral context beyond annotations: return fields are enumerated (id, type, params, created_at, last_fired_at, fire_count), which is critical given there is no output schema, and it discloses the active-only default scoping.

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

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

Two sentences with zero waste: the first states action, scope, and return format; the second states when to use it. Every clause earns its place, and the core purpose is front-loaded before the usage guidance.

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

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

For a simple read-only list tool with no required parameters and strong annotations, the description is complete. It covers what is returned (compensating for the missing output schema), the active-only default, and both primary use cases. The large sibling set raises the differentiation bar, and the description clears it for the closely related subscribe/unsubscribe tools.

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 include_inactive parameter, so the baseline is 3. The description adds complementary value by framing 'active subscriptions' as the default, reinforcing the parameter's default-false semantics, and by noting the returned 'id' is what you'd use to cancel — connecting the output to the unsubscribe workflow.

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

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

The description states a specific verb and resource — 'List the caller's active subscriptions' — and distinguishes itself from the sibling tools subscribe and unsubscribe by framing this as a review/lookup operation. The caller scoping ('the caller's') removes any ambiguity about which subscriptions are returned.

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 when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This maps directly to the sibling tools subscribe ('before adding more') and unsubscribe ('find an id to cancel'), routing the agent to the correct alternative without ambiguity.

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 important behaviors beyond the annotations: anonymous filing returns a claim_token, passing that token later retrieves resolution status, the endpoint is rate-limited to 5 per identifier per day, and it does not count against the tool-call quota. This gives the agent a clear model of side effects and limits 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 dense but every sentence earns its place: purpose, use cases, exclusions, content guidance, token flow, rate limit, and cost. The most important guidance is front-loaded, and the caveats are grouped 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?

The description is complete for a feedback tool with no output schema. It tells the agent what to file, how to frame it, when not to file, what response token to expect, how to follow up, and what operational constraints apply. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds genuine value on top by explaining the claim_token round-trip flow (file without account, get pwfb_ token, pass it back with no other arguments to read status) and by advising against pasting end-user prompts. It doesn't add much about the context object, but the schema already documents those fields well.

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 concrete verb and object: "Tell the Pipeworx team something is broken, missing, or needs to exist." It then enumerates the exact feedback categories (bug, feature/data_gap, praise), making the tool's role unmistakable and clearly distinct from the research/lookup siblings.

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

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

The description gives explicit when-to-use conditions for each feedback type: wrong/stale data = bug, missing tool = feature/data_gap, positive experience = praise. It also gives a strong exclusion condition: feedback about tools from other MCP servers should be filed elsewhere, with a practical test for disambiguation based on the tool name source.

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

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

Even though annotations already mark this as read-only, open-world, idempotent, and non-destructive, the description adds meaningful behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h depending on window. This goes well beyond what the annotations alone convey.

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

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

The description is tight and well-structured: it leads with the core signal, then states the return values, then gives practical use cases, then adds important data provenance and caching details. No sentence is wasted, and the 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?

For a simple one-optional-parameter tool with no output schema, this description is complete: it explains what is returned, the available windows, the underlying data source, privacy characteristics, caching behavior, and practical applications. An agent has everything needed to decide whether and how to call it.

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

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

Schema coverage is 100% for the single optional window parameter, so the schema already explains the enum and the trade-off between shorter and longer windows. The description does not add much parameter-level detail beyond restating the window options and cache behavior, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window, which is a specific verb-resource pairing. It conveys the trending/social-proof nature of the data, making it easy to distinguish from a general tool-discovery tool like 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 'Useful for' list gives concrete contexts: surfacing hot data sources, validating canonical tool choice, and checking alignment with other agents' needs. It provides clear usage guidance without explicitly naming alternatives or when-not-to-use cases.

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

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

Annotations mark the tool read-only and non-destructive, and the description adds substantial behavioral detail: partition filtering, similarity thresholds, fill-check against live CLOB depth, and the difference between theoretical and realizable edge. 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?

Dense but every sentence carries operational value: mode selection, examples, filters, response fields, and fill-check caveat. It is front-loaded with the core purpose and uses clear mode headings to keep a complex tool navigable.

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 invocation patterns, parameter semantics, response shape, edge-case filters, and real-world trading caveats. Since there is no output schema, the explicit response field list and fill-check explanation are especially valuable and sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: event mode checks date/threshold ordering plus partition sum, while topic mode flattens related events and catches cross-event patterns. It also documents the no-arg behavior, which the schema cannot express.

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

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

States a clear specific action: find arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It also distinguishes operational modes (trending_scan, event, topic) and references polymarket_fill_risk for custom sizing, helping the agent tell it apart from sibling tools.

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

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

Provides explicit when-to-use guidance: no args for trending scan, event for a specific market, topic for cross-event scanning, and names polymarket_fill_risk for custom sizing. It also tells the agent when not to trade (realizable_edge_pp <= 0), making decisions concrete.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive. The description goes well beyond them by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), diagnostics output (_diagnostics with funnel counters), the 24h-move warning, slippage assumptions, and the caveat that the edge may already be priced in. This is rich, honest behavioral context with no contradiction.

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

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

The description is long and dense, but the tool is genuinely complex: five model families, three response segments, multiple filter knobs, diagnostics, and caching behavior. It is front-loaded with purpose and uses caps, numbering, and grouped sections to aid scanning. A more compact version would risk losing important caveats and segment semantics.

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 compensates well by documenting the top-level response shape (by_segment, fed_candidates/fed_note, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), and the caveats that explain empty results. For a complex 9-parameter discovery tool with no required arguments and no output schema, this is unusually 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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by grouping knobs into 'TRADEABLE-EDGE KNOBS' and explaining nuanced interaction, e.g. min_kelly never filters partition arbs because parent-level kelly_fraction_half is 0 by design, while min_partition_leg_kelly applies per-leg instead. This is genuinely useful semantic context, though much parameter detail already lives 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 states a specific verb and resource ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and frames the intended use case ('what should I bet on today'). It names the three response segments and model families, making the tool's scope concrete and distinguishable from siblings like polymarket_arbitrage.

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

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

The description gives clear context for when to use the tool: discovering today's betting opportunities without paging hundreds of markets. It also explains what is excluded (Fed bets from ranking) and why. It does not explicitly name sibling alternatives or state when to prefer a different tool, but the use-case framing is strong enough to guide an 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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds substantial behavioral context beyond that: history depth bounded by the 60-day snapshot TTL and snapshotting-enablement start, data gaps meaning 'nobody scanned that day' (cache-miss write semantics), decay computed on daily closes of edge_pp_net rather than intraday, the signed-value convention (negative = SELL YES), and the median-lifespan 'competition clock' framing. This provenance and computation-basis disclosure is exactly what an agent needs to correctly interpret results.

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

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

Though lengthy, every sentence earns its place: the purpose is front-loaded, args are summarized in one clause, the RESPONSE section is needed because there is no output schema, and the LIMITS section discloses TTL, provenance start, and computation basis. The organization (purpose → args → response → limits) makes the density navigable, and even the conversational aside ('wide for a reason nobody is willing to take') carries interpretive value for trade assessment.

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 the return shape, and it does so exhaustively: tracked[] with edge_pp_net time-series, first_seen, trend enum values, and decay_pp_per_day; expired[] with lifespan_days and its interpretive meaning; snapshot_dates[] with the cache-miss gap explanation. Combined with the LIMITS caveats, an agent has everything needed to call the tool correctly and interpret results — nothing material is missing.

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

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

Schema description coverage is 100%, so per the baseline rule a 3 applies even without param info in the description. The description does restate the parameters ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') with a marginal addition — the phrase 'snapshot family' links window to the snapshot-storage concept — but it does not materially extend what the schema already documents.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' and immediately frames the core question ('how long has this edge existed and is it shrinking?'). It clearly distinguishes itself from the sibling polymarket_edges by positioning itself as the historical-persistence layer on top of those snapshots, while the concrete contrast ('a fresh wide edge and a 3-week-old wide edge are different trades') makes 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 gives strong contextual signals about when to use it — the entire framing is temporal ('how long has this edge existed', 'first_seen', 'lifespan_days', 'decay_pd_per_day'), and it references its relationship to polymarket_edges ('built from daily polymarket_edges snapshots'), letting an agent infer that point-in-time edge scanning belongs to the sibling tool. However, it never explicitly names an alternative or states 'use X when ... not Y,' so the when-not-to-use guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it explains that basket fills can strand the user unhedged, that returns include per-leg fill detail and thin_legs[], and that size_usd is clamped 10–1,000,000. It would earn a 5 if it stated whether the CLOB check is point-in-time or subscribes to live updates, but the added risk disclosure is substantial.

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: mode requirements are front-loaded, single-market and basket behaviors are separated with clear labels, and the risk warning is placed at the end where it reinforces usage. It is longer than typical descriptions, but every sentence carries operational information. A 5 would require slightly better scannability, such as bullet-like breaks for the two modes, but the structure is strong 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?

The description is complete for a high-complexity tool with no output schema: it defines both modes, explains the meaning of size_usd in each mode, lists return fields, identifies risk conditions (thin legs, partial fills, unhedged positions), and gives explicit usage triggers. The only minor gap is not describing the format of apex output or error cases, but with 100% schema coverage and such a rich natural-language spec, no essential call-time information is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters well, giving a baseline of 3. The tool description goes further by explaining how size_usd is interpreted differently in single-market vs basket mode (spend/proceeds vs settlement notional), and how side default is auto-derived from partition sum in basket mode. This adds meaning beyond the schema, so a 4 is appropriate, though it falls short of 5 because the description doesn't give examples of slug/URL formats or clarify whether market and event are mutually exclusive beyond 'REQUIRES one of'.

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

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

The description clearly identifies the tool as a fill-risk/edge-capture check against live CLOB order-book depth, with explicit modes (single-market vs basket) and a specific verb ('checks', 'walks the ladder'). It distinguishes itself from siblings by naming polymarket_arbitrage and polymarket_edges as tools it should precede, so an agent can differentiate it from those alternatives.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', giving both a clear trigger condition and a specific alternative context. It also explains when not to rely on theoretical overround, which is strong when-to-use guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing fee modeling limitations, compatibility warnings, unclassified legs never being paired, temporal-alignment semantics, and the fact that all returned spreads are gross rather than net tradeable edge. It also explains that compatibility fields must be read even when matched_pairs > 0.

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 highly structured with labeled sections and front-loaded purpose. It contains redundant emphasis around safety fields and warnings, and the extended code list adds bulk, but almost every sentence carries needed operational detail, especially given the absence of an output schema.

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 is unusually complete: it covers the response shape, per-leg pricing, spread direction, compatibility codes, skipped categories, temporal alignment meaning, fee caveats, and statistical rarity of real spreads. An agent has enough context to invoke the tool and interpret results safely.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it explains that topic auto-fetches the matching event, that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and that both modes run the identical token-overlap matcher. This materially improves an agent's ability to choose and combine parameters correctly.

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: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It clearly explains what the tool computes and gives two concrete operating modes. It does not explicitly name and contrast sibling tools like polymarket_arbitrage, so it stops short of full sibling differentiation.

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

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

The description gives clear usage context: either use a pre-mapped topic shortcut or supply explicit event identifiers, and it warns that pre-mapped does not imply tradeable. It does not explicitly state when to prefer this tool over alternatives or when not to use it, but the mode descriptions make the intended invocation path clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: scoping to identifier (anonymous IP, BYO key hash, or account ID) and the omit-key behavior for listing all keys. It doesn't describe missing-key error behavior, but the safety profile is already covered by annotations.

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

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

Three sentences with no filler. The main action is front-loaded, the usage context follows, and the sibling pairing is stated in the final sentence. 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 one-optional-parameter read tool with no output schema, the description is complete: it covers purpose, usage context, scoping, the list-all behavior, and the related tools. The schema examples further cover calling patterns. Nothing critical is missing.

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

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

Schema description coverage is 100%: the only parameter `key` is fully documented with its own description and examples. The tool description reinforces the omit-to-list behavior but does not add any new parameter semantics beyond what the schema already provides. Baseline 3 applies.

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

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

The description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), then explicitly covers the alternative behavior of listing all keys when the key is omitted. This clearly distinguishes it from sibling tools like remember and forget.

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

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

Explicitly states when to use the tool: 'look up context the agent stored earlier... without re-deriving it from scratch.' It also names the sibling pairing ('Pair with remember to save, forget to delete'), which tells the agent how this tool fits with alternatives.

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

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

Annotations already convey readOnly, idempotent, non-destructive, and open-world behavior. The description adds meaningful behavioral context on top: the feed is persisted, the evaluator writes to it, mark_read flags events read on the same call, and unread_only filters on read_at. It also notes that the same feed is exposed at a public URL, which is useful for an agent deciding between polling this tool and using HTTP.

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

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

Three sentences, front-loaded with what the tool returns, then filters, then read-state behavior, then polling note. Every sentence carries distinct information and there is no repetition of schema boilerplate.

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

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

For a read-only polling tool with no output schema, the description covers the key semantics an agent needs: what events are returned, how filters work, how read-state changes behavior, and an alternative URL for scripts/dashboards. It doesn't document pagination beyond a limit parameter or what the exact response shape looks like beyond the listed fields, but that's minor given the 100% schema coverage and the simplicity of the operation.

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 already documents all five parameters. The description adds only light semantic context (e.g., 'sec_8k' as an example for type, mark_read affecting the next call, since meaning fired_at >= the timestamp). That extra context is valuable but modest; a 3 baseline is fair when schema covers everything.

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

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

States a specific verb ('Pull'), a specific resource ('fired events from your subscription feed'), and what the returned data carries (source, citation_uri, raw payload). It is clearly distinguishable from siblings like list_subscriptions (manage subscriptions) and recent_changes (different feed 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?

The description explicitly says filtering by type and since, and polling is fine, plus points to an alternate access path (GET registry.pipeworx.io/alerts.json) for scripts. It does not name a sibling alternative to prefer for a given condition, but it gives enough context for an agent to know when to call it.

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

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

The description goes well beyond the annotations by disclosing the parallel fan-out to SEC EDGAR, GDELT→GNews fallback behavior, rate-limit/5xx handling, the USPTO PatentsView sunset issue, and that the tool 'soft-fails until reactivated.' It also describes the return shape with changes[], total_changes, and citation URIs, giving the agent accurate expectations for a read-only, idempotent call.

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: query triggers, core capability, data sources, fallback logic, date format, return structure, and sibling routing. Important details are front-loaded and grouped coherently, with no filler or redundant restatement of the title.

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 sufficiently explains inputs, date handling, source behavior, failure modes, and return structure. The explicit pointer to entity_profile covers the main alternative, so an agent has enough context to invoke recent_changes correctly without additional lookup.

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 schema already documents type, since, and value. The description adds a useful recommendation ('Use "30d" or "1m" for typical monitoring') and examples of ticker/CIK formats, but these are minor enrichments over schema definitions rather than substantial new 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 opens with concrete natural-language triggers and then states the core purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the resource (company change feed), the window behavior, and clearly differentiates this from the sibling entity_profile by noting the alternative for static profiles.

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

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

Usage is made explicit through query examples and a direct routing instruction: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also clarifies the fallback behavior across data sources, so an agent knows when this tool is appropriate and when it should select a sibling.

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

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

The description adds meaningful behavior beyond annotations: storage is a key-value pair scoped by the agent identifier, authenticated users get persistent memory, anonymous sessions expire after 24 hours, and recall/forget are the companion tools. No contradiction with the readOnlyHint/idempotentHint 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 tightly written and front-loaded with the core purpose. Each sentence adds useful information: when to use, how storage works, persistence behavior, and companion tools. There is no filler or repetition.

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

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

For a simple two-parameter write tool with no output schema, the description is complete. It covers purpose, usage triggers, storage semantics, retention behavior, and sibling tool routing. No critical information needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the key/value model and gives examples that closely mirror the schema descriptions, but it does not add significant per-parameter meaning beyond what the schema already provides.

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

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

The description states a clear verb and resource: 'Save data the agent will need to reuse later,' with concrete example content (ticker, address, preference, research subject). It also distinguishes the tool from its siblings by framing it as the write side of a memory pair with recall and forget.

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

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

The description gives explicit when-to-use guidance: 'Use when you discover something worth carrying forward,' with concrete examples. It does not state when not to use the tool or explicitly compare to alternative memory tools beyond naming recall and forget, so it stops short of a full 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 establish readOnly/openWorld/idempotent/non-destructive behavior. The description adds valuable transparency about internal cascading lookups, graceful degradation when GLEIF or OpenFIGI is unavailable, explicit `unresolved` reporting, source labels on every identifier, and the FIGI candidate behavior. It also clarifies that non-equity instruments like bonds resolve via name search rather than ticker. These behavioral details go far beyond the annotations and help an agent anticipate real 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 dense and long, but every segment earns its place given the tool's complexity and the many identifier domains. It is front-loaded with examples, the core directive is early ('Use FIRST'), and supplementary technical detail is grouped logically. It could be tightened slightly, but it remains a high-value, well-structured explanation rather than padding.

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

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

For a tool with no output schema and two required parameters, this description is extremely complete: it covers input forms, output identifiers, candidate behavior, source attribution, unresolved handling, graceful degradation, internal cascading, and even the tricky case of non-US/ISIN-linked legal entities. Given the complexity of cross-source entity resolution, little is missing for an agent to know when and how to invoke it.

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

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

Schema coverage is 100% and the schema already describes each parameter clearly, but the description and schema together add substantial meaning: for `value`, the twist about passing only the issuer name exactly as printed and not trailing security-class words is critical disambiguation not inferable from the schema. For `type`, the description explains what each enum value returns across sources. This goes well beyond a baseline 3 and meaningfully prevents misuse.

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 rich set of natural-language examples ('What's the ticker for...', 'find the CIK for...') and immediately states the core purpose: resolving a user-spoken name to canonical identifiers required by other tools. It explicitly enumerates supported types and outputs across multiple domains (SEC CIK/ticker, GLEIF LEI, OpenFIGI FIGI, RxNorm RxCUI), which distinguishes it clearly from any sibling by the verb 'resolve' plus the identifier resources.

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 usage direction: 'Use FIRST whenever you have a name but need an ID.' It also states where alternatives fit based on the type enum (company vs drug), and gives exclusion-style guidance: when a name matches multiple instruments, it returns figi_candidates rather than asserting, which is 'the correct answer to an issuer name that does not identify a single bond.' This is unusually actionable for when-to-use and what-to-expect.

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

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

Annotations already establish read-only, idempotent, open-world behavior; the description adds process detail: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, and signal density. No contradictions or hidden side effects.

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 tight sentences with the main purpose front-loaded. The quoted use-case example adds clarity without padding, and 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?

Covers what the tool does, how it works, when to use it, and what it returns, which is especially useful given there is no output schema. It could additionally reference model selection or API key handling, but those are already fully documented in the input schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description reinforces the entities concept as 'your brand + N competitors' but does not add meaningful parameter-level detail beyond the schema's own documentation.

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

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

States a specific action ('Compare AI visibility across multiple entities side-by-side'), identifies the probe mechanism (ai_visibility_check), and describes the ranking output. This clearly distinguishes it from single-entity tools like ai_visibility_check and generic compare_entities.

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

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

Gives a concrete use case ('competitive AI-marketing audits') and an illustrative question that makes the intended scenario vivid. However, it does not explicitly name alternatives or state when not to use this 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?

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds valuable behavioral detail beyond those annotations: bundlephobia first-measurement latency (5-30s), graceful partial-failure handling via sources_failed, and the specific summary fields returned. It does not fully disclose rate limits or exact failure shapes, but it clearly exceeds minimum transparency given the rich annotations.

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

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

The description is dense but highly efficient: three sentences cover purpose, data sources, output format, ecosystem boundaries, latency, and failure behavior. It front-loads the core value proposition and each clause carries distinct information. No fluff or repetition of schema fields.

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

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

For a two-parameter read-only tool with no output schema, the description is unusually complete. It tells the agent the exact output fields, the failure mode, the latency caveat, and the ecosystem boundary. The absence of an output schema is mitigated by the enumerated summary block and per-advisory detail mention.

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 already 3 because both parameters are documented in the schema. The description adds meaning beyond the inline schema: it states that version defaults to latest when omitted, scoped packages are accepted for package, and it connects the parameters to the output summary via is_latest. This raises the score to 4 rather than leaving it at 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 explicitly states a composite check with a clear verb ('should I add this npm package'), names the data sources (deps.dev, bundlephobia), and enumerates the exact output fields. It distinguishes itself from the sibling scan_competitor_ai_presence and general lookups by framing the use case around npm package evaluation.

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

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

It gives explicit when-to-use triggers ('Use whenever an agent asks...'), scopes the ecosystem (NPM only in v1), and tells the agent where to route non-NPM ecosystems (deps.dev:version directly). This is actionable routing guidance beyond what the schema or annotations provide.

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?

Although annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context beyond those flags: truncation behavior ('cap is 200K chars (longer inputs are truncated and flagged)'), implementation details ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), and output feature ('every passage carries an offset so the agent can verify a verbatim quote'). No contradiction with annotations is present.

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

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

The description is tightly written and front-loaded: the first sentence gives the core purpose, followed by mechanics, usage condition, integration, and implementation details. Each sentence earns its place—there is no filler or repetition. The only possible redundancy is the cap mention in both the schema and description, but it is justified as a behavioral clue for the agent.

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 values; it does so by stating 'top-N passages with character offsets and similarity scores.' It also covers input limits, truncation flag, and integration workflow. A fully explicit response structure (e.g., exact JSON format of each passage) is not specified, but the description provides enough for an agent to understand what will be returned and how to use it.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description reinforces the role of each parameter ('text you already pulled', 'natural-language query', 'top-N passages') but does not add new details beyond the schema. The schema already documents text length, query examples, and limit range/default, so the description adds minimal parameter-specific value.

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: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by explaining it operates on already-fetched text and returns passages with offsets and similarity scores, and explicitly pairs with ask_pipeworx_grounded, which uses the gateway to fetch. This makes differentiation from other search or Q&A tools immediate.

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

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

The description states an explicit condition: 'Use when the record is too big to cram into the prompt.' It also provides a concrete workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document,' which routes the agent to the correct alternative (ask_pipeworx_grounded) and clarifies this tool is for offline passage extraction. This is strong guidance with clear exclusions and integration hints.

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 non-read-only and non-destructive behavior, and the description adds substantial real-world context: anonymous/BYO cannot persist subscriptions, SMS is capped at 10/day, webhook delivery auto-disables after 10 failures, and the webhook signing secret is only returned once. This goes far beyond what annotations provide and fully discloses important behavioral gotchas.

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

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

The description is long but dense, and all content earns its place given the tool's many subscription types and delivery options. It is front-loaded with the core purpose and return value, then organizes type-specific and delivery-specific details in a readable way. Slightly long, but justified by 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?

For a tool with three complex parameters and no output schema, the description covers what the agent needs: the required auth context, all supported types with parameter examples, delivery behavior, return value (subscription id), and the one-time webhook secret. No major operational gap remains.

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

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

Although schema coverage is 100%, the description enriches the parameters with concrete examples for each type (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') and adds delivery constraints (phone verification, 10/day cap, HMAC signing, once-only secret). This is meaningful value beyond the schema, not mere repetition.

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 ('create'), resource ('subscription'), and goal ('proactive monitoring subscription to a live-data event stream'). It also enumerates supported subscription types and delivery channels, making the tool's scope immediately distinguishable from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description gives strong contextual guidance about prerequisites (Pipeworx OAuth account, verified phone for SMS) and supported types, but it does not explicitly state when to prefer this tool over sibling tools or mention exclusions like 'use recent_alerts instead for one-time pulls.' The usage context is clear, but alternatives are not named.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description goes beyond annotations by disclosing the return shape (category-bucketed example questions with tool and argument mapping), the live-catalog source, and the no-argument/filtered-topic behaviors. This is more behavioral detail than the minimum.

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

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

The description is dense and front-loads the core purpose, but it is slightly padded by listing many query phrasings and the full set of categories. Still, every major sentence contributes: purpose, output format, argument behavior, and usage timing.

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 adequately explains what will be returned: category-bucketed example questions, each paired with the exact tool and argument shape. It also covers argument handling, the live catalog source, and the intended first-use scenario, leaving no critical gap for an agent deciding whether and how to call it.

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

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

The schema already covers the only parameter with 100% coverage, including valid focus areas and omit behavior. The description adds example topics and the idea of 'focusing,' but does not meaningfully extend the schema's meaning. Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description clearly identifies a specific purpose: an onboarding entry point that suggests example questions and maps each to the exact tool and argument shape. It differentiates from siblings by framing itself as the 'FIRST' tool to use when the agent does not yet know Pipeworx's capabilities.

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

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

It gives explicit when-to-use guidance: '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 does not explicitly state when not to use it or name direct alternatives, but the context is clear enough to guide selection.

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

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

The description goes beyond the annotations by explaining the actual mutation semantics: the subscription is deactivated, not deleted, and historical events remain available via recent_alerts. This is valuable behavioral context that the annotations (readOnlyHint false, destructiveHint false) do not fully convey.

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

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

Two sentences, no filler, with the core action front-loaded first and important constraints following immediately. Every sentence adds value.

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

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

For a single-parameter mutation tool with no output schema, the description covers the essential context: what action is performed, the ownership restriction, and the side effect (deactivation vs deletion). Nothing critical is missing for an agent to invoke this correctly.

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

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

The input schema already fully describes the single id parameter, including that it is a subscription id returned by subscribe. The description adds no additional parameter-level semantics beyond what the schema provides, 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 states a specific action ('Cancel'), a specific resource ('subscription'), and the key identifier ('id'), making the tool's purpose immediately clear. It also distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation.

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

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

The description clearly implies when to use the tool: when you want to cancel an existing subscription by its id. It also provides a meaningful usage constraint — ownership is enforced, so you can only cancel your own subscriptions.

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, it discloses non-obvious behavior: the six possible verdicts, that could_not_verify means the check did not happen and carries verification_error{stage,detail}, and that unsupported means no covered source exists. The 'IMPORTANT for callers' caveat directly prevents a dangerous misinterpretation.

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 the length is justified by trigger phrases, dual routing paths, verdict semantics, and caller caveats. It is front-loaded with the purpose and organized into clearly scoped sections; only the list of synonymous query phrasings is slightly repetitive.

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

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

Despite no output schema, the description enumerates the return shape (verdict, actual value with pipeworx:// citation, and reasoning) and error semantics. It also explains both internal verification paths and what each non-obvious verdict means, leaving no critical operational gap for callers.

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 at 100% coverage, including tolerance_pct range and override semantics, so the description does not need to repeat them. The description adds context about exact percent-delta math for financial claims, but no additional parameter-level 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 names the exact capability: natural-language claim verification and fact-checking, with explicit trigger phrasings and a clear distinction from generic Q&A. It specifies the verification methods (SEC EDGAR/XBRL fast path vs grounded pipeline) and a defined verdict set, so an agent can separate it from siblings like ask_pipeworx or deep_research.

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

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

States a direct when-to-use rule: 'Use whenever the agent needs to check whether something a user said is factually correct,' and further splits company-financial claims from other factual claims. It does not explicitly name sibling tools to avoid, so it misses the full 5-level 'when-not/alternatives' criterion.

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