Pexels

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral details: the default free model (Workers AI Llama-3.3-70b), the optional Anthropic probing with a BYO key and direct payment, and the exact per-model return structure. It does not contradict the annotations and enriches the agent's understanding of cost and execution.

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

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

The description is two sentences, front-loaded with the core purpose, then efficiently adds default behavior, key requirement, return schema, and use cases without unnecessary detail. Every phrase contributes value.

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

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

Even without an output schema, the description specifies the exact per-model return fields ({score, confidence, signals, raw_response}) and the combined view. It covers default model selection, optional costing, and practical scenarios, making it complete for a 4-parameter tool with full schema descriptions.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the default model ('Workers AI Llama-3.3-70b (free)'), the relationship between models and _apiKey (only needed if 'anthropic' is included), and the purpose of context ('Helps disambiguate common names'). These clarifications go slightly beyond the schema's individual parameter descriptions.

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

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

The description clearly states the action ('Probe one or more LLMs'), the target ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). This specific verb+resource+output distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence, which focus on different aspects.

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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool. It does not explicitly mention when not to use it or name alternative tools, so it falls just short of a 5.

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

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

Annotations already signal a safe, idempotent, read-only operation, so the description goes beyond by explaining that the tool actively routes to thousands of underlying tools, fills arguments automatically, and returns structured answers with concise stable pipeworx:// citation URIs. This gives an agent a realistic mental model of what will happen at call time, although it does not mention potential latency or upstream tool limits.

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

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

The description is longer than the minimum but every sentence contributes: priority rule, domain list, mechanics, trigger phrases, examples, and sibling exclusions. The key 'START HERE' message is front-loaded and the examples are concrete. It could be trimmed slightly, but the density is justified for a central routing 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?

This is a complex meta-tool with a heterogeneous data space and no output schema, yet the description explains what it accepts (natural language questions), how it works (routing and filling arguments), what it returns (structured answers with citations), and when to pick an alternative. Given the breadth of the tool, nothing crucial 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?

All parameters are aliases for the `question` parameter and are already well documented in the schema, including the accepted alias names. The description reinforces the overall natural-language usage and adds trigger examples, but it does not need to add much further parameter-level semantics; baseline 3 is appropriate given 100% schema coverage.

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

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

The description opens with a clear operational preference over web search and defines the tool as a router that picks one of 5,596 tools across 1,465 verified sources, fills arguments, and returns structured answers with stable citation URIs. Inclusive trigger phrases and concrete example questions make the tool's target use unmistakable and distinguish it from generic search tools.

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

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

It explicitly defines when to use this tool, even when a web search could also answer, and names sibling tools for real alternative conditions: deep_research for broad multi-part reports, ask_pipeworx_grounded for precise citations, and others like Wingman for consumer-focused purchases. The guidance is actionable and leaves almost no ambiguity about routing decisions.

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

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

The description adds substantial behavioral detail beyond the annotations: candidate routing updates are turned live only during tests, no candidate is active as of a specified date, the tool currently behaves exactly like askama_pipeworx, and it is a fully working router rather than a fallback. It does not contradict the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint annotations, and it gives the agent useful expectations about changing 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 primary differentiator and usage instruction are front-loaded in the first two sentences, and the rest of the description earns its place by clarifying current state, purpose of the beta, and fallback behavior. The parenthetical about retirement evidence is slightly extra but still helps establish that no candidate is currently active.

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

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

Despite having no output schema, the description tells the agent all essential operational aspects: what the tool is, whether it's safe, how it behaves relative to askama_pipeworx, and that the response shape matches the stable router. It could have been more explicit about return values, but the reference to the sibling's response shape gives the agent enough to invoke it confidently.

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 itself documents all six parameters with full coverage, including the question field and several aliases. The description only refers generically to 'same arguments our schema carries the actual semantic weight' and doesn't add new parameter-level detail, so the baseline 3 fits.

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 'Beta version of ask_pipeworx' and clearly defines the tool as a universal router sharing the same 5,596 tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental routing, so an agent can tell it apart even before reading 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?

It gives an explicit selection condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also frames the purpose as experimental comparison against the stable router. However, it doesn't state a clear 'when not to use this' case, so the guidance is good but not exhaustive.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the exact refusal contract, the output shape, the 'uses ONLY what the tool result contains' constraint, and the failure modes such as not_in_source, no_tool_match, data_truncated, and llm_error. This gives the agent realistic expectations of both success and refusal 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 dense but every sentence earns its place: the mode is defined first, routing is summarized, output and refusal formats are given, and usage/cost tradeoffs are stated. It avoids filler and rewards careful reading, which is appropriate for a high-stakes 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?

Given there is no output schema, the description fully spec-ifies the return shape and refusal semantics, including the explicit refusal reasons. It also covers tool selection behavior, data truncation, cost, and common use cases, so an agent has enough context to invoke and interpret this tool correctly without additional documentation.

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 is already fully documented: all six parameters are clearly described as aliases of 'question', with 'question' itself explained as a natural-language string. The description adds no extra parameter-level semantics, which is acceptable because the baseline for 100% schema coverage is a 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?

The description names a specific tool mode ('hallucination-resistant answer mode') and a specific operation (route a question across sources, fetch data, and extract an answer from the returned content only). It explicitly contrasts itself with sibling ask_pipeworx, so an agent can distinguish grounded/ungrounded behavior immediately.

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 concrete when-to-use guidance: use when the answer will be quoted, cited, or acted on and when fact-invention is unacceptable, with examples. It also names the alternative ('prefer ask_pipeworx for casual lookups') and adds the cost tradeoff of one extra LLM call, making the choice 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 provide readOnly/openWorld/idempotent hints, but the description goes far beyond by disclosing fan-out behavior, resolver confidence contract, blocking statuses (low_confidence_match, market_closed_or_inactive), wide-spread tradeability warnings, and resolution-rule risk (cancellation_rule with refund_50_50). This is rich behavioral context that annotations could not convey.

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

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

