Api Ninjas

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context beyond annotations: it mentions the default model, that Anthropic calls require a BYO key with direct payment, and the structure of the return value. This provides useful behavioral insight not covered by annotations alone.

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

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

The description is four sentences, each serving a distinct purpose: main action, configuration details, return type, and use cases. No filler, all content is essential and front-loaded.

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

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

For a tool with 4 parameters and no output schema, the description covers the main purpose, parameter specifics, return structure (including fields like score, confidence, signals, raw_response), and use cases. It lacks details on how the scoring works or what the signals are, but overall it provides sufficient context for an AI agent to understand and invoke the tool correctly.

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

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

Input schema has 100% parameter description coverage, so baseline is 3. The description adds value by explaining the default model for the 'models' parameter and clarifying the role of '_apiKey' (BYO key for Anthropic). This enriches the schema definitions without redundancy.

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 probes LLMs for knowledge about a business/product/topic and returns a visibility score. It specifies the verb 'Probe' and the resource 'LLMs', and distinguishes itself from sibling tools by focusing on AI visibility scoring, which is unique among the listed tools.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key, guiding when to use each. However, it does not directly contrast with sibling tools or state when not to use it.

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

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

Annotations already declare read-only/idempotent/non-destructive behavior, so the safety profile is covered. The description adds the external API Ninjas provenance and, since there is no output schema, the concrete return shape (list of name, taxonomy, locations, diet, habitat, lifespan, top_speed). It does not address rate limits or error behavior, but these are not essential for this simple read-only lookup.

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?

Compact and front-loaded: purpose, return fields, and an example with no filler. Every sentence earns its place, and the most important usage detail (lookup by name) appears immediately.

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-required-parameter read-only lookup, the description provides enough: input example, output fields, and data source. The optional API key nuance is already captured in the schema, and because no output schema exists, the explicit field list completes the picture.

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

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

Schema coverage is 100%; both name and _apiKey have descriptions, including an example for name. The description's 'by name' and cheetah example echo that schema rather than adding new meaning. Baseline 3 applies because the schema carries the parameter semantics.

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?

Opens with a specific verb+resource: 'facts about an animal species by name'. It names the exact returned fields, so an agent can identify it as a direct animal-fact lookup rather than a research or comparison tool. The example appends a concrete invocation, removing ambiguity.

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

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

No explicit when/when-not guidance or alternative tool names appear. The phrase 'by name' and the cheetah example imply that this tool is for fetching facts by species name, but an agent is left to infer when to choose it over broad research tools like deep_research or entity_profile.

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 read-only, open-world, idempotent, and non-destructive, so the description only needs to add nuance. It does so by disclosing the routing behavior, automatic argument-filling, and return format with stable pipeworx:// citation URIs. It stops short of describing rate limits, auth details, or failure modes, but there is no contradiction 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 content is front-loaded and well ordered, starting with the core directive, then usage triggers, examples, and alternative tools. However, it is long, repeats the 'prefer over web search' idea, and ends with a truncated sentence ('Use with key pipeworx-mcp-routing ...'), which weakens the structure.

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 complex routing tool with no output schema, the description covers the invocation decision thoroughly: supported domains, trigger phrases, alternatives, and return behavior (structured answer + citations). The only gap is the incomplete final note about the API key, but the core information an agent needs to select and call the tool correctly is present.

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

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

The schema provides 100% coverage: all six properties are documented, with 'question' defined as a natural-language request accepting five aliases. The description adds only illustrative examples rather than clarifying how to pick between the alias parameters or whether the required field must literally be 'question', so it adds little 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 bold directive 'PREFER OVER WEB SEARCH' and explains the tool routes questions to one of 5,798 tools across 1,517 verified sources, returning structured answers with pipeworx:// citation URIs. It explicitly contrasts itself with named siblings such as ask_pipeworx_grounded, ask_pipeworx_beta, entity_profile, and validate_claim, so an agent can distinguish it at a glance.

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

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

It states when to use the tool: 'START HERE for most questions' and gives trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', plus concrete examples. It also provides explicit alternatives for different cases: entity_profile for single-entity 'why' questions, validate_claim for fact-checking, ask_pipeworx_grounded for fast answers, ask_pipeworx_beta for AI models, and deep_research/pipeworx_trending for exhaustive discovery.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavior beyond that: it is a live experimental edge, no candidate is currently active, it currently matches ask_pipeworx exactly, and it 'falls back to nothing' so it is a full working router rather than a wrapper. This gives the agent a clear picture of the tool's current and expected behavior.

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

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

The description is information-dense and front-loads the beta identity and equivalence to ask_pipeworx. Every sentence contributes key context, though the specific retirement date and the repeated emphasis that it is a full working router add minor length without much additional actionability.

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

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

For a single-required-question router with strong annotations and 100% schema coverage, the description covers identity, current state, usage condition, and experimental risk. It relies on ask_pipeworx for response shape details via 'same response shape,' which is acceptable given the sibling context, but it does not independently describe the return format.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the single question parameter. The description adds no parameter-level semantic detail beyond saying it uses the same arguments as ask_pipeworx. This matches the baseline of 3 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 clearly identifies the tool as the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx sibling by positioning it as the experimental routing variant. The core resource and relationship to the stable tool are unambiguous.

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

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

