Flickr Public

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context beyond that: the default model is free, using Anthropic requires a BYO API key with direct payment to Anthropic, and the API key is passed straight through to api.anthropic.com. This informs cost and data handling behavior meaningfully, though it could mention rate limits or latency.

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, front-loaded with the main purpose, then adds model details, return structure, and use cases. Every sentence carries useful information without redundancy, and it is appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description fully specifies the return payload shape: per-model {score, confidence, signals, raw_response} plus a combined view. It also covers default behavior, optional API key usage, and applied use cases, leaving no major gaps for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the relationship between `models` and `_apiKey` (passing _apiKey 'also probe[s] Anthropic') and clarifying the default model for the `models` parameter. This enhances the schema's already-complete documentation.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business/brand/product/topic'), clearly distinguishing the tool's purpose of scoring AI visibility from sibling tools like ask_pipeworx or deep_research. It also states the output format and scoring range, making the core function 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 clear context for when to use it ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model choice versus the optional Anthropic path. However, it does not explicitly name alternative tools or exclusionary conditions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context beyond that: it routes questions, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier. No contradictions with annotations.

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

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

The description is lengthy but densely informative, front-loaded with the 'PREFER OVER WEB SEARCH' directive. Every sentence adds value: scope, trigger phrases, examples, distinctions from siblings, and tier/performance notes. The structure guides the reader from primary use to alternatives.

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 broad scope and no output schema, the description covers return format (structured answer with citations), domain coverage, usage cues, and alternatives. It even explains how it handles breaking news. This is complete for a default entry-point tool.

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

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

Schema coverage is 100% with 'question' and all aliases documented. The description adds example questions and explains the natural language input, but does not provide additional parameter semantics beyond what the schema already offers. 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 answers factual questions by routing to 5,366 tools across 1,396 verified sources, returning structured answers with citation URIs. It explicitly lists supported domains (SEC filings, FDA, FRED/BLS, etc.) and differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives trigger phrases ('what is', 'look up', 'find', etc.). Also explains when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions).

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 hints. The description adds valuable context: it is a live experimental edge, may have candidate routing improvements enabled, currently matches ask_pipeworx exactly, and falls back to nothing—it is a full working router. This goes beyond annotations to explain the experimental state and current behavior.

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

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

The description is information-dense and front-loaded with the core purpose. It includes a few redundant phrases ('identical universal router' and 'use it exactly like ask_pipeworx'), but each sentence contributes context about the beta state, current activity, and relationship to the stable tool. Slightly verbose but well-organized.

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

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

Given the tool's complexity as a router over thousands of tools, the description covers purpose, usage guidance, current behavior, relationship to stable version, and experimental nature. No output schema exists, but the description specifies the response shape is identical to ask_pipeworx, making it complete for an agent to select and invoke correctly.

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

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

The input schema covers 100% of parameters with descriptions for all six aliases and the question field. The description adds no parameter-specific meaning beyond stating 'same arguments' as ask_pipeworx, which is redundant. Baseline 3 is appropriate since schema carries the full burden.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly differentiates from the stable sibling ask_pipeworx by describing its experimental routing improvements, making the purpose unmistakable.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. This provides clear when-to-use guidance and implicitly names the stable alternative, satisfying the criteria for explicit usage guidelines.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context: it returns a structured success object with evidence as a verbatim quote, or an explicit refusal with specific refusal reasons, and it only uses the tool result content. This goes well beyond what annotations provide.

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

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

The description is longer than typical but every sentence carries distinct information: purpose, mechanism, success return, refusal return, usage context, and cost trade-off. It is front-loaded with the core purpose. The only slight issue is the mechanism sentence is a bit verbose, but it is not redundant.

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

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

With no output schema, the description fully specifies both success and refusal return formats, including the refusal reason enum. It also covers usage context, alternatives, and cost, making it self-contained for a high-stakes answer 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 already covers all six parameters with descriptions, including the alias relationship. The description does not add parameter-level semantics beyond what the schema provides. Given 100% schema coverage, the 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 identifies the tool as a hallucination-resistant answer mode for high-stakes reads, and it explicitly distinguishes itself from ask_pipeworx by stating it uses the same routing but extracts answers only from tool results. This is a specific verb+resource definition that goes beyond a generic statement.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also notes the additional LLM call cost, providing a clear trade-off for decision-making.

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 (readOnly, openWorld, idempotent, non-destructive) by explaining resolver confidence levels, low-confidence short-circuits, closed-market statuses, wide-spread illiquidity warnings, parent-event extraction, news fallback behavior, and cancellation-rule risk. This is rich behavioral context that helps the agent understand exactly what happens inside the tool.

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

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

The description is long but extremely well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK). Every block carries operational value, though some redundancy around blocking paths and the extensive fan-out examples keep it from being maximally concise.

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

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