The description is long but information-dense, with every major section (resolver contract, parent event, news fields, safety) earning its place for a complex tool. It is front-loaded with the core action and use cases, then systematically details edge cases. Slightly overlong 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?

With no output schema, the description carries full responsibility for explaining return shapes and behavior. It thoroughly covers result.market, result.analysis, result.evidence, resolver confidence, parent event extraction, news fallback fields, safety short-circuits, and resolution-rule risk. 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%, and the schema itself thoroughly explains each parameter (market variants, depth enum, include_raw). The description adds contextual examples of market types and fan-outs but does not add syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's job from siblings by listing classifiers and concrete use cases like 'should I bet on X'. This unambiguously defines the tool's purpose.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...') and gives many fan-out examples per bet type. However, it never explicitly says when NOT to use it or names alternative sibling tools (e.g., polymarket_arbitrage), so it lacks explicit exclusions/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 non-destructive, so the safety profile is covered. The description adds that results are paginated mixed media objects with URLs and metadata, which provides useful context about the response shape but does not go beyond that.

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?

One sentence, front-loaded with the primary verb and resource, no extraneous information.

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

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

For a simple one-parameter tool with an output schema, strong annotations, and a clear description stating pagination and return contents, the description is fully sufficient.

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

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

With 0% schema description coverage, the description compensates partially by stating 'by string id', indicating the id is a string. The examples in schema show string collection identifiers, but the description does not explicitly define what the id refers to beyond 'specific Pexels collection'. This is a minor gap.

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 fetches all photos and videos inside a specific Pexels collection by string id, with a specific verb (Fetch) and resource (collection media). It distinguishes from siblings like featured_collections (collections list) and photo/video (single media) by focusing on mixed media in a collection.

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 use case (retrieving all media in a collection) but does not explicitly state when to use this tool vs alternatives like photo_search or video_search, nor does it provide exclusions. Usage is implied rather than directly guided.

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

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

Annotations already declare read-only and idempotent, but the description adds valuable behavioral detail: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. This goes well beyond the annotation hints.

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?

Despite being long, every sentence earns its place: trigger examples, preference guidance, data-source details, sorting behavior, and return type. It's front-loaded with usage examples and structured in a scannable way.

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 explains return value (paired data + citation URIs), covers both entity types, mentions the lookup-count reduction (8–15 sequential lookups), and addresses edge cases (off-calendar fiscal years), making it complete for an agent.

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

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

Schema coverage is 100%, but the description enriches both parameters with concrete examples (e.g., ['AAPL','MSFT'] for company, ['ozempic','mounjaro'] for drug), explains the enum values, and notes fiscal-year handling and data pulled per type, adding significant meaning beyond the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes from siblings by mentioning it replaces sequential lookups and covers entity types company/drug.

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

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

Explicitly lists when to use (comparison queries, ranking, head-to-head) and provides a strong directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. This gives clear context and an alternative to avoid.

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

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

The description goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations, disclosing behavioral details like the parallel tool routing, the findings packet structure, verbatim evidence, confidence and source fields, stable pipeworx:// citations, explicit gaps[] for unanswered facets, contradictions[] scans, semantic excerpting of long records, and the 15-90s latency profile. It also discloses the account and plan requirements, which is important operational context.

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

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

The text is long, but nearly every sentence carries a distinct operational fact: auth requirements, alternatives, domain scope, finding format, citation semantics, gap behavior, contradictions, excerpting, and latency. It is front-loaded with the ACCOUNT REQUIRED warning before alternatives, though the sentence flow is dense and could benefit from a few more separations.

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

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

With no output schema present, the description compensates by specifying the return payload (verbatim evidence + confidence + source + fetched_at + stable citation), the explicit gaps[] and contradictions[] behavior, the hop field, and the citation_uri fetchability guarantee. It also gives timing expectations and covers both signed-in and signed-out scenarios, so an agent has enough information to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description still adds real meaning to both parameters. It details that depth 'quick' is a single hop with 3 facets, 'standard' adds a gap-recovery hop and contradictions[] scan, and 'thorough' adds the iterative lead-chasing hop and requires a paid plan. It also confirms that broad/multi-part natural-language questions are welcome, which strengthens the question 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 names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources' in one call. It distinguishes itself from open-web search and from siblings like ask_pipeworx, and explains the decomposition-and-parallel-routing mechanism, making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and explicit when-not-to-use guidance with alternatives ('If you are not signed in, use ask_pipeworx instead'; 'For a single lookup use ask_pipeworx'; 'For BREAKING ... prefer ask_pipeworx'). It also explains why deep_research is inappropriate for those cases, such as returning mostly empty gaps for non-structured topics.

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

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

Annotations already establish read-only and idempotent behavior. The description adds beyond this by detailing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This informs the agent about the response structure and direct callability, which is valuable behavioral context beyond the annotations.

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

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

The description is three sentences: purpose, usage domains, and return behavior. The long list of domains (SEC filings, FDA drugs, etc.) is front-loaded and serves to guide query formulation, but it makes the description a bit lengthy. Still, every sentence adds value; both purpose and usage are immediately clear. Slight verbosity from the domain list prevents a 5.

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

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

This is a meta-tool with no output schema, so the description must explain what it returns, which it does thoroughly ('Returns the top-N most relevant tools with names, descriptions, and full input schemas'). It also covers when to use it and what it is for, making the description complete for an agent to understand the tool's role and call it correctly. No gaps remain given the tool's simplicity.

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

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