It explicitly says to use the tool exactly like ask_pipeworx when the user wants the newest routing, and it mentions results are compared against the stable router. The alternative ask_pipeworx is named, but there is no explicit 'do not use when you need stable behavior' exclusion; it is only implied by 'experimental edge'.

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/idempotent/open-world behavior, but the description goes further by disclosing the structured return payload, explicit refusal reasons, the guarantee that answers come only from tool results, and the extra LLM call cost. 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?

Four dense, well-organized sentences cover what it is, how it works, what it returns or refuses, and when to use a cheaper sibling. Critical behavioral details are front-loaded and no sentence is 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 specifies the return shape and failure modes, includes usage boundaries, and even quantifies the extra cost. An agent has everything needed to select and invoke 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?

Schema description coverage is 100%, so the schema already fully documents the question parameter and its aliases. The description adds no parameter-level detail, which is acceptable because the parameter is self-explanatory; 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 a specific and distinctive purpose: a hallucination-resistant answer mode for high-stakes reads. It clearly states the mechanic (extract the answer using only what the tool result contains) and differentiates it from the sibling ask_pipeworx by emphasizing grounded extraction 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 explicitly directs the agent to use this tool when an answer will be quoted, cited, or acted on and fact invention is unacceptable. It also names the cheaper alternative, ask_pipeworx, and says to prefer it for casual lookups, giving clear when-to-use and 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?

Description extensively details behaviors beyond annotations: market matching confidence, parent event extraction, news fallback handling, safety short-circuits for low confidence, closed market handling, illiquid spread warnings, and resolution-rule risk. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial context without contradiction.

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

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

Description is very long and contains extensive details, examples, and edge cases. While comprehensive and front-loaded with core purpose, it could be more concise. However, given the tool's complexity, the length is partially 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?

Despite no output schema, the description thoroughly covers response shapes: result.market fields, result.analysis with model probability and edge warnings, result.evidence keyed by source, resolver contract with confidence and alternatives, parent event extractor, news fields with fallback info, and safety behaviors. It is complete for a complex research tool.

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

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

Schema coverage is 100% with all three parameters described. Description adds significant meaning: explains market parameter accepts slug, URL, or question text with example; depth parameter explains 'quick' vs 'thorough' and default; include_raw explains when to use true/false with response size implications.

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

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

Description clearly states it researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question) and what it does: resolves market, classifies, fans out, returns evidence packet + comparison. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive research with category-specific data packs.

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?

Description gives explicit use cases ("should I bet on X", "what does the data say about Y", "is there edge in Z") and provides many fan-out examples per bet category. It also covers scenarios like low-confidence matches, closed markets, and wide spreads, but does not explicitly list when not to use it or compare to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by specifying the return shape (a list of ten named fields), which is essential because no output schema exists. The external 'API Ninjas' reference hints at an external service, but rate limits and default result counts are left to the schema's limit and _apiKey descriptions.

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

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

The description is two sentences and an example, with no filler. It front-loads the resource and follows with return fields and an illustrative call, making every word informative.

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 lookup with no output schema, the description supplies the essential return fields and a working example, so an agent can form correct invocations. It leaves open whether at least one filter is required (schema says all optional), which is a minor ambiguity. Overall, the output contract is sufficiently clear for this level of complexity.

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

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

The schema already documents all six parameters with 100% coverage, so the baseline applies. The description adds contextual meaning by framing make/model/year/fuel_type as filter criteria and showing an example call, but it does not elaborate on limit or _apiKey semantics beyond the schema. No additional parameter insight is provided.

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 vehicle-specification lookup, naming the resource ('cars') and the query dimensions (make, model, year, fuel type), and enumerates the returned fields. This distinguishes it from sibling API Ninjas tools like animals or exercises by domain, even though it does not name an alternative. A minor weakness is the lack of an explicit action verb such as 'search' or 'lookup,' but 'Returns a list' conveys the behavior.

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

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

The description implies the tool should be used when vehicle specifications are needed, and the example shows a realistic invocation with make/model/year. However, it does not explicitly state when not to use it or name alternatives among the API Ninjas siblings, nor any conditions such as requiring at least one filter. Guidance is therefore 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behavioral quirks: the free plan rotates commodities every week, the tool deliberately avoids publishing a stale list, and unsupported names return found:false along with free_commodities_this_week. It also reveals the exact response shape { exchange, name, price, updated }, which is critical because no output schema exists. 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?

Though longer than average, every sentence earns its place: purpose, return shape, weekly rotation caveat, failure mode, FRED alternative, aliases, and example. The critical usage guidance and return contracts are front-loaded, with supporting caveats following logically. Nothing is redundant or filler.

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

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

With no output schema, the description fully covers return values and failure behavior. It explains the live free-list fallback, names the dependable commodity, provides alternative data sources, documents aliases and the optional API key, and gives a concrete example. An agent has everything needed to invoke this tool correctly in varied situations.

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 real value: it clarifies that commodity and symbol are aliases for name, provides a concrete invocation example, and warns that 'a name outside it returns the current free list rather than an error.' This goes beyond the schema's per-parameter descriptions by explaining behavior tied to the name 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?