There is no output schema, so the description compensates thoroughly by inventorying the return shapes: result.market fields, result.analysis, result.evidence, parent_event, status codes, news fallback fields, and cancellation-rule risk. For a multi-source research tool, this level of completeness is exceptional.

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 all three parameters. The description adds meaningful context for the `market` parameter by explaining accepted input forms (slug, URL, or question text) and the resulting resolution/fan-out pipeline. It also explains output shapes tied to `depth` and `include_raw`, adding value beyond the schema.

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

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

The opening sentence names the exact function ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and the use-case line ('should I bet on X', 'what does the data say about Y') makes the scope unmistakable. The classifier list and fan-out description distinguish it clearly from sibling tools like polymarket_edges or arbitrage 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?

Explicitly states when to use the tool with three concrete query templates: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not name alternative tools or explicitly say when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the 'Public uploads' scope, which is useful context regarding accessibility, but it does not disclose behavior like pagination, ordering, or limit defaults, leaving some behavioral gaps.

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 phrase 'Public uploads in one group.' with no wasted words. It is appropriately sized for a simple tool and communicates the core purpose efficiently.

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 adequate for a simple read-only tool given the presence of an output schema and safety annotations, but it lacks usage context (e.g., when to prefer this over 'by_user') and details like pagination or limit behavior. This leaves noticeable gaps in completeness.

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

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

The schema provides a description for group_id ('Flickr group id.') and none for limit. The description does not explain the limit parameter or its default behavior, and with schema coverage at only 50%, the description should compensate but does not, leaving parameter meaning incomplete.

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 'Public uploads in one group' clearly identifies the resource (group uploads) and scope (public, one group), distinguishing it from the sibling 'by_user'. However, it lacks an explicit verb like 'list' or 'get', so it's not fully explicit.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as 'by_user'. There is no mention of exclusions, prerequisites, or specific use cases beyond the implied 'when you need public uploads for a group'.

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 hints. The description adds the behavioral constraint that only 'Public' uploads are returned, which is useful. However, it does not disclose details like pagination, sorting, or how the limit parameter affects results beyond what the output schema may already capture.

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 no wasted words. It conveys the core purpose efficiently, though it is arguably too terse and could benefit from an explicit verb. Still, it is concise and well-structured.

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

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

Given the presence of an output schema and comprehensive safety annotations, the description only needs to state the tool's scope, which it does. However, it omits any mention of parameter behavior, alternatives, or edge cases, making it minimally adequate but not complete for a tool with two parameters.

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 schema description coverage at 50%, only user_id is described in the schema and the description adds no parameter context. The limit parameter is undocumented in both the schema and the description, so the agent receives no explanation of its meaning or format. The description does not compensate for the missing limit 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 'Public uploads from one user' clearly identifies the resource (public uploads) and the scope (one user), distinguishing it from similar tools like by_group. However, it lacks an explicit verb (e.g., 'list', 'retrieve'), so it doesn't fully meet the 5-point criterion for a specific verb+resource.

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 no guidance on when to use this tool versus alternatives such as by_group, recent, or search_within. It does not mention exclusions, prerequisites, or contexts where another tool would be more appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), off-calendar fiscal year handling, sorting by primary metric, and return format with pipeworx:// citation URIs. 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 longer than minimal, but every section serves a purpose: trigger phrases, scope, preference note, per-type data details, sorting, and output format. It is dense and well-organized, though the uppercase 'ALWAYS PREFER' and semi-list structure slightly reduce elegance.

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

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

With no output schema, the description compensates by explaining what is returned (paired data + citation URIs), how results are sorted, what each type pulls, and the parallel-call efficiency. Combined with the fully described parameters and annotations, the agent has all necessary 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%, so the baseline is 3, but the description significantly enriches both parameters: type='company' means 10-K financial metrics, type='drug' means adverse-event/trial counts, and values range is explicitly tied to 2–5 entries. This goes well beyond the schema's bare definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete trigger phrases like 'X vs Y' and 'rank these companies'. This distinguishes it from sibling tools such as entity_profile and from sequential lookups.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides clear when-to-use context via natural-language examples. It also implicitly differentiates company vs drug use cases by data source, giving the agent strong guidance.

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

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

Description adds extensive behavioral context beyond annotations: account/tier requirements, parallel decomposition, gap reporting ('never invented'), contradictions scan, hop fields, citation URIs, semantic excerpting, and expected latency. No contradiction with the readOnlyHint, openWorldHint, or idempotentHint annotations.

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

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

The description is long and dense, though well-structured with front-loaded account requirements and a logical flow. Every sentence adds value, but the sheer length and parenthetical-heavy style make it harder to parse quickly. A bulleted layout would improve structural clarity.

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 discloses return format (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field), timing expectations, and limitations. It provides a complete picture 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 already provides 100% parameter coverage, but the description significantly enriches the meaning of 'depth' with explicit facet counts, behavior differences (gap recovery, contradiction scan, paid tier), and confirms the 'question' parameter accepts broad multi-part queries. This goes far beyond the schema's enum 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 tool performs grounded multi-source research across Pipeworx's 1396 structured data sources, explicitly distinguishing it from open-web search. It names sibling alternatives (ask_pipeworx) and specifies the exact resource (structured data tools). The verb 'research' is specific and the scope is well-defined.

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

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