Schema description coverage is 100% — all parameters, including aliases and the 'limit' default/max, are documented in the schema. The description mentions 'top-N' which relates to 'limit' but doesn't add syntax or format details beyond what the schema already provides. The description adds no significant 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's purpose with a specific verb and resource: 'Find tools by describing the data or task.' It further distinguishes itself from siblings by positioning as a discovery/meta tool ('Call this FIRST when you have many tools available'), which is unique among the listed 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 gives explicit when-to-use context: '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.' It doesn't explicitly state when not to use it or name alternatives, but the 'not just one answer' clause implies that for a direct answer you might use a specific tool. Clear usage context with an implicit exclusion.

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 read-only, idempotent, non-destructive. The description adds substantial behavioral context: it fans out across SEC EDGAR, XBRL, USPTO, GDELT→GNews, and GLEIF; patents API soft-fails due to sunset; returns specific fields. This goes beyond the annotations and improves the agent's understanding of side effects and limitations.

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 front-loaded with user queries, then states purpose, usage directives, and return fields. Each clause serves a function; no redundant filler. Though it is long, it packs a large amount of necessary behavioral and usage information into a compact block.

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

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

For a tool with no output schema, the description clearly enumerates exactly what will be returned (CIK, filings with URIs, fundamentals, patents, news, LEI) and notes fallback/sunset behavior. It also covers the only input limitation (ticker/CIK, not names). With two well-documented parameters and strong annotations, the description is complete for safe and effective use.

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 covers both parameters with detailed descriptions, including ticker/CIK examples and the name-not-supported limitation. The description essentially repeats this information, so it adds no additional parameter semantics beyond the schema. Baseline score of 3 is appropriate given 100% schema coverage.

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

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

The description opens with multiple example user queries that map directly to the tool's intent, then explicitly states 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes itself from sibling tools like resolve_entity by noting names are not supported, and from single-pack lookups via the 'ALWAYS PREFER' directive. This is clear, concise, and differentiates the tool.

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

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

Explicitly tells the agent to prefer this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is needed. It also warns that names are not supported and directs the agent to use resolve_entity first if only a name is available. This provides clear when-to-use and alternative guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false, which cover safety. The description adds what the return contains (collection id, title, description, media counts), but does not disclose additional behavioral traits such as pagination, ordering, or potential rate limits. Since the bar is lower with strong annotations, this is adequate but not enriched.

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, front-loaded sentence with a clear verb and essential return-value details. Every word contributes to understanding the tool's purpose and output.

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 zero-parameter listing tool with a rich output schema and strong annotations, the description is largely complete. It explains what the tool returns, which is sufficient, though it could optionally mention that no pagination is needed or that all featured collections are returned at once. Minor gap, but not material.

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?

This tool has zero parameters, so the baseline is 4. The description correctly implies no inputs are needed and clarifies the output focus. There is no parameter-level information to add beyond the empty schema.

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

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