States a specific verb and resource: 'live commodity price: current spot price for a traded commodity.' It clarifies scope with concrete query examples like 'gold spot price' and 'silver price today', and distinguishes itself from general web search as the preferred alternative. The purpose is unambiguous even without the title.

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

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

Explicitly says when to prefer this tool over web search and names concrete alternatives: 'For crude oil, natural gas and agricultural benchmarks, FRED carries equivalent series that are always available.' It also advises that gold is the dependable commodity and that unsupported names return the live free list, giving the agent actionable routing guidance.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context: for 'company', it pulls 'LATEST 10-K revenue + net income + cash + long-term debt from SEC EDGAR/XBRL' and handles 'off-calendar fiscal years correctly (AAPL Sep, NVDA Jan).' For 'drug', it pulls 'FAERS adverse-event counts, FDA approval counts, active trial counts.' It also states 'Results sorted by primary metric' and returns 'paired data + pipeworx:// citation URIs per entity.' No contradictions with annotations.

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

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

The description is well-structured and front-loaded with trigger phrases and core purpose. Every sentence adds value (trigger examples, use-case preference, data details, sorting, return format, efficiency claim). It is slightly long but efficient for the information density. A minor trim could be possible, but overall excellent.

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 2 parameters and no output schema, the description is remarkably complete. It covers both entity types with data sources, sorting behavior, return format (paired data + citation URIs), edge cases (off-calendar fiscal years), and an efficiency comparison (replaces 8-15 lookups). No gaps for an agent to decide to invoke or interpret results.

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

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

Schema description coverage is 100%, with clear enum for 'type' and array constraints for 'values'. The description adds context beyond schema: for 'company', it specifies 'tickers/CIKs' and gives examples; for 'drug', specifies 'names' and examples. It also explains what data each type returns, aiding agent understanding.

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 starts with user query examples ('Compare X and Y', 'which is bigger') and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from sibling tools by noting 'ALWAYS PREFER over sequential single-pack lookups' and that it replaces '8–15 sequential lookups.'

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

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

The description lists trigger phrases ('compare', 'X vs Y', 'rank these', 'head to head') and explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear when-to-use guidance and implies when not to use (avoid single-entity lookups).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial context beyond annotations: account/plan requirements, expected latency ('15-60s', thorough 'up to ~90s'), the internal decompose-and-route mechanism, output shape (gaps[], contradictions[], hop field, citation_uri), and the guarantee that citations are always fetchable. No contradiction with annotations.

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

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

The description is long but information-dense and front-loaded with the most critical constraint (account required). However, it is a single wall-of-text paragraph with some redundancy — contradictions[] and the multi-step resolution behavior are each mentioned twice — which slightly hurts scannability.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: findings packet fields, gaps[] for unanswered facets, contradictions[], the hop field, and citation_uri behavior. It also covers auth tiers, latency, and source scope. Nothing an agent needs to invoke or interpret this tool correctly is missing.

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

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

Schema coverage is 100% and the depth enum description is already detailed, so baseline is 3. The description adds meaning beyond the schema: it ties 'thorough' to the paid plan, gives latency expectations per depth, and provides concrete example questions for the 'question' parameter. This lifts it above baseline.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call', and explicitly carves out what it is not ('this is NOT open-web search'). It differentiates itself from siblings by naming when to use ask_pipeworx instead, so an agent can select it correctly without opening the schema.

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, and explicit when-not-to-use: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'. The alternative tool is named and the selection condition is unambiguous.

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, destructiveHint=false. The description adds valuable behavioral context: returns top-N relevant tools with full schemas and curated examples, and that results are ready to call directly. No contradictions. Could mention rate limits or pagination but not necessary for this tool.

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

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

The description is a single dense paragraph but every sentence adds value. It is front-loaded with the core purpose and usage. Slightly longer than minimal but still efficient for the information conveyed.

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

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

Given the tool's simplicity (6 parameters but many aliases, 1 required, no output schema), the description fully covers purpose, usage guidelines, behavioral details, and what results look like (top-N tools with schemas and examples). Complete for an agent to decide when 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%, so baseline is 3. The description mentions the main parameter's purpose (query) and aliases, but the schema already documents all aliases and descriptions. The description does not add meaning beyond what the schema provides for parameters; the behavioral notes about return format are not parameter semantics.

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 verb 'Find tools by describing the data or task' and lists numerous example domains (SEC filings, FDA drugs, etc.), immediately differentiating this discovery tool from its siblings which perform specific analyses.

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 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use and when-not-to-use guidance, distinguishing from other tools.

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

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

The description adds substantial behavioral context beyond the read-only/idempotent annotations: it fans out across multiple named sources, returns sources_used/sources_failed, treats empty sections as real 'no data', and handles private companies with resolved:false plus a notes line. It also discloses that name resolution happens via SEC EDGAR. No contradiction with annotations.

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

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

The description is long but information-dense, front-loaded with usage examples and the 'ALWAYS PREFER' guidance. The source list and edge cases are useful, though the sentence structure is somewhat run-on and could be organized into clearer sections. Every part does contribute value, but it is not maximally concise.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it lists resolved fields, recent_filings, fundamentals, patents, contracts, FDA products, hiring, news, and LEI, plus behavior for no-data and private companies. The flexible input forms and source failure semantics are also covered, making this complete for the tool's complexity.

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

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