Usage is explicitly contextualized: 'Best for broad/multi-part questions over structured data' and alternatives are given for single lookups and breaking news. The description even explains when deep_research would return empty gaps, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context: returns the top-N most relevant tools with full input schemas and curated examples, and each result is 'ready to call directly, no second schema lookup needed'. This explains the return semantics and key user-facing behavior 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 reasonably concise for a meta-tool. It front-loads the core purpose, provides a useful domain list, then covers return behavior and usage guidance. Each sentence earns its place, though the domain list is somewhat 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?

No output schema is present, so the description carries the burden of explaining return values. It does so well, specifying the top-N result format, included fields (names, descriptions, full input schemas), and the 'ready to call' property. It does not cover pagination or error handling, but these are less critical for a discovery tool.

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

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

Schema description coverage is 100%: the query parameter and all aliases (q, task, search, description) are already fully documented with examples in the schema. The description adds no additional parameter meaning beyond noting the 'top-N' behavior, which the limit parameter already covers.

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

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

Description clearly states 'Find tools by describing the data or task' with specific verb+resource. It also enumerates many domains (SEC filings, FDA drugs, etc.), making the tool's scope immediately clear and distinguishing it from all sibling tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This gives clear when-to-use context and implies when not to use (when you already know the exact tool), but does not name specific alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), discloses that the USPTO patents API is sunsetting in May 2025 and will soft-fail until reactivated, and describes a GDELT→GNews fallback. It doesn't cover all edge cases (e.g., rate limits, invalid ticker behavior) but goes beyond annotations.

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

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

The description is long but information-dense, front-loaded with example queries to quickly convey intent. It packs in return fields, source APIs, fallback behavior, and constraints without excessive fluff. While it could be trimmed slightly, every sentence contributes useful context for invocation.

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

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

Given the tool's complexity (multi-source fan-out) and lack of an output schema, the description is remarkably complete: it lists return fields (cik, recent_filings, fundamentals, patents, news, LEI), source APIs, and fallback behavior. It lacks explicit error handling details or pagination info, but for a read-only profile tool, it covers the essential operational context.

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 clearly described, but the description adds concrete examples ('AAPL', '0000320193') and reinforces the constraint that names are not supported. It also clarifies the 'type' parameter by explicitly stating only 'company' is supported today, complementing the schema's enum. This is meaningfully more than the schema alone.

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

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

The description clearly identifies the tool's purpose: generate a comprehensive cross-source profile of a US public company in a single call. It provides specific verbs like 'profile,' 'research,' and 'brief me,' and distinguishes itself from single-pack lookups by emphasizing the holistic view. It also differentiates from sibling tools like resolve_entity by explicitly stating that names are not supported and directing users to resolve_entity first.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion (names not supported) and directs users to an alternative tool (resolve_entity). This is strong usage guidance beyond mere purpose.

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 context about clearing sensitive data but does not reveal additional behavior beyond the delete action, such as error handling, irreversibility, or return values. It is consistent 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 two sentences, front-loaded with the action, and contains no filler. Every word adds value, covering purpose, usage conditions, and related tools.

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

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

For a simple 1-parameter tool with strong annotations (destructive, idempotent), the description provides sufficient context for use. It does not explain the return value, but given the simplicity and lack of output schema, this is a minor gap. The description is practically complete.

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

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

The input schema fully covers the single parameter 'key' with a clear description. The description's 'by key' adds no extra semantic meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using specific verb and resource. It distinguishes itself from sibling tools like remember and recall by explicitly naming them.

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 conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and names related tools to pair with. However, it does not provide explicit when-not-to-use exclusions, which prevents a full 5.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable process details: it fetches the page, extracts title/description/key links, and emits markdown. This goes beyond the annotations without contradicting them. It does not disclose potential failures or rate limits, but that is not essential given the annotation coverage.

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, front-loaded with the core purpose, followed by behavior, output format, and use cases. Every sentence carries meaningful information; there is 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?

The tool is simple with two parameters and no output schema. The description fully covers what it does, how it works, what the output looks like, and when to use it. It is complete for the tool's complexity and annotation richness.

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

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

Schema description coverage is 100%, with both parameters ('url' and 'max_links') already documented with types, examples, and defaults. The description only indirectly references link extraction, adding nothing substantive 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 uses a specific verb ('Generate') and a concrete resource ('llms.txt file'), and clearly states the input ('for any URL') and output ('standard llms.txt markdown format'). It further distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the file itself rather than analyzing AI visibility.

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

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