The description uses a specific verb ('List') and specifies the resource ('Pexels' featured curated collections'). It also clearly distinguishes itself from sibling tools like collection_media (which likely retrieves media within a collection) and photo/video search tools by stating it returns collection metadata.

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: use this tool to list featured curated collections. However, it does not explicitly state when to prefer this over collection_media or search tools, nor does it mention any exclusions. Some context is present but guidance is minimal.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context about clearing sensitive data, which goes beyond the structured hints. No contradiction detected.

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

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

Two sentences that are front-loaded with the action ('Delete a previously stored memory by key'), followed by usage guidance. Every word earns its place.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, usage scenarios, and relationship to sibling tools, making it fully self-contained.

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

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

Schema coverage is 100%, so the schema already documents the 'key' parameter completely. The description mentions 'by key' but adds no additional syntax or behavioral detail beyond the schema.

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

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

The description uses a specific verb 'Delete' with a clear resource ('previously stored memory by key'), and it distinguishes itself from sibling tools by mentioning pairing with '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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names related tools ('remember' and 'recall') to clarify its complementary role.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable process detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a text blob ready to deploy. It doesn't cover failure modes or network error handling, but given the annotations, this is solid.

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

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

The description is three sentences: purpose, process, and use cases. It is front-loaded with the primary action, every sentence carries meaningful information, and there is zero redundancy or filler. The 'Useful for' list is clearly structured and adds practical context.

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 of moderate complexity, the description covers purpose, process, output format, and usage scenarios. It lacks mention of edge cases like unreachable URLs, JavaScript-rendered pages, or output size limits, but the annotations and clear schema mitigate this. The output is described as a single text blob, which is sufficient since there is no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a behavioral connection (fetching page, extracting links) but does not elaborate on parameter formats or constraints beyond what the schema already provides. The schema already explains 'url' and 'max_links' with defaults, so the description adds minimal new semantic value.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes this tool from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation. The full sentence specifies the exact deliverable and target consumers.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable context: it returns active subscriptions only (unless include_inactive is set), and it discloses the exact fields returned. This goes beyond the annotations and clarifies the tool's scope and output 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 two sentences: first states the purpose and return fields, second provides usage guidance. Every sentence earns its place with no redundancy or filler. Front-loaded with the core action.

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 lists all return fields (id, type, params, created_at, last_fired_at, fire_count), so the agent knows the response shape. It also covers the optional parameter's behavior. For a simple read-only list tool, this is complete.

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

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

The only parameter (include_inactive) is fully described in the schema with 100% coverage, so the description doesn't need to add much. The description implicitly references the parameter by saying 'active subscriptions,' and the schema's description is sufficient. 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 verb and resource: 'List the caller's active subscriptions.' It also lists the return fields (id, type, params, etc.), which distinguishes it from sibling tools like subscribe/unsubscribe. This is specific and unambiguous.

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

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

The description gives concrete usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies the tool is a read-only precursor to subscribe/unsubscribe, though it doesn't explicitly name alternatives or exclusions. Clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying what 'full metadata' includes (all sized image URLs, photographer name/URL, dimensions, alt text), which is beyond the annotations. No contradictions detected.

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

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

The description is a single sentence that front-loads the verb and resource, immediately stating what the tool does. It lists the metadata components efficiently without fluff, earning every word.

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 one simple parameter and an output schema present, the description is fully sufficient. It explains both the input (numeric id) and the output contents, while the output schema handles detailed return structure. No gaps in context remain.

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

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

Schema coverage is 0%, so the description must compensate for parameter meaning. It says 'by numeric id', which reinforces the schema's number type, but adds no extra semantics like where the id comes from, valid ranges, or format. With only one parameter, the tool description's mention of numeric id is minimal but not entirely absent, so a 3 is appropriate.

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

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

The description uses the specific verb 'Fetch' with the resource 'full metadata for a single Pexels photo by numeric id', clearly distinguishing it from sibling tools like photo_search and photo_curated. It enumerates the metadata contents (all sized image URLs, photographer, dimensions, alt text), making the tool's purpose unambiguous.

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

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

The description clearly implies usage when you have a numeric photo ID and need full metadata, but it does not explicitly mention alternatives like photo_search or photo_curated for discovering photos. There are no exclusions or when-not-to-use scenarios, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by noting that results are paginated and include image URLs in multiple sizes and photographer info, which goes beyond the structured 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, front-loaded sentence that starts with the primary action and then lists the key return details. Every phrase earns its place; there is no fluff or repetition of schema/annotation content.

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 zero parameters, a rich annotation set, and an output schema, the description is sufficient. It explains the core purpose and return shape, and there are no missing prerequisites or edge cases that need to be disclosed for this simple fetch operation.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the empty schema is fully consistent. The description's mention of pagination and image sizes is the only relevant semantics, but there is nothing missing.

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 ('Fetch') and a clear resource ('Pexels' curated editorial photo feed'), and it details the return payload (paginated photo objects with multiple image sizes and photographer info). It distinguishes itself from sibling tools like photo_search by emphasizing the 'curated editorial' feed rather than general search.

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 use for curated editorial content, but it does not explicitly state when to use this tool versus photo_search or photo. There are no explicit exclusions or alternative tool references, so the usage guidance is only implied by the 'curated editorial' wording.

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 context by stating that results are paginated and include image URLs in multiple sizes, photographer name, and attribution link. Since annotations already declare readOnlyHint=true and destructiveHint=false, the description complements rather than contradicts them, earning a 4.

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, focused sentence that front-loads the purpose and then lists return values. It contains no fluff and is easy to parse, warranting a 5.

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

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

Despite having only one parameter and an output schema noted, the description covers the tool's purpose, return values, and required input. Combined with annotations, this is sufficient for an agent to select and invoke the tool correctly, giving a 5.

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

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

The input schema provides no description for the query parameter (0% coverage), so the description compensates by clarifying that 'query' is a keyword. It also notes that the keyword is required, adding meaning to the parameter. This is at a baseline level, thus a 4.

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

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

The description clearly states the tool searches Pexels photos by keyword and specifies the return content, making the core purpose unambiguous. It uses a specific verb 'Search' and resource 'Pexels photos.' However, it does not explicitly differentiate from sibling tools like photo_curated, so it earns a 4 rather than 5.

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

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

The description implies the use case (keyword-based photo search) but does not explicitly mention when to use this tool versus alternatives such as photo_curated or video_search. There are no exclusions or alternative recommendations, so the guidance is minimal, giving a 3.

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 rate limiting (5 per identifier per day), free/no quota impact, the claim_token flow for tracking and follow-up, and daily digest/signal relevance. This far exceeds the sparse annotations (all false hints) and provides valuable operational 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?

Front-loaded with the primary purpose in the first sentence, then logically organizes usage boundaries, message guidelines, and token mechanics. Every sentence earns its place; the length is appropriate for the tool's nuanced scope and exclusions.

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?

Provides a complete picture for a feedback tool with no output schema: covers triggers, exclusions, message expectations, token workflow, rate limits, cost, and team review process. Nothing critical is left unaddressed.

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 already documents all parameters (100% coverage), but the description adds meaningful guidance beyond schema: instructing users not to paste end-user prompts, to be specific about tool/pack/error, and how to use claim_token for follow-up reads. This extra semantic layer justifies a 4 over the 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?

Clearly states the tool sends feedback to the Pipeworx team about broken, missing, or desired functionality, using a specific verb ('Tell') and resource. It distinguishes itself from sibling data/research tools by focusing on feedback submission rather than information retrieval.

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

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

Explicitly specifies when to use (bug, feature, data_gap, praise) and when not to use (feedback about third-party MCP servers), along with a heuristic for identifying Pipeworx tools. This level of exclusion guidance is rare and highly actionable.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that the data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This adds valuable transparency about data provenance, privacy, and freshness. There is no contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then lists specific return values, use cases, and technical context. Each sentence adds value and there is no filler. The structure with a short intro and bullet-like use cases is 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 read-only tool with one optional parameter and no output schema, the description is remarkably complete. It explains the output format, use cases, caching behavior, privacy considerations, and data source. Nothing important is missing for the agent to decide whether to invoke it.

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

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

The schema already covers the single 'window' parameter with enum values and a description. The tool description repeats the window options but does not add new semantic meaning beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume from other AI agents over a recent window. This is a specific verb+resource, and it distinguishes itself from siblings like discover_tools and featured_collections by focusing on AI agent usage trends.

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 'Useful for' scenarios, indicating when to use the tool (e.g., discovering hot data sources, confirming canonical tools, checking use-case alignment). It does not explicitly mention when not to use it or alternatives, but the use cases give clear context. This is a strong 4, falling short of 5 only because no alternative tools are named.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses substantial internal behavior: partition filter drops placeholder slugs and returns null above 20% placeholder fraction, semantic anchor uses ≥0.30 Jaccard similarity, and fill-check explains that realizable_edge_pp ≤ 0 means the edge is not tradeable. These are non-obvious behaviors an agent needs to interpret results correctly.

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

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

The description is long but highly structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every sentence adds operational detail; no filler or repetition of schema fields.

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

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

This is a complex tool with multiple modes, filters, and safety checks, and no output schema. The description fully compensates by detailing the response structure (opportunities[], partition_check fields, fill_check pricing logic, thin_legs) and the conditions under which signals should be ignored. It is complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is already 100%, but the description adds rich meaning: concrete examples for `event` slugs (e.g., 'fed-decision-may-2026'), acceptance of full URLs, and explanation of `topic` as a seed question. It also clarifies the difference between modes, which the schema alone does not convey.

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

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

The description opens with a clear, specific action: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes this from sibling tools by focusing on arbitrage detection and explicitly naming polymarket_fill_risk for custom sizing. The three invocation modes (no args, event, topic) are clearly differentiated.

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

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

Provides explicit when-to-use guidance: use `event` for a specific market, `topic` for cross-event scanning, and no args for a trending scan. It also names an alternative tool (polymarket_fill_risk) for custom sizing and explains that cross-event mode catches patterns single-event misses, directly helping an agent choose between modes.

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

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

The description goes far beyond the annotations by disclosing caching behavior (1h KV keyed on knobs), the exact response structure (by_segment, fed_candidates, _diagnostics), the logic behind each model family (e.g., lognormal barrier, GDELT ratio, partition overround bias correction with per-sport α), and edge caps (Kelly capped at 0.25). It also explains why segments may be empty via diagnostic funnel counters. 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 and dense, but it is well-structured with clear sections (model families, opportunity fields, knobs, response top-level) and each sentence carries substantive detail. Some specifics—like per-sport α values and 'Run 8' gate history—are arguably extraneous, but the organization keeps it navigable and front-loaded with 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 is remarkably complete: it explains the top-level response structure, why segments might be empty (top-N stale, all candidates failed gates, knob dropped them), the edge fields (edge_pp_net after slippage, kelly caps, liquidity/spread/volume), and the 1h caching behavior. With no output schema, the description carries the full responsibility and exceeds what is typically provided.

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

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

All 9 parameters have 100% schema description coverage, so the baseline is 3. The tool description adds meaningful context by grouping tradeable-edge knobs and explaining subtleties like min_partition_leg_kelly applying to per-leg Kelly instead of the parent level, which the schema doesn't clarify. This extra semantic layer justifies a score 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 clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case: 'what should I bet on today'. It distinguishes itself from sibling tools by focusing on edge discovery across multiple model families rather than just arbitrage or tracking.

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

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

The description provides strong usage context, explaining when to use the tool ('agents discover opportunities without paging hundreds of markets') and how to adjust knobs for tradeable edges, including explicit 'set to X' recommendations. It also implies when not to rely on it, such as the Fed signal being unreliable and the 24h-move warning. However, it does not explicitly name sibling alternatives as a comparison.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is already known. The description adds substantial behavioral context beyond annotations: snapshots are written on cache-miss, gaps mean no scan happened, history is bounded by a 60-day TTL, decay is computed from daily closes not intraday, and edge_pp_net is signed by trade direction. This goes far beyond the structured hints.

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

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

The description is long but well-structured with clear labels (Args, RESPONSE, LIMITS) and each section earns its place. It front-loads the core purpose in the first sentence and then provides dense, relevant details about response shape and limitations. No filler or repetition.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly documents tracked[] with fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. It also addresses edge cases like gaps and TTL limits. For a tool with this complexity, the description is complete.

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

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

Schema coverage is 100% and the schema already documents both parameters with defaults and allowed values. The description restates days as 'lookback, default 14, max 30' and window as 'snapshot family, default 1wk' without adding new meaning beyond the schema. It does add some context in the response section (e.g., how window selects the snapshot family), but the parameter descriptions themselves are mostly redundant.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers what the tool does (tracks edge persistence/decay over time) and differentiates it from the sibling polymarket_edges tool, which likely provides current snapshots rather than historical trend analysis. The examples ('a fresh wide edge vs. a 3-week-old wide edge') further sharpen the purpose.

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

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

The description gives clear context for when to use this tool: when the question is 'how long has this edge existed and is it shrinking?' It also implies alternatives by noting it is built from polymarket_edges snapshots, subtly distinguishing it from the current-edge view. However, it does not explicitly say 'use polymarket_edges for current edges instead' or list other exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial context beyond that: it explains that the tool 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict,' and warns that 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode in real arb-bot P&L).' This is a rich behavioral disclosure that goes far beyond the safety hints.

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?

At roughly 250 words, it is long, but it is structured with clear labels (SINGLE-MARKET, BASKET) and every sentence carries operational value. Front-loading the purpose and then methodically detailing modes, returns, and usage makes the length justified, though slightly dense for quick skimming.

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 compensates by enumerating all return fields for both modes, including thin_legs[], max_clean_notional_usd, forced_directional_risk, and verdicts. It also covers parameter semantics, size clamps, and failure modes, making it fully self-sufficient for an agent to invoke the tool correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning beyond the schema by clarifying size_usd's dual interpretation ('max spend on buys, target proceeds on sells' vs 'settlement notional S (shares per leg)') and by giving strategic intent for side in basket mode ('sell_yes = capture overround... buy_yes = capture underround'), which the schema does not include.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a precise verb+resource+scope statement. It explicitly ties itself to sibling tools by naming 'polymarket_arbitrage SELL/BUY-EVERY-LEG signal' and 'polymarket_edges trade,' making the tool's unique role clear.

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

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

Provides explicit directives: 'REQUIRES one of market or event' and 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This clearly specifies when to use the tool versus alternatives, including a practical threshold and use case.

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 description does not need to restate safety. It adds extensive behavioral context: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and the matcher's behavior when pairings are non-equivalent. It also honestly discloses that most pre-mapped topics yield warnings, setting accurate expectations.

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

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

The description is lengthy but every sentence earns its place. It is structured with clear sections ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') and front-loads the core purpose. The density is high without redundancy, and the final warning is valuable context rather than filler.

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

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

For a complex tool with no output schema, the description covers all essential aspects: response structure, safety fields, compatibility caveats, temporal alignment, and practical limitations. It leaves no major gaps about behavior or expected output, making it complete for an agent to invoke correctly.

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

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

While schema coverage is 100%, the description elevates parameter meaning by explaining the two modes and how parameters interact: topic auto-fetches both venues, while kalshi_event_ticker and polymarket_event_slug override the respective side. It also clarifies the expected formats (e.g., ticker examples) and the consequences of each mode. This goes well beyond the schema's baseline.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools by focusing exclusively on cross-venue spread, and further clarifies via two modes (topic vs explicit ticker/slug). The explanation of pre-mapped shortcuts and custom pairings leaves no ambiguity about what the tool does.

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

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

The description provides clear context for when to use the tool (when comparing Kalshi and Polymarket prices for the same question) and explains both modes of operation. It also gives implicit guidance by warning that 'most pre-mapped topics return compatibility_warning' and that 'pre-mapped ≠ tradeable.' However, it does not explicitly name sibling alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavior: omitting the key lists all saved keys, and results are scoped to the caller's identifier. This goes beyond annotations and enriches understanding of return behavior.

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

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

Three sentences, each with a distinct purpose: first describes the action, second gives concrete use cases, third covers scope and related tools. No filler, front-loaded with the operational verb. Ideal length for the tool's simplicity.

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-optional-parameter tool with strong annotations, the description covers all essential aspects: function, behavior with/without key, scoping, and relationship to sibling tools. No output schema is needed for this simple retrieval, so the description is complete.

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

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

Schema already documents the 'key' parameter with 100% coverage, so baseline is 3. The description adds the crucial nuance that omitting the key lists all keys, which clarifies the optional behavior beyond the schema's static description. This extra semantic guidance justifies a 4.

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

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

The description clearly states the dual function: 'Retrieve a value previously saved via remember, or list all saved keys'. It identifies the resource (saved memory) and the specific verb (retrieve/list), and differentiates from sibling tools like remember and forget.

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

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

Explicitly says when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and complements: 'Pair with remember to save, forget to delete.' This provides clear context and exclusions relative 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 and idempotentHint=true, so the bar is lower. The description adds value by disclosing the mark_read side effect (state change when explicitly requested), the return payload structure (source, citation_uri, raw payload), and the alternative retrieval URL. This complements the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence adds useful information (return fields, filtering, side effect, polling, alternative access). It is compact without being sparse, achieving high information density with minimal waste.

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

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

Given no output schema, the description explains what the return carries (source, citation_uri, raw payload). It covers filtering, pagination-ish behavior via limit (via schema), mark_read, polling suitability, and an external feed URL. This is fully sufficient for a read-oriented tool with strong 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 coverage is 100% with each parameter having a description, so baseline is 3. The description enriches this by providing a concrete type example ('sec_8k'), clarifying that 'since' is an ISO timestamp, and explaining the behavioral impact of mark_read (next call only shows newer ones). This goes beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly identifies what the tool does and differentiates it from subscription management siblings (list_subscriptions, subscribe, unsubscribe) by focusing on reading alerts. The mention of the persisted feed and evaluator-written alerts adds specificity.

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

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

The description provides concrete usage guidance: filtering by type and since, setting mark_read to affect future calls, and polling suitability. It also mentions an alternative URL for scripts/dashboards, implying when the tool might be preferred over direct HTTP access. It lacks explicit exclusion of alternatives but still gives clear 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 declare readOnly/idempotent/destructive hints. The description adds valuable behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback (rate-limited or 5xx), USPTO PatentsView sunset causing soft-fail until reactivated, and the return format with pipeworx:// citation URIs. No contradiction.

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

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

The description is dense but front-loaded with example queries, then packs details on data sources, fallback, and return shape. Every sentence carries information, though the single-paragraph format could be more scannable with bullet points. 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?

Despite having no output schema, the description fully covers return value ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also explains edge cases (GDELT vs GNews fallback, USPTO soft-fail) and the 'ONE parallel call' architecture, making the tool well-understood without external references.

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 3. The description adds extra practical guidance: 'since' accepts ISO date or relative shorthand, recommends 'Use "30d" or "1m" for typical monitoring', and clarifies 'value' examples (ticker or zero-padded CIK). This exceeds the schema descriptions.

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

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

The description uses a specific verb and resource: 'change feed for a company in the last N days/weeks/months' and opens with concrete example queries. It distinguishes itself from sibling tool `entity_profile` by contrasting dynamic change feed vs static 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?

Explicit guidance is provided: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' The description also explains when the tool is appropriate ('What's new with X') and includes fallback behavior that implies usage conditions.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds key behavioral details: persistence scoped by identifier, authenticated vs anonymous retention periods (24 hours), and key-value storage semantics. 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 concise (three sentences), front-loaded with the main purpose, and each sentence adds new information: what, when, and persistence details. 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?

For a simple two-parameter write tool with rich annotations and no output schema, the description covers use cases, persistence, scoping, and sibling relationships. Nothing essential 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% with both parameters well-described. The description reinforces but does not substantially extend parameter meaning beyond giving example keys and noting value is any text. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It specifies the resource (key-value memory) and distinguishes itself from siblings by explicitly mentioning pairing with recall and forget.

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

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

The description provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and contrasts with 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?

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds rich detail: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI is unavailable, explicitly lists unresolved identifiers, and returns ownership hierarchy. This goes far 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 lengthy but every clause adds value, covering examples, supported types, fallback behavior, and return structure. It is front-loaded with query examples. However, the single dense paragraph could be improved with structured bullet points for the two entity types, slightly reducing readability.

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 explains return values: identifiers labeled with source, unresolved list, RxCUI with citation, LEI parent/children hierarchy, and input edge cases like ISIN for non-US issuers. It is complete for a resolver tool with this complexity and annotation support.

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

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

Schema descriptions cover both parameters at 100%, but the description adds significant semantics: examples like AAPL, CH0038863350, and 'ozempic', the ISIN-to-LEI mapping, and clarification that value accepts different formats depending on type. This meaningfully enhances 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 resolves user-spoken names to canonical/official identifiers, lists supported entity types (company, drug), and provides concrete example queries. It distinguishes itself from siblings by explicitly positioning itself as the first tool to use when a name needs an ID, which separates it from entity_profile 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?

It explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' provides multiple query patterns ('What's the ticker for…', etc.), and notes that it replaces 2-3 manual lookups. It also clarifies what each type returns, giving clear context for when to choose this tool over 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond these: it reveals the internal mechanism (probes each entity with ai_visibility_check), explains the ranking behavior, and specifies the return shape (ranked list with score, confidence, signal density). This enriches the agent's understanding without contradicting annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, then elaborates on mechanics, use case, and output. Every sentence earns its place with useful information, and there is no redundancy or filler. It is well-organized for 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?