The schema already covers both parameters at 100% with clear descriptions. The tool description adds extra meaning by giving concrete examples, explaining that type values are interchangeable, noting zero-padded CIK format, and describing resolution behavior for names. This goes beyond the schema without being essential to understand the parameters.

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: it produces a 'full cross-source profile of a US public company in ONE parallel call'. It includes concrete example queries and distinguishes itself from single-pack SEC/XBRL/news lookups, so an agent can clearly tell what it does and how it differs from related 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 explicitly says to prefer this tool over chaining single-pack lookups when the user asks for a holistic view, and it explains the accepted input shapes. However, it does not address sibling tools like compare_entities or resolve_entity, so there is no explicit guidance on when to use those instead.

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

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

Annotations already establish the read-only, idempotent, non-destructive nature of the operation. The description adds the concrete return shape and a usage example, which is useful but does not go far beyond what annotations communicate.

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

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

The description is two tight sentences with a helpful example and zero filler. Key identity and filtering scope are front-loaded, 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?

For a simple, read-only, zero-required-param tool, the description is largely complete: it communicates the output format, filter options, and an example call. Minor gaps such as default behavior with no filters or pagination details are not critical given the annotations and 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%, so every parameter is already documented. The description reinforces the filter dimensions and provides an example combining muscle and difficulty, but it does not add substantial semantics beyond the schema.

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

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

The description clearly states the resource ('fitness/gym exercises'), the action ('filtered by'), and the specific filter dimensions (muscle, type, difficulty, name). It also lists the exact return fields, making the tool's purpose unambiguous and distinct from the unrelated 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?

The description implies when to use the tool: when an agent needs exercise data filtered by muscle, type, difficulty, or name. It does not explicitly name alternatives or exclusion conditions, but no sibling tool covers this domain, so the context is clear enough for correct routing.

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

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

The description states 'Delete', which aligns with the destructiveHint=true annotation. However, it does not add behavioral details beyond what annotations already provide, such as confirming the irreversible nature of deletion.

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

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

The description is concise, with only two sentences. It is front-loaded with the primary action and immediately provides usage guidance, making it efficient and easy to scan.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and sibling relationships. No additional information is needed.

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

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

With 100% schema description coverage, the parameter 'key' is already well-defined in the input schema. The description adds no further semantic context beyond what is provided.

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 verb 'Delete' and the resource 'previously stored memory by key', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

The description explicitly provides when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember' and 'recall', offering clear 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 indicate safe, read-only, idempotent behavior. Description adds context about fetching, extracting, and emitting markdown, which clarifies the process without contradicting annotations.

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

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

Four concise, front-loaded sentences. Each sentence adds distinct value: purpose, process, output, use cases. No 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?

Description covers all needed context given simple 2-parameter tool. Output format is specified as 'single text blob'. No output schema needed. No gaps.

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

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

Schema covers 100% of parameters with descriptions. Description augments with workflow context (fetches, extracts, emits) and mentions the default and max for max_links, adding value beyond schema.

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

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

Description clearly states the tool generates an llms.txt file for a URL, specifies the output format, and lists concrete use cases. The verb 'generate' and resource 'llms.txt' are unambiguous.

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

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

Provides explicit usage contexts: getting client sites indexed, drafting for own projects, auditing competitors. Does not explicitly mention when not to use or alternatives, but the use cases are 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 cover read-only, idempotent, non-destructive, and open-world behavior, so the description only needs to add non-obvious behavior. It discloses the exact return shape as a list of { year, month, day, event } and shows a sample call, which meaningfully extends the structured metadata.

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 carry all essential information with the primary purpose front-loaded, followed by filter behavior, output shape, and a compact example. No filler or repeated schema text.

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

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

For a simple read-only lookup with no required parameters, the description covers input options, output structure, and a usage example. It does not state default behavior when no parameters are supplied, but the open-world and read-only annotations plus schema make the tool safely callable without that detail.

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 the relationship between parameters ('free-text keyword and/or an exact date') and demonstrates it with an example call. This clarifies combinational semantics beyond what individual parameter descriptions provide.

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 'notable events from world history' and specifies the core operations: filter by keyword and/or exact date, returning a list of event records. This is clear and unambiguous, though it doesn't call out any sibling tool for 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 implies when to use the tool—whenever a historical event lookup with keyword/date filtering is needed—and provides a concrete invocation example. It doesn't explicitly contrast with alternatives or state conditions where another tool should be preferred, so guidance is implied rather than explicit.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the bar for extra behavioral disclosure is lower. The description still adds value by specifying the exact return fields, that results come as a list, and showing a concrete invocation example. No contradiction with annotations.

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

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

The description is compact and front-loaded, with each sentence earning its place: what the tool returns, how to filter, and an example invocation. No filler or redundant restatement of the name or annotations.

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

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

For a simple read-only lookup tool with no output schema, the description is complete: it explains the return format, the optional filtering behavior, and the API key handling is covered in the schema. An agent has enough context to select and invoke 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?