The description provides clear usage context through 'Useful for:' followed by three concrete scenarios (client indexing, drafting for your own project, auditing a competitor). It does not explicitly name alternative tools or state when NOT to use it, but the use-case list gives strong guidance for tool 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 and idempotentHint, so the safety profile is known. The description adds value by specifying the default behavior (active only), the included return fields, and the effect of the include_inactive parameter, which goes beyond the annotation coverage.

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 function and return fields, followed by a practical usage note. Every sentence contributes value with no redundancy or fluff.

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

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

Given the tool's simplicity, strong annotations, and complete parameter schema, the description covers return format, default filtering, and usage scenarios. It is fully adequate for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% for the single parameter include_inactive, and the parameter already has a clear description. The tool description does not add further meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, which is a specific verb-resource combination. It also distinguishes from siblings like subscribe and unsubscribe by focusing on the listing capability.

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

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

The description provides clear usage context: use it to review what you're monitoring before adding more subscriptions, or to find an id to cancel. It doesn't explicitly name alternatives or exclusions, but the intent is clear.

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

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

Annotations are all false, so the description carries the behavioral burden. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily, affecting roadmap. While it doesn't describe the response format, it adds significant context beyond the empty annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence conveys unique information (usage triggers, content guidance, operational details). No wasted words 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?

Given the tool's simplicity (no output schema, 3 params, one nested object), the description covers all essential aspects: what, when, how, and constraints. It lacks explicit mention of the response/return value, but for a feedback submission tool this is minor. Overall, it is quite 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%, so baseline is 3. The description adds meaningful guidance for the 'message' parameter: describe issues in terms of Pipeworx tools/packs and don't paste end-user prompts. This exceeds schema descriptions and helps the agent produce more useful feedback.

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: to tell the Pipeworx team about something broken, missing, or needed. It explicitly lists the feedback types (bug, feature, data_gap, praise) and distinguishes this tool from siblings, which are research/data tools.

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

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

The description provides explicit when-to-use scenarios: wrong/stale data (bug), missing tool/data (feature/data_gap), and positive experiences (praise). It also gives a 'don't' guideline (don't paste end-user prompt) and notes rate limits and quota behavior, offering 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?

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy, caching, and output shape.

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 uses clear bullet-pointed use cases, and ends with a concise note on behavior. Every sentence adds value and the structure is easy to parse.

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 simple one-parameter schema and existing annotations, the description fully covers what the tool returns (top tools, top packs, total call volume), when to use it, and additional context like caching and no PII. Even without an output schema, an agent can confidently invoke it.

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

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

Schema description coverage is 100% for the single parameter 'window', and the schema already explains the meaning of each window. The tool description merely mentions the window options without adding new semantic details, 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 a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes it from siblings like recent or discover_tools by focusing on aggregate trending signal.

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 three use cases, such as discovering hot data sources and confirming canonical tool choices. It provides clear context for when to use the tool, though it doesn't explicitly name when not to use it or alternative tools, so a 4 is appropriate.

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

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

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds substantial behavioral detail: 3pp threshold for partition signals, ≥0.30 Jaccard similarity for cross-event pairing, >20% placeholder fraction returning null, and the fill-check warning that realizable_edge_pp ≤ 0 means the edge is not real and should not be traded. These go far 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?

Though long, the description is organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) and front-loaded with the core purpose. Every sentence contributes useful details, examples, or warnings, with 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?

Given the tool's complexity and lack of output schema, the description covers return structures (opportunities[], partition_check{}), thresholds, filter behavior, and risk guidance. It even directs users to polymarket_fill_risk for custom sizing, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and baseline would be 3, but the description enriches both parameters with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifies that full URLs are accepted, explains the no-args mode, and outlines response shapes per mode. This adds significant semantic value beyond the schema.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by describing what makes this tool unique.

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 instructs when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scan. It recommends event for specific markets and notes that custom sizing should use polymarket_fill_risk, providing an explicit alternative. It also explains what cross-event mode catches that single-event misses, giving 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?

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral traits: KV-level caching keyed on all knobs, exclusion of Fed bets from ranking, the 24h-move warning, the fact that partition arbs always return kelly_fraction_half=0 at the parent level, and diagnostics for why a segment is empty. This gives the agent a realistic model 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 long, but every section (purpose, model families, knobs, response structure, caching) serves a distinct and necessary function given the tool's complexity. It is front-loaded with the main purpose and uses clear labels for segmentation. The density may be overwhelming, but it avoids redundancy and 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?

With no output schema, the description compensates by thoroughly detailing the top-level response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.). It also explains what to observe when a segment is empty, making the tool fully understandable for a complex data-heavy 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 input schema already provides 100% parameter descriptions, so the baseline is 3. The tool description adds value by grouping knobs into 'TRADEABLE-EDGE KNOBS', explaining the interaction between min_kelly and min_partition_leg_kelly, and clarifying the purpose of each filter. This semantic glue goes 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 opening sentence clearly states the action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the intended use case ('what should I bet on today') and differentiates from sibling tools by describing its unique segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and knobs.

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

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