Given the tool's medium complexity (multi-entity comparison, optional models, API key), the description covers the return format, the probing mechanism, and a typical use case. No output schema exists, but the description specifies the returned fields. It could mention edge cases or failure modes, but with full parameter schema coverage and annotation hints, the provided information is sufficient for an agent to invoke the tool correctly in most scenarios.

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

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly. The description adds minimal new meaning beyond the schema (e.g., it does not explain parameter values or constraints further). The only slight addition is the phrase 'your brand + N competitors' which echoes the schema's 'First entry treated as the subject' but does not go beyond it. Baseline 3 is appropriate.

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

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

The description states that it compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. This clearly distinguishes it from the sibling tool ai_visibility_check, which focuses on a single entity. The verb 'compare' plus the resource 'AI presence' makes the purpose specific and non-tautological.

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 mentions 'competitive AI-marketing audits' and gives a concrete example ('does Claude know about us as well as our competitors?'), which clarifies when to use it. It also implicitly contrasts with ai_visibility_check by noting each entity is probed with that tool, but it does not explicitly name an alternative or state exclusion criteria, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral details beyond annotations: partial failures degrade gracefully, first bundlephobia measurement can take 5-30s, and sources_failed will list timeouts. 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 exceptionally dense; every sentence earns its place: purpose, trigger phrasing, output summary fields, ecosystem scope, and failure behavior are all covered. It is well-structured and front-loaded with 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?