Input schema coverage is 100%, so the schema carries most parameter meaning. The description adds beyond this by clarifying that country and type are optional filters, tying them to the result fields, and providing a usage example. This is a modest but real improvement over the schema alone.

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

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

The description states a specific resource ('API Ninjas inflation'), the data returned (monthly/yearly rates by country), and the optional filters. It clearly distinguishes this from sibling tools by tying it to inflation rates and outlining the result structure.

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 makes the tool's context clear: use it to retrieve latest inflation rates by country, optionally filtered by index type. It does not explicitly name alternatives or exclusion criteria, but none of the sibling tools are inflation-specific, so the intended usage is easy to infer.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by specifying that it returns only active subscriptions by default and that the 'include_inactive' parameter can change this. No contradictions.

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

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

Two sentences with no filler. The first sentence states what the tool does and what it returns; the second explains when to use it. Perfectly front-loaded and efficient.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description covers all needed aspects: purpose, output fields, default behavior, and usage scenario. It is complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with the single parameter 'include_inactive' described. The description reinforces its effect (include cancelled subscriptions) and adds practical context (default false). The parameter's purpose is clear.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). The verb 'list' and resource 'subscriptions' are precise, distinguishing it from siblings like 'subscribe' and 'unsubscribe'.

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 when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implicitly contrasts with subscription creation and deletion tools.

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

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

The annotations are all false and provide almost no behavioral information, so the description carries the full burden. It discloses critical behaviors: rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow for anonymous submissions and later status checking, free usage ('doesn't count against your tool-call quota'), and the team's daily digests affecting roadmap. This goes well beyond what the annotations or schema indicate, giving the agent a clear model of side effects and lifecycle.

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 relatively long but every sentence contributes unique information: purpose, usage triggers, exclusionary scope, content rules, token mechanics, rate limits, and quota impact. It is front-loaded with the core purpose and then details. The length is justified by the tool's complexity (two modes, restrictions, and token flow), though it could be tightened slightly (e.g., 'The team reads digests daily...' is motivational rather than operational). Overall, it is dense but not wasteful.

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 thoroughly covers all necessary context: what the tool does, when to use it, when not to, how to format the message, the two invocation modes (create and check status), rate limits, and what happens after filing. It also explains the significance of feedback ('signal directly affects roadmap'), which helps the agent understand the tool's impact. No critical gaps remain for an agent to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description does add some value beyond the schema: it clarifies the semantic distinction between the two modes (submit feedback with type/context/message vs. check status by passing only claim_token), gives a concrete invocation example for claim_token, and adds a content guideline ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') that is not present in the parameter descriptions. While not a lot, these are meaningful additions, earning above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from all siblings by enumerating the exact feedback categories (bug, feature, data_gap, praise) and stating it is for Pipeworx tools only. No other sibling tool serves this purpose, so there is no ambiguity.

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

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

Usage guidance is explicit and actionable: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: 'if the tool came from a different MCP server... we cannot fix it... file it with that server instead.' Additional rules about describing the issue in terms of Pipeworx tools/packs and not pasting the end-user's prompt provide concrete when-to/how-to guidance beyond the schema.

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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds details about the data source (CF analytics-engine), no PII, and caching behavior (5min-1h), which goes beyond what annotations provide.

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

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

The description is well-structured with the main action front-loaded. It uses bullet points for use cases and concise details about the data source and caching. Minor redundancy could be trimmed but overall effective.

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 covers what is returned (top tools, packs, total call volume), the data source, caching, and privacy. It provides sufficient context for an agent to understand the tool's output and behavior.

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

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

Schema coverage is 100% with one parameter 'window' fully described by an enum and description. The description enhances semantics by explaining that shorter windows surface hot trends and longer windows show steady-state demand.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' over a recent window. This distinguishes it from sibling tools like 'discover_tools', which lists available tools rather than trending usage among AI agents.

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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and aligning use case with agent demand. This gives clear guidance on when to use the tool, though it does not explicitly state when not to use it.

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

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

Discloses extensive behavioral details beyond annotations: explains monotonicity checks, partition sum verification, Jaccard similarity threshold (0.30), partition filter (placeholder slugs), fill check via polymarket_fill_risk, and conditions for no-trade (realizable_edge_pp ≤ 0). No contradiction with readOnlyHint and other 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?

Description is relatively long but well-structured: starts with main purpose, then details each mode, then technical specifics. Each section earns its place given tool complexity. Could be slightly more concise, but front-loads essential info.

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, description details response structure (opportunities[], partition_check, fill check) and mentions custom sizing tool. Covers all relevant aspects for agent invocation: input modes, internal logic, response format, and caveats.

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

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

Schema coverage is 100% with descriptions, but the description adds substantial meaning: clarifies the purpose of each parameter, how event slugs and topic seeds are used, and the algorithmic behavior (similarity checks, filters, response structure). Beyond baseline 3.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, distinguishing between three modes (trending_scan, event, topic). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by its unique functionality.

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

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

Explicitly provides when to use each mode: trending_scan for top markets, event for a specific market slug, topic for cross-event scans. Recommends event for specific markets and notes that cross-event catches patterns single-event misses. Also directs to polymarket_fill_risk for custom sizing.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds caching details (cached 1h at KV level), explains edge calculation, slippage assumptions, and diagnostics sections, fully disclosing behavior without contradiction.

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

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