The description provides clear usage context: it is built for opportunity discovery without paging hundreds of markets, and it explains when to adjust knobs like min_liquidity and max_spread_pp. However, it does not explicitly name alternative tools or state when *not* to use this tool, so it lacks full exclusionary guidance.

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

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

The description goes far beyond the readOnlyHint and idempotentHint annotations. It discloses history depth limits (60-day TTL), snapshot gaps that imply 'nobody scanned that day,' that decay uses daily closes rather than intraday data, and the meaning of negative values (SELL YES). It also details the response structure, including expired opportunities and the 'competition clock' median lifespan, giving the agent a thorough behavioral model.

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

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

Though dense, every sentence carries substantive information: purpose, args, response fields, and limitations are clearly separated with labels (Args, RESPONSE, LIMITS). It is front-loaded with the core purpose and uses concise, high-signal language without redundancy.

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

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

Given there is no output schema, the description fully compensates by explicitly enumerating response fields (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers operational context (snapshot TTL, run conditions for gaps, decay calculation basis), making the tool self-explanatory 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 100%: both parameters (days and window) are fully described in the input schema with defaults and allowed values. The description merely restates the same information ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') without adding new semantic meaning. Thus it meets the baseline for good schema coverage but does not exceed it.

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

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

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

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

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

It clearly conveys when to use the tool: when you care about edge age and decay, stating that 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternative tools or exclusion criteria, but the context is strong enough for an agent to know when this is the right choice.

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, and the description adds substantial behavioral detail: it walks the order-book ladder, returns top_of_book/vwap_fill_price/slippage_pp, and discloses the key risk of partial fills converting an arb into an unhedged position. It also states the size_usd interpretation differences for buys vs sells and single-market vs basket. No contradiction with annotations.

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

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

The description is dense and structured with SINGLE-MARKET and BASKET sections, making it scannable. It uses concise, information-dense sentences. It is longer than typical but justified by the tool's two modes and multiple return fields; a bullet list could improve readability slightly, but every sentence adds value.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is remarkably complete. It enumerates the returned fields for each mode, explains the verdict values, mentions thin_legs, forced_directional_risk, and max_clean_notional_usd, and grounds the tool in real trading risk. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100%, but description enriches all parameters: it explains the side values in both modes, size_usd meaning ('max spend on buys, target proceeds on sells' and 'settlement notional S' for basket), and clarifies that market selects single-market mode while event selects basket mode. This goes far beyond the schema's minimal 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from siblings by naming the exact use case ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade') and describes both single-market and basket modes. This 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?

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert an arb into unhedged directional position), effectively advising against alternative approaches when conditions are unfavorable.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavior: two operating modes, response structure (leg-by-leg prices and top_spreads_pp), safety fields with two compatibility_warning cases, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also explains that most macro shortcuts currently return warnings, setting expectations about real-world utility.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every section adds necessary detail. Some informational prose (e.g., '2-25pp apart because their participant pools differ') could be trimmed, but the overall structure and front-loading of the core purpose keep it from being rambling.

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

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

The tool is complex with no output schema, so the description compensates by explaining the response format, safety fields, temporal alignment, and skipped-pair counters. It also covers edge cases (non-equivalent bet shapes, unmatched events) and gives concrete examples of incompatibility, making it complete for an agent to invoke and interpret results.

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

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