For a composite tool with no output schema, the description compensates by enumerating return fields, listing failure modes, and noting latency. Combined with strong annotations and full schema coverage, the agent has enough context to invoke and interpret the tool correctly.

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

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

Schema covers both parameters fully (package name and version with defaults and scoped-package acceptance). The description adds example usage ('lodash') but no new semantic 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 a composite purpose: to check if an npm package is worth adding by aggregating deps.dev and bundlephobia data. It distinguishes from siblings by naming data sources and specifying NPM-only scope, making the tool's function 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also excludes non-NPM ecosystems by directing them to deps.dev:version directly, offering clear when-to-use and when-not-to-use 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?

Beyond the annotations (read-only, idempotent), the description discloses key behaviors: it returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K char cap, and flags truncated inputs. This is rich behavioral context that the annotations do not 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 four sentences but each one earns its place: purpose, use case, pairing/benefit, and technical implementation. It is front-loaded with the core function and avoids 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?

The description fully covers the tool's purpose, usage scenario, return format (offsets, similarity scores), limitations (200K cap, truncation), and relationship to a sibling tool. It is complete for a tool with no output schema.

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

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

The input schema already provides 100% coverage with clear field descriptions and examples. The description adds context about usage (e.g., 'top-N passages') but mostly reinforces what the schema states. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Semantic search INSIDE a fetched record') and provides concrete examples (SEC 10-K body, article). It also distinguishes itself from siblings by emphasizing 'inside a fetched record' and explicitly pairing with ask_pipeworx_grounded.

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

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