The description is dense and well-structured with bold headers, but somewhat lengthy. However, every sentence adds value given the tool's complexity; it front-loads the purpose and is organized logically. Still, conciseness could be improved slightly.

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 9 parameters, no output schema, and three segments, the description thoroughly covers response structure (by_segment, diagnostics), cache policy, filter knobs, and even explains why Fed bets are excluded. It leaves no major gaps for an agent to understand input/output.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description goes beyond by explaining rationale (e.g., min_kelly skips too-small opportunities, slippage_pp assumes 20-50bp, min_partition_leg_kelly for per-leg Kelly). This adds significant meaning.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It specifies three segments (model_driven, structural_arbitrage, concentrated_longshot) and is built for daily betting discovery, distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description implies usage for daily opportunity discovery and explains each segment's purpose (e.g., structural_arbitrage for mutually-exclusive events, concentrated_longshot for basket trades). It does not explicitly state when not to use it or list alternatives, but the context is clear enough for an agent to decide.

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 provides extensive behavioral context beyond annotations: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, non-intraday decay), and interpretation nuances (signed edge_pp_net). Annotations already convey safety and idempotency.

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

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

The description is well-structured: a concise purpose sentence, labeled sections for args, response, and limits. Every sentence adds value without redundancy. The length is appropriate for the complexity of the tool.

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

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

Despite no output schema, the description fully documents the return fields (tracked, expired, snapshot_dates) with detailed subfields and meanings. It also covers limitations and data gaps, providing complete context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds defaults and constraints (e.g., 'default 14, max 30' for days) and explains the 'window' parameter as snapshot family with examples, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry, answering specifically how long an edge has existed and whether it is shrinking. It differentiates itself from related tools like 'polymarket_edges' by focusing on temporal analysis.

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 implicitly guides usage by stating the question it answers, but does not explicitly compare to sibling tools or provide when-to-use/when-not-to-use guidance. The detailed response structure helps an agent infer appropriate 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?

The description discloses the tool walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.), and warns about the risk of unhedged directional positions. Annotations already mark it read-only, idempotent, and non-destructive, and the description adds rich behavioral context without contradiction.

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

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

The description is well-structured with clear sections for single-market and basket modes, uses bold/uppercase for key terms, and every sentence adds essential information. It is appropriately sized for the tool's complexity.

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

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

Given the two modes, multiple return fields, and risk warnings, the description is complete. It details both modes, explains return values (despite no output schema), and provides usage context and caveats. No gaps are evident.

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 description adds extensive meaning: explains side defaults and auto-mode in baskets, interprets size_usd differently for buys vs sells and baskets, clarifies market/event requirement. This goes well beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying two modes (single-market and basket) and distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

It explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial fills create directional risk, providing clear when-to-use and 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?

The description extensively discloses behavioral traits beyond the annotations: token-overlap matching, compatibility codes that can be non-empty even with matched pairs, unclassified legs never being paired, temporal_alignment null meaning 'uncomputed' not 'aligned', and gross-vs-net fee caveats. This goes far beyond the readOnly/openWorld/idempotent hints and gives the agent a realistic model of when results are trustworthy.

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 not short, but it is front-loaded with the core purpose and modes, and nearly every sentence carries safety or behavioral detail needed to interpret results correctly. Redundancies like repeating 'BOTH modes' and 'in EITHER mode' and the wall-of-text formatting prevent a perfect score, but no sentence feels gratuitous given the tool's complexity.

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

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

For a tool with no output schema and three optional parameters, the description covers the response shape, safety fields, compatibility codes, per-leg flags, temporal alignment semantics, fee disclosure, and skipped-comparison counters. It is missing explicit guidance for edge cases like calling with no parameters or providing only one explicit pair side, but overall it is substantively complete.

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

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

The input schema already documents all three parameters with 100% coverage, and the description adds meaningful override semantics: kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and both modes run the identical matcher. It leaves slight ambiguity around combinations of topic with only one explicit override, and what happens with no parameters, but it clearly adds value beyond the schema.

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

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

The description opens by stating the exact resource and task: cross-venue spread between Kalshi and Polymarket for the same resolving question. It further distinguishes the tool's scope by emphasizing cross-venue comparison and the two modes, which separates it from Polymarket-only sibling tools. This is a specific verb+resource with clear 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 clearly explains two usage modes — pre-mapped topic shortcuts vs. explicit kalshi_event_ticker and polymarket_event_slug — and warns that most pre-mapped topics currently return compatibility warnings, so pre-mapped is not necessarily tradeable. However, it does not explicitly name alternative tools or state when not to use this tool in favor of a sibling, so it stops short of full exclusion guidance.

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

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

Annotations already provide readOnlyHint and idempotentHint; description adds scoping and pairing context without contradicting annotations.

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

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

Four focused sentences front-loaded with purpose, zero wasted words.

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

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