The schema already covers all three parameters (100% coverage), so the baseline is 3. The description adds value by explaining the relationship between topic and the explicit overrides ('Overrides the topic-mapped... side'), and by enumerating the 10 accepted topic values in the description. This goes beyond the schema's descriptions and clarifies mode 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the verb (compute/display spread) and the resource (cross-venue pair). It differentiates from sibling tools by focusing on the Kalshi-Polymarket comparison and details two input modes, 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 provides explicit when-to-use guidance: 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so' and warns 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not name alternative tools, but gives clear conditionals for when spreads are meaningful, so it earns a 4 rather than 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, covering safety. The description adds valuable behavioral context beyond annotations: scoping to 'anonymous IP, BYO key hash, or account ID' and the list-all-keys behavior when the key argument is omitted. This 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 four sentences, each earning its place. It front-loads the core action first ('Retrieve a value previously saved via remember'), then adds usage context, scoping, and sibling relationships. No fluff or redundant phrasing.

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 retrieval tool with one optional parameter, strong annotations, and no output schema, the description is complete. It covers the tool's function, when to use it, scoping details, and how it relates to sibling tools. The agent has enough information to invoke it correctly without additional context.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to retrieve (omit to list all keys)'. The description adds semantic richness by giving concrete examples of key contents (user's target ticker, address, research notes) and explaining the omission behavior in context, which helps the agent understand the parameter's purpose beyond the schema.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb ('Retrieve') with a clear resource (saved values), and distinguishes it from sibling tools by naming remember (save) and forget (delete).

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 to look up context the agent stored earlier' and provides concrete examples (target ticker, address, prior research notes). It also explains when not to use alternatives by pairing with remember/forget, giving clear context for retrieval versus saving or deleting.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the 'public uploads' scope and tag-filtering behavior, but does not disclose additional details like pagination limits or time windows. With annotations carrying safety, a 3 is appropriate.

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

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

The description is a single, efficient sentence: 'Most recent public uploads, optionally tag-filtered.' It is front-loaded with the core purpose and every word contributes value. 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?

This is a simple read-only feed tool with only three optional parameters, full schema documentation, a defined output schema, and comprehensive annotations. The brief description is adequate for understanding the tool's basic behavior, though it could mention the 'public' scope more explicitly. Given the low complexity and rich structured metadata, the completeness is high.

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

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

Schema coverage is 100% with each parameter documented (tags, limit, tagmode) and examples. The description adds the concept of 'tag-filtered' which maps to tags/tagmode, but provides no additional meaning beyond what the schema already offers. Baseline 3 applies.

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

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

The description clearly states the tool returns 'most recent public uploads' with optional tag filtering. This is a specific verb+resource+scope construction that distinguishes it from siblings like by_user and by_group, which filter by user/group rather than recency.

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 no explicit guidance on when to use this tool versus alternatives. It implies usage (when you want recent public uploads) but does not name alternatives or state when not to use it, such as when user/group-specific uploads are needed.

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

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

Description contradicts readOnlyHint annotation by stating that mark_read:true flags events read and changes future call results, implying state mutation. Annotation says readOnlyHint=true. Therefore score 1 per rule.

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

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

Three sentences, front-loaded with the main purpose, no redundancy. Every sentence provides useful info (filtering, read-state, alternative endpoint).

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

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

Despite no output schema, description covers return fields (source, citation_uri, raw payload), read-state behavior, filter options, and alternative access method. This is comprehensive for a 5-parameter read tool.

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

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

Schema already has 100% coverage. Description adds value by explaining mark_read's effect on subsequent calls and giving a concrete type example ('sec_8k'), exceeding 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?

The description uses the verb 'Pull' plus resource 'fired events from your subscription feed', clearly distinguishing it from siblings like list_subscriptions (which lists subscriptions) and recent (general recent items). It specifies the return type and source.

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

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

Provides clear usage context: filtering by type/since, mark_read semantics, and notes polling works fine. Also offers an alternative HTTP endpoint for scripts/dashboards, but doesn't explicitly contrast with sibling tools, so not a perfect 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, openWorld, idempotent, and non-destructive. The description adds significant behavioral detail beyond these: parallel fan-out to SEC EDGAR, GDELT-to-GNews fallback (with conditions), and USPTO soft-fail due to API sunset, plus the return structure. This is exactly the kind of context annotations cannot 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 dense and front-loaded with the core purpose, then details sources, fallbacks, and return format. While it includes multiple illustrative examples ('What's new with X' etc.) that are useful for NL matching, they add length. Overall, every sentence contributes value, but it is slightly longer than strictly necessary.

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

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

Since there is no output schema, the description fully covers the return shape ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs') and explains edge cases like GDELT/GNews fallback and USPTO soft-fail. It also cross-references entity_profile, making the description complete for a tool of this complexity.

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

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