The description gives explicit guidance: 'Use when the record is too big to cram into the prompt' and explains the value proposition (saves context, returns only relevant passages). It also names a complementary tool (ask_pipeworx_grounded) and tells the agent exactly how to combine them.

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 enriches the annotation profile by disclosing that the write operation requires an OAuth account and that anonymous/BYO cannot persist subscriptions. It also reveals SMS rate limits (10/day), phone verification requirements, and the one-time webhook signing secret, adding significant operational detail beyond the annotations.

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

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

The description is dense but well-structured: it opens with the main action and return, then covers prerequisites, supported types, and delivery channels in a logical order. Each sentence adds value, though the length is considerable; still appropriately sized for a complex 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?

The description covers the core action, return value, auth requirements, example types, and delivery options. It omits two schema enum types (patent_grant, clinical_trial) from the narrative, but those are documented in the schema. Given no output schema, the return of a new subscription id is sufficient.

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

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

While the schema covers 100% of parameters with descriptions, the tool description adds concrete examples (e.g., items:['5.02'] for sec_8k, topic:'fed' for polymarket_edge, series_id:'UNRATE' for fred_series) and clarifies delivery behavior (feed always on, webhook auto-disable). This goes beyond the schema's 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 clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value ('Returns the new subscription id'). It identifies the resource (subscription) and distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context: requires a Pipeworx OAuth account, supported subscription types, and delivery channels. It also explains how to consume the feed ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). However, it does not explicitly compare with alternatives or state when not to use this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context that it draws from a live catalog of thousands of tools and returns categorized examples, which goes beyond the annotations. No contradiction found.

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

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

The description is well-structured: it opens with a list of user intents, then explains the return format, argument behavior, and usage context. Every sentence earns its place and information is front-loaded.

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

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

With no output schema, the description fully explains the return value: category-bucketed example questions with tool + argument shapes. It also addresses the optional topic parameter and the tool's role as an onboarding guide, making it complete for this simple tool.

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

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