Complete for a simple retrieval tool with one optional parameter, annotations present, and description covers behavior, scoping, and pairing.

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%; description adds value by clarifying that omitting key lists all keys, and provides usage examples.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb+'resource' and explicit mention of sibling tools (remember, 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 explains when to use it (look up context stored earlier) and pairs it with remember/forget, but lacks an explicit when-not-to-use statement.

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?

Describes return format (source, citation_uri, raw payload) and side effect of mark_read flagging events as read. Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, and the description enhances understanding without contradiction.

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

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

Concise yet comprehensive; every sentence adds value. Front-loaded with core purpose, followed by payload details, filtering options, and a note on polling and alternative access.

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 all necessary aspects: what is returned, filtering, pagination (limit), read state management, and alternative access. No output schema, but description sufficiently explains expected data.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by exemplifying 'type' filter with 'sec_8k' and explaining mark_read behavior. Does not add much for limit or unread_only, but overall improves clarity.

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 'Pull fired events from your subscription feed', specifying the verb and resource. It distinguishes itself from siblings like list_subscriptions and recall by focusing on retrieving events from the feed with specific payload details.

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 guidance on when to use (polls work fine) and mentions an alternative HTTP endpoint. Explains filtering options but does not explicitly state when not to use this tool vs other tools.

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

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

Annotations already indicate safe, read-only, idempotent operation. The description adds valuable behavioral details: parallel fan-out to multiple sources, fallback logic (GDELT→GNews on rate limits/5xx), soft-fail for USPTO, and return structure (changes[] grouped by source, total_changes count, citation URIs). No contradictions.

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

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

The description is a single well-structured paragraph that front-loads the purpose and example queries. It covers all essential aspects (sources, parameters, fallbacks, alternatives) without redundancy or fluff.

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

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

Despite the tool's complexity (multi-source, fallbacks, error handling) and absence of an output schema, the description is complete. It explains the behavior of each source, what happens on failures, the return format, and provides a clear alternative tool.

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

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

Schema coverage is 100% with descriptions. The description adds extra context: examples of relative shorthand ('7d', '30d', '3m', '1y') and suggestion for typical monitoring. It clarifies that 'value' accepts ticker or CIK, and 'type' is only 'company'.

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 provides a change feed for a company within a time window, with specific example queries ('What's new with X', 'latest on Y'). It lists the data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling 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?

Explicitly tells when to use (e.g., 'What's new with X') and when not to ('Use entity_profile instead when you want the static profile'). It also cautions about USPTO soft-fail and provides parameter suggestions (e.g., use '30d' for typical monitoring).

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), description adds valuable context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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?

Description is concise with four focused sentences. Front-loaded with purpose. Slightly dense but efficient; could benefit from more structuring but remains clear.

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, description adequately explains persistence behavior, scoping, and pairing with sibling tools. Covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both key and value. Description adds value by explaining the key-value pair concept and giving example key formats, though schema already includes examples.

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

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

Description clearly states the tool saves data for reuse across conversations or sessions, using a verb-resource pair ('Save data'). It distinguishes from siblings like recall and forget by mentioning them explicitly.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

The description richly discloses behavior beyond annotations: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates when a name matches multiple instruments, and clearly reports unresolved identifiers. It also explains non-equity instrument resolution and ISIN-to-LEI mapping. Even with strong annotations, this adds substantial behavioral context without contradicting them.

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

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

The description is long but front-loaded with examples and organized into clear sections. It is verbose, yet nearly every sentence adds operational detail needed for correct use. Some redundancy and length could be trimmed, but the structure supports quick scanning by an 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?

Despite having no output schema, the description covers input constraints, entity types, resolution behavior, ambiguous-match handling, unresolved reporting, enrichment degradation, and internal cascading. An agent has enough context to select and invoke this tool correctly without needing to infer missing behavior.

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 substantially enriches parameter meaning: it explains that value must be the entity name only, warns against including full noun phrases, details accepted formats like ticker, CIK, ISIN, company name, and drug brand/generic names. This goes far beyond the schema's brief property descriptions and materially improves correct invocation.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with concrete examples like 'ticker for...' and 'CIK for...'. It also enumerates supported entity types and distinguishes itself from other tools by positioning it as the first stop when a name needs an ID. This is a specific verb+resource with strong scoping.

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

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

The description gives explicit guidance to 'Use FIRST whenever you have a name but need an ID' and provides examples of suitable queries. It describes what inputs are accepted per entity type. It does not enumerate sibling alternatives or state when not to use it, but the 'Use FIRST' directive provides clear usage context.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint false. Description adds how the tool works: probes each entity with ai_visibility_check, ranks by score, and surfaces results. No contradictions.

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

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

Two sentences, front-loaded with the core action, no wasted words. Structure is efficient.

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 explains the return format (ranked list with score, confidence, signal density per entity). It covers what, why, and when, making it 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%, with each parameter already described. The description does not add new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them, and identifies most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a practical use case ('Useful for competitive AI-marketing audits') and an example question. It doesn't explicitly state when not to use or list alternatives, but the context and example are clear enough.

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 it as read-only, idempotent, and non-destructive. The description adds significant behavioral context: fans out to multiple services, partial failures degrade gracefully, bundlephobia timing, and sources_failed listing. 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 a single well-structured paragraph. Every sentence adds essential information—purpose, scope, usage, return details, error behavior—with no wasted words.

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

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

No output schema exists, but the description thoroughly covers return values: summary block fields, per-advisory details, links, alternatives. Also addresses error handling and partial failures. Complete for a composite analysis tool.

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

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

Schema coverage is 100%, but the description adds meaningful context beyond the schema: scoped packages accepted, version defaults to latest. Adds value without redundancy.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'scan' and 'check' and distinguishes from siblings by explicitly noting NPM ecosystem only.

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

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

Explicitly states when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also clarifies NPM only and that other ecosystems use deps.dev directly.

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

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

The description adds behavioral details beyond annotations: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, caps input at 200K chars with truncation flagging, and ensures each passage includes an offset for verification. 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 a single paragraph that is fairly concise given the detail it packs. It could be more structured (e.g., bullet points), but it is still readable and front-loads the core purpose.

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

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

The description covers the main aspects: purpose, usage guidance, technical implementation, input constraints, and output format (offsets and similarity scores). Given no output schema, it sufficiently explains what the tool returns, making it complete for this complexity level.

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 parameter meanings with examples (e.g., 'supply-chain risk') and mentions default limit of 5, but adds limited new semantic value beyond the schema.

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

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

The description clearly states it performs semantic search within a fetched record, with examples like SEC 10-K and article. It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded, and specifies returning top-N passages with offsets and scores.

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 advises using this tool when a record is too large for the prompt, saving context by returning only relevant passages. It also mentions pairing with ask_pipeworx_grounded, providing clear context for when this tool is appropriate, though it lacks explicit when-not-to-use conditions.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: requires OAuth account, anonymous/BYO cannot persist, delivery channel behaviors (always-on feed, email, SMS with 10/day cap, webhook with HMAC signing and auto-disable after 10 failures), and type-specific parameter constraints. No contradictions.

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

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

The description is a single dense paragraph with clear sections (purpose, requirement, types, delivery channels). Every sentence adds value; no redundancy or fluff. Front-loaded with core purpose.

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

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

Given the tool's complexity (multiple subscription types, delivery options, authentication, rate limits, webhook signing), the description covers all necessary information. Even without an output schema, the return value (subscription id) is mentioned. No gaps identified.

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 rich examples per subscription type (e.g., sec_8k items mapping) and delivery constraints (phone verification, webhook secret once). This goes well beyond the schema descriptions, making parameter usage clearer.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource with return value, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description provides explicit context on when to use (for proactive monitoring), requirements (Pipeworx OAuth account), and examples per type and delivery channel. While it does not explicitly say 'do not use for listing', the sibling names imply the distinction. Still, could be more explicit about alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that results are example questions with tool+argument shapes. No contradictions.

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?

Description is a single paragraph but contains parenthetical lists and multiple questions inline. It could be more concise, but it is front-loaded with the key purpose.

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

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

Given the tool's simplicity (1 optional param, no output schema) and rich annotations, the description fully covers when and how to use it, what it returns, and its role as a starting point.

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

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

Schema coverage is 100% with a descriptive parameter topic. Description adds context that omitting it returns a full spread, and provides example values like 'finance', 'pharma'.

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

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

The description clearly states it is the onboarding entry point for an agent, returning category-bucketed example questions with exact tool calls. It distinguishes from sibling tools like ask_pipeworx and 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?

Explicitly advises using this tool first when the agent does not know what Pipeworx can do, and mentions how to call meta-tools. Includes guidance on optional topic parameter to narrow results.

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 indicate non-destructive and idempotent. Description adds that the row is deactivated (not deleted) and historical events remain via 'recent_alerts', exceeding annotation coverage. 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?

Two sentences with front-loaded purpose, ownership, and side effect. No wasted words.

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

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

For a single-parameter tool without output schema, the description fully explains the action, ownership constraint, deactivation effect, and links to historical data via sibling tool 'recent_alerts'.

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 covers the 'id' parameter as a subscription uuid. The description does not add additional semantics beyond what the schema provides, so baseline 3 applies.

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

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

Description states 'Cancel a subscription by id' with clear verb-resource pairing. Distinguishes from siblings 'subscribe' and 'list_subscriptions' by specifying the cancel action and deactivation behavior.

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

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

Ownership is explicitly enforced ('only cancel your own subscriptions'), providing clear when-to-use context. Does not explicitly state alternatives, but the sibling list implies options like 'list_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?

Annotations already mark readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: the dual-pipeline routing, verdict semantics (could_not_verify vs unsupported), and error structure, which are not present in 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?

Though long, the description is front-loaded with trigger phrases and every sentence contributes operational detail (verdicts, citations, error handling). There is no redundancy or fluff for a tool with this 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?

Despite lacking an output schema, the description fully specifies return values (verdict, actual value, citation, reasoning), covers error cases (could_not_verify, unsupported), and explains the two verification paths. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds operational value: tolerance_pct overrides the implied tolerance, has a default cap of 5, and is recommended set to 1–2 for hallucination detection. This goes beyond the schema's basic definitions.

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

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

The description uses a specific verb ('verify') and resource ('natural-language claim') and lists clear trigger phrases and examples. It clearly distinguishes itself from siblings by focusing on fact-checking rather than general question answering.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It further partitions financial vs other claims and notes that it replaces 4–6 sequential calls, giving clear when-to-use context and an implicit alternative.

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