The input schema provides 100% coverage with descriptions for all three parameters, including the exact `since` formats (ISO date and relative shorthand) and examples for `value`. The description repeats the same `since` details but adds no new parameter semantics, so it meets the schema-heavy baseline of 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 precisely defines the tool as a 'change feed for a company in the last N days/weeks/months' and includes concrete query examples. It explicitly distinguishes from sibling tool entity_profile, noting 'Use entity_profile instead when you want the static profile,' which makes its scope 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 clear usage context with natural language triggers ('What's new with X', 'latest on Y') and provides an explicit alternative: 'Use entity_profile instead ... regardless of window.' It also explains the source fan-out and fallback behavior, helping the agent 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?

Adds important behavioral details beyond annotations: authentication-dependent persistence (persistent for authenticated users, 24h for anonymous) and scoping by identifier. Annotations already indicate idempotent and non-destructive, and the description's write nature aligns with readOnlyHint=false.

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

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

Three sentences, front-loaded with purpose, includes examples for usage, and provides pairing hints without fluff. Every sentence adds value.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, when-to-use, persistence behavior, and relationships to sibling tools. It is fully sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no new parameter-level details beyond the schema's own examples and value 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 tool saves data for later reuse, with a specific verb ('Save') and resource (data/memory). It distinguishes itself from siblings by explicitly mentioning key-value storage and pairing with recall (retrieve) and forget (delete).

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: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: auto-disambiguation of input, internal cascading through multiple lookup endpoints, and data sources (SEC EDGAR, RxNorm) with citation URIs. This goes beyond the safety profile, though it doesn't mention rate limits or failure modes, which are less relevant given the read-only nature.

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

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

Though longer than average, every sentence adds value: example queries, purpose statement, usage priority, supported types, outputs, and efficiency benefit. It is front-loaded with the purpose and instantly actionable. 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?

With no output schema, the description fully explains return values for each entity type, including citation URIs. It covers the internal cascading behavior and input flexibility, making it complete for a tool of this complexity. The absence of an output schema is compensated extensively.

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 provides enum and basic descriptions with 100% coverage. The description significantly enriches each parameter: for type='company' it specifies accepted inputs (ticker, CIK, name) and exact output fields (ticker, 10-digit CIK, company_name, citation URI); for type='drug' it lists RxCUI, ingredient, brand, and citation. This adds decisive meaning for correct invocation 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 verb 'resolve' and resource 'entity' (names to canonical identifiers), with specific examples of user queries. It distinguishes from siblings by emphasizing that it provides IDs needed as input by other tools, and lists supported entity types with exact outputs.

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 instructs 'Use FIRST whenever you have a name but need an ID', establishing clear when-to-use guidance. It also contrasts with manual lookups ('replaces 2-3 manual lookups') and enumerates supported types and input formats, giving the agent actionable context for when to invoke this tool over others.

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 and idempotentHint. The description adds behavioral context by explaining the tool internally probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. This goes beyond the safety annotations and clarifies 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 plus an illustrative question. It is front-loaded with the core purpose, immediately explains the mechanism, and includes a concrete use case without any redundant or filler 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?

The tool is moderately complex, but the description covers the essential behavior and output. Combined with detailed schema and annotations, the description is complete enough for an agent to select and invoke the tool correctly. It does not detail error handling, but that is not expected for a read-only comparison tool.

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

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

Schema coverage is 100%, and the schema descriptions already explain each parameter (models, _apiKey, context, entities). The description does not add significant parameter semantics beyond what the schema provides, 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 clearly states the tool compares AI visibility across multiple entities side-by-side. It specifies the method (probes each entity with ai_visibility_check, ranks by score) and distinguishes it from the single-entity sibling tool ai_visibility_check and generic compare_entities by focusing on AI visibility for competitive audits.

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

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

The description provides clear usage context: competitive AI-marketing audits with an example question. It implies that for single-entity checks, ai_visibility_check is the alternative, but it does not explicitly state when not to use this tool or name alternatives beyond the underlying probe.

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 notable behavioral context beyond the annotations: it explains partial failure degradation, warns about 5-30s latency for first bundlephobia measurement, and mentions the sources_failed field. It also discloses the NPM-only limitation. 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 detailed but every sentence carries useful information: purpose, use case, return fields, failure behavior, and ecosystem scope. It is well-structured with semicolons and a list of output fields, ensuring high information density without fluff.

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

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

Given the tool's complexity (composite of two external services, multiple output dimensions) and lack of an output schema, the description is exceptionally complete. It enumerates all return components, explains the failure mode, and notes timing delays. 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?

The input schema already covers 100% of parameter semantics with descriptions for 'package' and 'version', including scoped package support and defaulting behavior. The description restates these points but does not add significant new meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly defines the tool as a composite npm package evaluation check, specifying the source services (deps.dev, bundlephobia) and the exact question it answers ('should I add this npm package to my project'). It is distinct from the sibling tools, which focus on other domains like research, alerts, or subscriptions.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes an ecosystem limitation (NPM only in v1) and points to an alternative for other ecosystems (deps.dev:version directly), giving 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description goes further by disclosing the embedding model (BGE-base-en), window size (500-char overlapping), the 200K character cap with truncation and flagging, and the exact return payload (offsets + scores). This fully prepares the agent for observable behavior without relying on structured fields.

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 action and contains four sentences, each serving a distinct purpose: definition, usage context, pairing with a sibling, and technical implementation details. No filler or redundant phrasing. Despite its length, every sentence earns its place.

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

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

Without an output schema, the description compensates by explaining the return format (passages with offsets and similarity scores) and the truncation cap. It also covers edge-case behavior (truncation flagged) and gives a concrete pairing workflow. For a tool of moderate complexity, this is complete and leaves no critical ambiguity for an agent deciding to invoke it.

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

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

Schema coverage is 100% and each parameter already has a clear description, so the baseline is 3. The description adds some context (e.g., examples of text types and query format) but doesn't introduce new semantic nuances beyond what the schema provides. It reinforces but doesn't significantly extend parameter meaning.

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

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

The description opens with a specific verb phrase 'Semantic search INSIDE a fetched record,' clearly distinguishing this tool from siblings like ask_pipeworx or recall. It also specifies the resource (a record already fetched) and the return format (top-N passages with character offsets and similarity scores), making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a direct companion tool (ask_pipeworx_grounded) and describes a two-step workflow, giving clear context for when this tool is the right choice versus 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?

The description adds significant behavioral context beyond the annotations: it discloses the need for OAuth authentication, the SMS 10/day cap, phone verification requirement, and the always-on feed behavior. Annotations already indicate the operation is a write (readOnlyHint false) and non-destructive, so the description complements them without contradiction.

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

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

The description is dense but well-structured: it opens with the core action, then covers supported types and delivery channels in a logical flow. While it is fairly long, every sentence earns its place by adding necessary details about types, parameters, or delivery constraints.

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 complexity of three parameters with nested objects and multiple subscription types, the description is quite complete: it mentions return value, auth requirements, and all delivery options. There is no output schema, so the description compensates by stating the returned id. Minor gaps like error cases are acceptable given the detail 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?

Schema description coverage is 100%, but the tool description enhances parameter understanding by providing concrete examples for each supported type (e.g., items:["5.02"] = officer change for sec_8k). This adds practical meaning beyond the schema's property definitions, especially for nested params objects.

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

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

The description clearly states the tool's function with a specific verb and resource: "Create a proactive monitoring subscription to a live-data event stream." It also explicitly notes the return value (new subscription id), distinguishing it from related sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on prerequisites (requires Pipeworx OAuth, anonymous/BYO cannot persist) and explains delivery channels, including how to retrieve feed alerts via recent_alerts or a direct URL. While it doesn't explicitly name alternative tools for every scenario, it implies when this tool is appropriate and even suggests how to consume the feed.

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 destructiveHint. The description adds valuable context beyond these: it returns live-catalog-derived example questions with tool/argument shapes, and explains the no-argument vs topic argument behavior. This goes beyond what annotations provide, though it doesn't detail every edge case.

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

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

The description is a single dense passage that front-loads natural language queries and clearly explains purpose, behavior, and parameters. It is a bit long but every clause contributes; no obvious fluff. It earns a 4 for being appropriately detailed without being 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 compensates by explaining the return format (category-bucketed examples with tool+argument shapes). It also covers argument variants, use case, and connection to meta-tools, making it fully sufficient for an agent to decide whether and how to invoke this tool.

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

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

The input schema already describes the topic parameter with all allowed values (finance, pharma, etc.) and states to omit for a cross-category spread. The description adds only brief examples ('finance', 'pharma', 'betting') which do not exceed the schema's coverage, so the baseline 3 applies.

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

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

The description clearly states this is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses a specific verb ('returns') and resource ('category-bucketed example questions'), and distinguishes itself from siblings by positioning as the first tool to use for learning what to ask.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This is clear when-to-use guidance, but it doesn't explicitly state when not to use it or name alternatives like discover_tools, so it falls short of a 5.

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

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

Beyond the annotations, the description discloses that ownership is enforced, the row is deactivated (not deleted), and historical events remain available via recent_alerts. This provides valuable insight into side effects and safety, going well beyond what annotations already declare.

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

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

The description is three sentences, each earning its place: the action, the ownership restriction, and the deactivation behavior. It is front-loaded and free of 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 simple tool with one parameter and no output schema, the description covers the primary purpose, a key constraint (ownership), and the relevant behavioral nuance (deactivation vs deletion). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, with the parameter 'id' fully documented. The description's 'by id' adds no new semantic information; it simply mirrors 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 uses a specific verb ('cancel') and resource ('subscription') with an explicit identifier ('by id'), clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description gives clear context (canceling a subscription) and an important ownership constraint, but it does not explicitly mention alternatives or when not to use the tool. The usage is implied rather than contrasted with sibling tools.

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

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

Annotations already mark readOnly/openWorld/idempotent, and the description adds rich behavioral detail beyond them: the two-path routing (SEC EDGAR/XBRL fast path vs. grounded pipeline), the use of 'verbatim evidence' and 'pipeworx:// citation,' the percentage-delta math, and the return of a verdict list. It clearly describes what the agent can expect 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 long but information-dense, front-loaded with use-case examples and then moving to specifics. The 'Replaces 4–6 sequential calls' sentence adds context, though the description could be slightly tightened without losing important guidance.

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

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

Given only 2 simple parameters and no output schema, the description fully explains what the tool returns (verdict options, actual value with citation, reasoning), the routing logic, and the type of claims it handles. It is complete enough 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?

The schema covers both parameters completely (100% coverage), but the description and inline parameter descriptions add value by giving concrete examples ('Apple's FY2024 revenue was $400 billion'), explaining tolerance_pct as an override with 1–2 for hallucination detection, and noting the default is implied by wording capped at 5.

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

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

The description opens with concrete natural-language trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes from sibling tools by detailing when to use it (any factual check) and by contrasting the SEC EDGAR/XBRL fast path for company-financial claims with the general grounded pipeline for other facts.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear routing rules for financial vs. any other claim. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is strong enough to guide selection.

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