The schema covers the single 'topic' parameter at 100%, but the description enriches it by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting it gives the full spread. This 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 clearly identifies the tool as the onboarding entry point for an agent that just connected, stating it returns category-bucketed example questions with exact tool and argument shapes. This distinguishes it from sibling tools like discover_tools by emphasizing user-facing question suggestions rather than tool discovery.

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 FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools as an alternative. While it doesn't explicitly state when not to use it, the 'FIRST' positioning implies a 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?

The description discloses important behaviors beyond annotations: ownership enforcement ('you can only cancel your own subscriptions'), soft-delete semantics ('deactivated, not deleted'), and the continued availability of historical events via 'recent_alerts'. These details add context not present in the annotations (readOnlyHint, destructiveHint, idempotentHint).

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 action, and every sentence adds value: the first states the operation and parameter, the second explains ownership and side effects. No filler or repetition.

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

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

For a tool with one parameter, no output schema, and rich annotations, the description fully covers the operational semantics: cancellation, ownership constraints, and non-destructive behavior. The mention of 'recent_alerts' ties it to the system context, exceeding minimum requirements.

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

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

Schema coverage is 100%—the single parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.' The description adds 'by id' but no new semantic detail; the schema already fully explains the parameter. Baseline 3 is appropriate for high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), distinguishing it from siblings like 'subscribe' (creation) and 'list_subscriptions' (listing). The scope is specific: cancellation by id with ownership enforcement.

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 this tool—when you want to cancel a subscription you own—and provides context about ownership restrictions. It does not explicitly name alternatives or say 'when not to use', but the context is clear enough. A named alternative would elevate it to 5.

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

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

Beyond the readOnly/idempotent annotations, the description warns that could_not_verify means the check did not happen and must not be treated as evidence, and explains unsupported as no source coverage. It also discloses the routing logic and the output verdicts, adding valuable nuance 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?

The description is dense but well-organized, front-loading example query patterns and purpose before diving into paths and caveats. Every sentence contributes either usage guidance, behavioral nuance, or output description, though it is slightly long.

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

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

The description covers the input, the two processing paths, the verdict set, the special semantics of could_not_verify and unsupported, and the return format (verdict, value with citation, reasoning). Since there is no output schema, this disclosure is necessary and 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?

Both claim and tolerance_pct are fully documented in the schema, including examples and the tolerance's effect and default (coverage 100%). The description adds no additional parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with concrete query patterns ('Is it true that…' / 'fact check' / 'verify the claim') and clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes validate_claim from sibling research tools by specifying it replaces multiple sequential calls and focuses specifically on fact-checking claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use context. It also differentiates two paths (SEC EDGAR/XBRL for financials, grounded pipeline for anything else), though it does not name 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, non-destructive, idempotent behavior. The description adds value by specifying the return content in detail (file URLs at all resolutions, duration, dimensions, attribution), which goes beyond the annotations and clarifies what the agent should expect from the response.

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

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

The description is a single well-structured sentence, front-loaded with the action and resource. Every phrase earns its place, listing both the input context and key output fields without redundancy.

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

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

With an output schema present and comprehensive annotations, the description provides all necessary context: the input, the output highlights, and the resource scope. It fully equips the agent to select and invoke the tool correctly for single-video metadata retrieval.

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 only defines 'id' as a number. The description enriches this by clarifying that the id is a Pexels video ID and that the tool returns a single video. This compensates for the low schema coverage by tying the parameter to the resource being fetched.

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 ('Fetch') and resource ('full metadata for a single Pexels video'), clearly distinguishing this from sibling tools like video_search and video_popular. It lists the exact data returned (file URLs, duration, width, height, attribution), leaving no ambiguity about the tool's function.

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 phrase 'by numeric id' makes clear this tool is for retrieving a single known video, contrasting with search/popular siblings. However, it does not explicitly state when not to use it or name alternative tools, so it falls 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 declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: it returns paginated results, with file URLs at multiple resolutions, duration, and videographer info. This enriches the agent's understanding of the operation without contradicting the annotations.

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

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

The description is a single sentence that front-loads the action ('Fetch Pexels' popular video feed') and packs useful details (paginated, file URLs, resolutions, duration, videographer info) without wasted words. It is appropriately concise for the tool's simplicity.

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 parameterless, read-only tool with an output schema and comprehensive annotations, the description is complete. It states what the tool does and what the response contains (paginated video objects with key properties). No additional context seems necessary for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so the baseline of 4 applies. There is no parameter meaning to explain, and the description does not need to compensate for schema coverage. The description shifts focus to the output format, which is fine.

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 fetches Pexels' popular video feed with a specific verb and resource, and the 'popular feed' scope differentiates it from search and specific video tools in the sibling list. However, it does not explicitly name alternatives or contrast with them, so it falls short of a 5.

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

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

The use case is implied: call this tool to get popular videos. But there are no explicit when-to-use/when-not-to-use instructions or references to alternative tools (e.g., video_search). The usage context relies on the name and description rather than explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds useful behavioral context beyond annotations: results are paginated, and the response includes file URLs at multiple resolutions, duration, and videographer info. This gives the agent a clear picture of what to expect.

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 one sentence with high information density, front-loading the action and resource. It covers what the tool does, the required parameter, and key output characteristics without unnecessary 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?

The tool is simple (one parameter, no nested objects) and has an output schema, so the description need not detail return structure. It covers pagination, response content, and the search mechanism. No major gaps are apparent, though it doesn't mention rate limits or sorting options, which are not essential for a basic search tool.

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

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

The description explains that the single required parameter 'query' is a keyword, adding meaning beyond the schema which only shows a string type. With 0% schema description coverage, this is valuable. The examples in the schema further confirm the expected format, making this sufficient for a simple search parameter.

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

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

The description clearly states the tool's function: 'Search Pexels videos by keyword' – a specific verb+resource pair. It distinguishes itself from sibling tools like video and video_popular by emphasizing keyword-based search, making it clear this is the search variant.

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 keyword-based video search but does not explicitly state when to use this tool versus siblings like video_popular or video. It mentions 'keyword (required)', which gives some context, but lacks explicit alternatives or exclusions.

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