Url

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context: default model is free, Anthropic requires BYO key, and it returns per-model details (score, confidence, signals, raw_response) plus a combined view. This enhances transparency 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 a single well-structured paragraph with no wasted words. It covers purpose, default behavior, optional configuration, return value structure, and use cases, all in concise form.

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

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

Given four parameters (one required), no output schema, and no nested objects, the description fully covers the return value format (per-model object + combined view) and parameter semantics. It is complete enough for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful meaning: gives examples for entity ("Pipeworx", "OpenInvoice"), explains models (omit for default, supported values), clarifies _apiKey necessity, and describes context purpose. This goes beyond the schema's 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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model, distinguishing it from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' by its specific verb 'probe' and resource 'LLMs' and '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 context for when to use the tool: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the optional use of _apiKey for Anthropic. However, it does not explicitly state when not to use it or mention alternative sibling tools, which would improve 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?

Discloses routing to 4,552 tools across 1,160 sources, argument filling, and return of structured answers with citation URIs. Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and description adds behavioral context beyond that.

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

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

Description is long but well-organized: starts with prioritization instruction, explains functionality, provides examples, and guides to alternatives. Minor redundancy, but no wasted sentences.

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 (many parameters, no output schema, numerous siblings), the description thoroughly covers purpose, usage context, behavioral traits, and parameter meaning. No gaps identified.

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

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

Schema coverage is 100% with all aliases documented. Description confirms natural language input but does not add significant meaning beyond the schema. 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?

Clearly states it answers factual questions using structured data sources, with specific verbs like 'routes' and 'returns'. Distinguishes from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', provides example queries, and tells when to use alternatives (hallucination-resistant ask_pipeworx_grounded, broad deep_research). Includes specific directive 'START HERE'.

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 non-destructive nature. Description adds substantial context: it routes through 4,552 tools across 1160 sources, fills arguments, fetches data, and extracts answer using only tool result. Details return format including explicit refusal reasons.

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

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

The description is concise (about 100 words) and front-loaded with the core purpose. Every sentence adds value, including process details, return format, refusal reasons, and usage comparison. No wasted words.

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

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

Despite the tool's complexity, the description covers the full retrieval and extraction process, return structure, refusal conditions, and appropriate use cases. No output schema exists, but the description provides detailed return format, making it complete for an AI agent.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. Description adds value by explaining the tool accepts natural language questions and clarifies the aliases, going beyond schema. Baseline 3, elevated to 4 for added context.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, specifying the verb 'extracts the answer' and resource 'tool result'. It explicitly distinguishes from sibling ask_pipeworx by noting cost and use cases.

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: 'whenever an answer will be quoted, cited, or acted on' and provides concrete examples (financial verdicts, legal claims). Also advises against using for casual lookups, directing to ask_pipeworx instead.

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

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

The description goes far beyond annotations, detailing the fan-out logic, response structure, resolver contract (including confidence levels), parent event extraction, news fields with fallback behavior, safety short-circuits (low confidence, closed markets), wide-spread warnings, and resolution rule risk. It discloses internal pipeline steps and edge cases fully, making agent behavior predictable.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety, etc.). It front-loads the purpose. While verbose, every part adds necessary detail for correct usage given the tool's complexity. Could be slightly more concise, but no wasted sentences.

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 complex fan-out logic, multiple data sources, and safety mechanisms, the description covers all necessary aspects: input variations, expected outputs (evidence, analysis, market info), confidence handling, parent events, news fallback, and edge cases (closed markets, wide spreads). No output schema exists, so the description fully substitutes it.

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

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

Schema coverage is 100%, and the description adds meaning: explains the 'market' parameter accepts slug, URL, or question text; 'depth' enum with quick/thorough definitions; 'include_raw' with trade-off explanation (summary vs full payloads). This adds value beyond the schema description for all three parameters.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies the verb 'research', the resource 'Polymarket bet', and provides extensive detail on the process (resolve, classify, fan-out, return evidence). It distinguishes itself from sibling tools by being the comprehensive research tool for a specific bet, while siblings like polymarket_edges focus on edges or arbitrage.

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

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

The description explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides warnings about inspecting market_match_confidence before trusting analysis, and advises checking cancellation rules before sizing sports/exoteric bets. However, it does not explicitly list when not to use this tool or alternatives for specific scenarios.

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, indicating a safe, non-mutating operation. The description does not contradict these and adds no further behavioral details (e.g., no side effects, no authentication needs), which is acceptable but does not exceed the baseline.

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 concise sentence with a parenthetical, no wasted words. It could be slightly more structured (e.g., listing required vs optional), but it remains efficient and 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 tool's low complexity, full schema coverage, and comprehensive annotations, the description sufficiently conveys all necessary information for an agent to use the tool correctly. No gaps remain.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description merely summarizes the schema (e.g., 'optionally protocol, port, path, hash') without adding new meaning or usage context, so it meets the baseline.

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

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

The description clearly states the tool's purpose: 'Build a URL string from components.' It specifies the key components (hostname, protocol, port, path, hash, query) and distinguishes it from the sibling 'parse_url' tool, which does the inverse.

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 indicates required input (hostname) and optional components, plus the query object. It implicitly suggests usage when constructing URLs, but does not explicitly exclude alternative tools or provide 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 (readOnlyHint, idempotentHint, etc.) already declare safety. Description adds context: data sources (SEC EDGAR for companies, FAERS for drugs), handling off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. Does not discuss error handling or edge cases, but sufficient given annotations.

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

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

Description is concise (single paragraph) with front-loaded natural language triggers. Every sentence adds value—usage guidance, data details, efficiency claim. No wasted words.

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

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

Given no output schema, description states it returns 'paired data + pipeworx:// citation URIs' and sorted results. This gives a general idea but lacks specific field names or structure. For a complex tool with two entity types, slightly more detail on return format would improve 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?

Schema coverage is 100%, but description significantly expands meaning: for 'type', it details data sources and scope; for 'values', it provides examples and clarifies tickers/names. This adds value beyond schema descriptions.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verb 'compare' and resource 'entities'. It distinguishes from sibling tools like entity_profile by explicitly advising preference over sequential single-pack lookups.

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

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

Provides explicit triggers like 'Compare X and Y', 'X vs Y', etc., and clearly directs when to use (comparing 2-5 entities) and why to prefer it over alternatives ('ALWAYS PREFER over sequential single-pack lookups'). Also explains what each type retrieves.

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?

Disclosures include: account requirement, paid plan for thorough depth, parallel decomposition, return format (findings packet with citations and gaps[]), expected duration (15-60s). No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 verbose but well-structured with critical info front-loaded (account requirement). Could be more concise while retaining all necessary 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 the tool's complexity, the description fully covers prerequisites, behavior, return format, and limitations. No output schema exists, but the explanation of the findings packet is sufficient.

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

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

Schema covers both parameters 100%; description adds significant value by explaining depth enum values (quick=3, standard=5, thorough=8) and the paid plan constraint, plus clarifying that the question can be broad/multi-part.

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

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

The description explicitly states 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and contrasts with sibling tools like ask_pipeworx, clearly distinguishing its purpose for broad/multi-part questions over structured data.

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 (broad/multi-part) and when-not-to-use (breaking news, single lookup) guidance, naming alternatives (ask_pipeworx) and explaining the differences.

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. The description adds valuable behavioral context: it returns top-N most relevant tools with complete schemas and examples, and each result is ready to call directly. 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 front-loaded with the core purpose and is well-structured. While it is somewhat lengthy, every sentence adds value (examples, usage guidance, behavioral details). A minor reduction could improve conciseness, but it remains efficient.

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

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

Despite no output schema, the description fully explains what the tool returns: top-N tools with names, descriptions, full input schemas, and curated examples. It also states results are ready to call directly, covering all needed information for an agent to use the tool effectively.

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% (6 parameters all described). The description adds meaning beyond schema by noting that 'query' accepts aliases (task, q, search, description) and provides examples like 'look up FDA drug approvals'. It also documents the limit parameter default (20) and max (50).

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: 'Find tools by describing the data or task.' It provides specific examples of topics (SEC filings, FDA drugs, etc.) and distinguishes it from sibling tools by advising 'Call this FIRST when you have many tools available.' This is a specific verb+resource with clear differentiation.

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

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

The description explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist.' It also advises calling it first when many tools are available. However, it does not explicitly state when not to use it or provide direct alternatives, though the context of sibling tools implies this is for discovery before other actions.

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

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

The description goes beyond annotations (readOnlyHint true, idempotentHint true) by detailing behavior: USPTO API sunset soft-fail, GDELT→GNews fallback, return structure with specific fields like cik, recent_filings with URIs, fundamentals sorted by period_end DESC, and patents status. 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 relatively long but densely packed with valuable information. It is front-loaded with example queries and immediately states the primary purpose. Every sentence adds meaningful detail, though some trimming could improve conciseness without losing critical context.

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

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

Given the complexity of the tool (multiple data sources, fallback mechanisms, unsupported features), the description covers all necessary aspects: what it returns, limitations (USPTO, name unsupported), and how it handles errors (soft-fail). No output schema exists, so the description adequately explains the return structure.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'value'. The description adds crucial semantics: 'type' only supports 'company' currently, 'value' must be ticker or zero-padded CIK, not names, and directs to resolve_entity for names. This adds meaning beyond the schema.

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

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

The description explicitly states it provides a 'full cross-source profile of a US public company' and lists example queries like 'tell me about X' and 'company profile for Microsoft'. It distinguishes itself from sibling tools by specifying it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF) and should be preferred over chaining single-pack lookups.

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

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

The description clearly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name).' This provides explicit context for alternatives.

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

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

Annotations already indicate destructiveHint=true. Description adds context about deleting sensitive data and pairing, but no contradiction. Lacks details on cascading effects or confirmation, but adequate.

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

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

Two clear, front-loaded sentences with zero waste. Every sentence adds value: action, when to use, and sibling pairing.

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 single parameter, no output schema, and rich annotations, the description is fully complete: it states purpose, usage conditions, and related tools. Nothing missing.

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

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

Schema has 100% coverage with description 'Memory key to delete'. Description only reiterates 'by key', adding no new meaning beyond schema.

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

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

Description explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by 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?

Clear guidance on when to use: 'context is stale, task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', giving explicit alternatives and 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?

Adds value beyond annotations by describing the extraction process (fetches, extracts title/description/links) and output format. 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?

Well-structured with clear two-sentence purpose plus bullet use cases. Slightly wordy but front-loaded with key info.

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

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

No output schema but explains return format. All parameters documented in schema. Adequately covers context for 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?

Schema coverage is 100%, so description adds no new parameter meaning. Baseline 3 justified as schema does heavy lifting.

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

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

The description clearly states the tool generates an llms.txt file for a URL, listing specific use cases. While distinct from siblings, it doesn't explicitly differentiate 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?

Lists useful scenarios but lacks when-not-to-use or alternative tool guidance. Implicitly suggests usage but no explicit 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, idempotentHint, openWorldHint, and destructiveHint. The description adds useful context by specifying the returned fields and default behavior (active subscriptions only), which is valuable 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 two sentences: the first states the action and return data, the second provides usage guidance. Every sentence adds value with no wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the purpose, return fields, parameter, and use case. It is complete given the complexity and available structured data.

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

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

The input schema fully covers the single optional parameter 'include_inactive' with a clear description. The tool description repeats 'active' but does not add new parameter-level detail, so baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates the return fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by being a read operation.

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 recommends using this tool to review monitored subscriptions before adding more or to get an id for cancellation. While it gives clear context, it does not mention when to avoid using 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?

Beyond annotations (read-only, idempotent, non-destructive), the description adds useful behavioral details: handling of leading '?' and conversion of repeated keys into arrays.

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?

A single, front-loaded sentence with no unnecessary words. Every part adds meaning.

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

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

For a one-parameter tool with rich annotations, the description fully covers input format and key output behavior, leaving no gaps.

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

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

With 100% schema coverage, the description still adds value by noting the optional leading '?', which is not in the schema's example.

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 'parse' and the resource 'query string', and specifies the behavior for repeated keys, distinguishing it from sibling tools like 'parse_url'.

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

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

The description implies usage for query strings but does not explicitly state when to use this tool versus alternatives like 'parse_url' or exclude certain cases.

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

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

Description adds 'keyless, offline' beyond annotations (readOnlyHint, idempotentHint). Lists components returned, but no mention of error handling or limitations. Good added context.

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

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

Single sentence, no wasted words. Clearly structured and front-loaded with purpose.

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

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

Given low complexity (1 param, no output schema), description adequately covers purpose and output. Missing error scenarios but acceptable for a simple parsing 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?

Only one parameter 'url' with schema description providing example. Description does not add beyond schema coverage (100%). 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?

Clearly states the tool parses a URL into its components, listing specific parts like protocol, host, query as object. Distinct from siblings like build_url and parse_query.

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?

Mentions 'keyless, offline' implying no external dependencies, but does not explicitly state when to use versus alternatives or when not to use. Adequate but lacks explicit guidance.

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

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

Annotations indicate mutability (readOnlyHint=false) and non-destructiveness. The description adds valuable behavioral details: rate limit (5 per identifier per day), free usage (no quota cost), and that team reads digests daily. This goes beyond what annotations provide.

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

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

The description is 5 sentences, each adding value. It could be slightly more concise, but the structure is clear and front-loaded with the core action. No wasted words.

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

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

For a feedback tool with no output schema, the description covers all necessary aspects: purpose, usage, behavioral constraints, and parameter guidance. It is fully self-contained and requires no 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 descriptions for all properties. The description adds practical guidance, such as avoiding user prompts and being specific. It elaborates on the 'type' enum, providing nuanced usage examples.

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

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

The description clearly identifies the tool as a feedback mechanism for the Pipeworx team, specifying categories (bug, feature, data_gap, praise) and what to include. It distinguishes itself from sibling tools by focusing on user feedback about Pipeworx tools/packs, not other actions.

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 (for bugs, missing features, data gaps, praise) and when not to (don't paste end-user prompts). It does not directly compare to sibling tools, but the usage context is well-defined.

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 safety traits; description adds valuable context: data source (CF analytics-engine), no PII, caching details (5min-1h). No contradictions.

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

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

Description is concise: three sentences plus bullet list. Front-loaded with main action, no redundant information.

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

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

Explains what is returned (top tools, packs, total call volume) and caching. Lacks precise return format, but sufficient for agent to understand usage. No output schema to compensate.

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

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

Schema covers parameter fully (enum description). Description adds behavioral meaning: shorter windows show hot trends, longer show steady-state demand. Adds value beyond schema.

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

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

Description clearly specifies the tool returns top tools, packs, and call volume over a window. Uses specific verbs and resources, and distinguishes from siblings by focusing on trending data.

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?

Includes three explicit use cases for when to use the tool. Does not explicitly state when not to use it or name alternatives, but context is clear enough for an agent to decide.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds rich detail: SEMANTIC ANCHOR with Jaccard similarity, PARTITION FILTER, FILL CHECK with book depth analysis, and realizable_edge_pp <= 0 no-trade rule. No contradictions.

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

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

Well-organized with labeled sections, but somewhat verbose with technical details that could be streamlined. Every sentence adds value, but length may hinder quick comprehension.

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?

Comprehensive: covers all modes, response structure, filtering logic, failure conditions, and integration with fill check. No output schema exists, but description adequately explains what the tool returns.

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

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

Schema covers 100% of parameters with descriptions. Description enhances by explaining each mode's purpose, giving examples (slugs, seed questions), and detailing internal logic like monotonicity checks and fill pricing.

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 finds arbitrage opportunities via specific methods (monotonicity violations + partition-sum checks). It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on cross-market arbitrage scanning.

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 guidance on when to use NO args vs `event` vs `topic`, and explains the differences. Recommends `event` for specific markets and `topic` for cross-event scanning. Does not exclude when not to use it, but context with sibling tools is sufficient.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details: caching (1h KV), internal algorithms (GDELT, lognormal barrier, favorite-longshot bias), and why fed bets are excluded. This goes well 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 very long (500+ words) and includes technical details that may overwhelm an agent. While it is well-structured with segments and front-loaded purpose, it could be more concise to improve readability for an AI.

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

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

Despite no output schema, the description fully describes the response structure (by_segment, fed, diagnostics) and caching behavior. This makes the tool's output and behavior completely transparent.

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 good parameter descriptions. The description adds extra context for knobs like min_liquidity, max_spread_pp, etc., explaining their purpose in detecting tradeable edges. This adds value beyond what the schema already provides.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly says 'Built for "what should I bet on today"'. It distinguishes from siblings by naming specific model families and segments.

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 extensive context on when to use each segment (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and mentions knobs for filtering. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so an agent might miss when to use alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds significant transparency: it reads snapshots, returns tracked/expired arrays with time-series, first_seen, trend, decay_pp_per_day, lifespan_days, and snapshot_dates. It also discloses limitations (60-day TTL, decay from daily closes not intraday). No contradiction with annotations.

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

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

The description is compact but thorough. It front-loads the purpose, then structures the response fields clearly (tracked, expired, snapshot_dates) and ends with limitations. Every sentence earns its place without redundancy.

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

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

Despite no output schema, the description fully explains the return structure and key fields. It covers the main use case, data interpretation (trend, decay), and limitations. This provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description mostly echoes the defaults and adds minimal context (e.g., 'snapshot family'). It does not significantly extend beyond the schema, so a score of 3 (baseline) 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 that the tool provides telemetry on edge persistence and decay, answering 'how long has this edge existed and is it shrinking?' It distinguishes the value proposition (fresh vs. old edges) and implicitly differentiates from sibling tools like polymarket_edges.

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

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

The description gives a concrete scenario for when to use the tool (contrasting fresh vs. 3-week-old edges) but does not explicitly mention when not to use it or provide alternative tools. The usage context is clear, but exclusions are missing.

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 indicate the tool is readOnly, idempotent, and non-destructive. The description adds critical behavioral context: it walks the order-book ladder, returns verdicts like 'clean|degraded|cannot_fill', and highlights risks such as thin books making theoretical overround uncapturable and partial basket fills creating unhedged positions. This goes well 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 well-structured with a brief overview followed by mode-specific details. It is front-loaded with the purpose and requirements. However, it is somewhat lengthy and could be tightened slightly without losing information. Overall, it earns its length by thoroughly explaining a complex tool.

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

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

Despite having no output schema, the description enumerates all major return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers prerequisites (requires market or event), constraints (size clamp), and behavioral warnings. The tool is complex with two modes, and the description ensures an agent has sufficient context to invoke it correctly.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description enriches these by adding defaults (size_usd=1000, clamp 10-1,000,000), explaining side behavior in basket mode (auto-detect from partition sum), and clarifying that market and event are mutually exclusive. Some nuance like the exact interpretation of size_usd in basket mode is briefly touched but could be more detailed.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It details two distinct modes (single-market and basket) and explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by stating it should be used before acting on their signals.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the conditions under which each mode applies and warns against partial fills converting an arb into a directional position, though does not explicitly state when not to use it.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description discloses key behavioral traits: compatibility_warning conditions (shape mismatch, no token overlap), temporal alignment check, and skipped cross-type/subtype counters. These details prevent misuse and clarify when spreads are meaningful.

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, starting with the core concept and then detailing modes, response, and safety fields. Every sentence adds value, though some repetition (e.g., 'pre-mapped ≠ tradeable' in last line) could be trimmed.

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

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

Despite lacking an output schema, the description fully explains the response structure (leg-by-leg prices, spread, compatibility_warning, temporal_alignment). It covers edge cases and limitations, making the tool self-contained for an AI agent.

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

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

Schema coverage is 100%, and the description adds significant meaning: lists all 10 topic shortcuts, explains override behavior for explicit parameters, and provides examples. This exceeds the schema's basic descriptions.

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

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

The description clearly states it calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like `polymarket_arbitrage` by focusing on this specific pair. It explicitly describes two modes (topic shortcuts and explicit tickers), making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use each mode and warns that most pre-mapped topics return compatibility warnings, so the agent should not assume tradeable spreads. However, it does not directly compare to sibling tools like `polymarket_arbitrage` or advise when to use this tool vs 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scope details and clarifies the listing behavior, providing additional context 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?

Description is three sentences, front-loaded with the primary action, and contains no fluff. Efficiently conveys all necessary information.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage, scope, and pairing. It is fully sufficient for correct invocation.

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

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

Schema coverage is 100% with the key parameter described. The description repeats that omitting key lists all, adding no new semantic information beyond the schema. 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 retrieves a value saved via 'remember' or lists all keys when omitted. It specifies the resource (saved values) and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description provides explicit guidance on when to use: to look up previously stored context without re-deriving. It mentions scoping (per identifier) and pairing with 'remember' and 'forget', giving clear usage context.

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

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

Annotations declare readOnlyHint=true, but the description describes mark_read:true as flagging events read, a state change, creating a contradiction. Without this contradiction, the description adds useful behavioral context (return fields, filtering, polling suitability).

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

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

Three sentences with front-loaded purpose, each sentence adding value: purpose, return fields, filtering and mark_read, polling and alternative. No wasted words.

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

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

The description covers return fields, filtering options, mark_read behavior, and an alternative access method. Combined with annotations (idempotentHint, readOnlyHint), it is complete for a read tool with no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds marginal context for mark_read beyond schema (e.g., effect on next call), but does not significantly enhance meaning for other parameters.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It distinguishes from sibling tools like 'list_subscriptions' which list subscriptions themselves, not events.

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

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

The description provides context that polling works and mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly compare to other sibling tools or provide when-not-to-use conditions.

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

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

Discloses fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), notes soft-fail for USPTO, and describes return structure (changes[], total_changes, citation URIs). Adds significant detail beyond annotations (readOnlyHint, etc.) without contradiction.

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

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

Front-loaded with example queries; dense but every sentence adds value. Slightly long but appropriate for the tool's complexity.

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

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

Comprehensive for a complex tool with multiple sources and fallback logic; describes return structure despite no output schema. No gaps for agent usage.

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 description adds meaning: explains `since` accepts ISO dates and relative shorthand, suggests '30d' or '1m' for monitoring, clarifies `type` is only 'company', and `value` can be ticker or CIK. Exceeds schema verbatim.

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?

Clear verb+resource ('change feed') with specific scope ('company in the last N days/weeks/months'). Distinguishes from sibling 'entity_profile' via explicit alternative.

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 example queries for when to use and states 'Use entity_profile instead when you want the static profile' for when-not, with clear context on 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?

Discloses behavioral traits beyond annotations: memory persistence differences between authenticated vs. anonymous users (24-hour retention), scoping by identifier. Annotations indicate idempotent (true) and non-destructive, which description does not contradict.

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

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

Three sentences with no fluff. First sentence states core purpose, second gives usage guidance, third adds behavioral nuance. Each sentence earns its place.

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

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

For a simple key-value store with two required parameters, no output schema, and enumless params, the description fully covers purpose, usage, persistence behavior, and integration with sibling tools. Nothing essential missing.

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

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

Schema coverage is 100% and already describes key and value with examples. The description does not add new semantic details for the parameters beyond contextualizing their use, so baseline score 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 saves data for later reuse across conversations or sessions, with specific verbs and resource. It distinguishes from sibling tools recall and forget by name, making its unique role clear.

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

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

Explicitly instructs when to use (when discovering something worth carrying forward) and mentions paired tools recall and forget for retrieval and deletion, providing clear context and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups', revealing internal complexity. 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?

Description is detailed yet structured: example queries, usage instruction, then bullet-style listing of types and their returns. It is front-loaded with purpose and avoids redundancy. Could be slightly more concise, 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 no output schema, the description provides sufficient output details for both company and drug types, including citation URIs. It covers accepted inputs and outputs. Minor gaps: no mention of error handling or edge cases (e.g., ambiguous names), but overall complete for a resolution tool.

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

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

Schema coverage is 100%, but description enriches both parameters: for 'value', it specifies accepted formats for company (ticker, CIK, or name) and drug (brand or generic), and for 'type', it details the return fields per type (e.g., ticker + 10-digit CIK + company_name). This adds meaning beyond the schema's basic description.

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

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

The description starts with concrete example queries, clearly stating the tool resolves user-spoken names to canonical/official identifiers. It explicitly lists supported entity types (company, drug) and their outputs, distinguishing the tool from siblings like entity_profile or compare_entities.

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

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

The description instructs 'Use FIRST whenever you have a name but need an ID', providing a clear usage context. It does not explicitly state when not to use it or list alternative tools, but the directive is sufficient given the 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 (readOnly, openWorld, idempotent, non-destructive) already convey safety and behavior. The description adds how it probes each entity, ranks, and returns metrics (score, confidence, signal density), enhancing transparency 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?

Two sentences, front-loaded with purpose, followed by how it works and example usage. No wasted words, every sentence earns its place.

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

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

Given no output schema, the description adequately covers return format (ranked list with score, confidence, signal density). Parameters fully described. Could add more about result ordering or default model behavior, but sufficient for selection.

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

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

Schema coverage is 100%, so baseline is 3. Description adds semantics: 'entities' first entry is subject, rest are competitors; 'models' lists supported models and defaults; '_apiKey' clarifies when required; 'context' provides example disambiguation. Adds value beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check per entity, ranking by score, and surfacing most/least recognized. It contrasts with single-entity sibling ai_visibility_check.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and implies usage context: when comparing multiple brands. Does not explicitly exclude scenarios but the sibling list includes alternatives like ai_visibility_check for single 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is fairly long but front-loads the main purpose. Every sentence adds value, though some redundancy (e.g., 'NPM ecosystem only in v1' is mentioned twice). Still, it's well-structured and informative.

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

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

Despite no output schema, the description thoroughly covers return fields, partial failure behavior, and ecosystem limitations. The tool is complex (multiple data sources), and the description provides complete context for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the composite nature, listing return fields (e.g., bundle_kb_min, advisory_count), and noting default version behavior. This goes beyond schema details.

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

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

The description starts with a clear verb 'Composite ... check in ONE call' and specifies the resource (npm package) and actions (license, advisories, bundle size checks). It distinguishes from siblings by noting 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies when not to use and alternatives for other ecosystems.

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; description adds internal details (BGE-base-en, cosine, 500-char windows, 200K cap with truncation) beyond annotations. No contradictions.

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

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

Four sentences, front-loaded with purpose followed by usage details and technical specs; no wasted words.

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

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

Covers purpose, usage, technical details, and output description (passages with offsets and similarity scores), though could explicitly state the default limit value.

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

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

Schema coverage is 100%; description adds examples for query, clarifies text max length and truncation, and mentions limit default (5), adding value beyond schema.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with specific use cases like SEC 10-K, articles, and distinguishes from sibling tool ask_pipeworx_grounded through pairing mention.

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

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

Explicitly advises when to use ('too big to cram into prompt') and pairs with ask_pipeworx_grounded, giving clear context and alternative.

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

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

The description adds significant behavioral context beyond annotations, including auth requirements (Pipeworx OAuth account), constraints like SMS 10/day cap, webhook auto-disable after 10 fails, and phone verification. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with purpose and requirements. While a bit lengthy, every sentence adds value. Minor redundancy with delivery details also in schema.

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

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

Given the complexity (3 params, 2 required, nested objects, no output schema), the description is comprehensive, covering all types, parameter formats, and delivery options. It does not detail error handling or returned ID format, but these are minor gaps.

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

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

Schema coverage is 100%, but the description adds meaning with examples for each subscription type (e.g., sec_8k items meaning) and detailed explanations for delivery channels (e.g., webhook signing). This goes beyond the schema's brief 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 creates a proactive monitoring subscription and returns a subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying the action and 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 clear context for when to use this tool (to subscribe to live data events) and includes examples for different types. While it does not explicitly state when not to use it, the level of detail helps the agent differentiate from siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: returns live catalog examples, effect of arguments, and the kind of category buckets. No contradictions.

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

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

Description is somewhat lengthy but well-structured, front-loading common user queries. Every sentence adds value, though it could be slightly more compact without losing information.

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

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

For a discovery tool with good annotations and full schema coverage, the description thoroughly explains purpose, usage, parameter details, and typical use cases. No output schema but return behavior is implied (example questions). Complete for the tool's role.

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 has 100% coverage with description for 'topic' parameter. The description adds concrete examples of topic values ('finance', 'pharma', 'betting') and explains that omitting topic provides a cross-category spread, which exceeds the schema's description.

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

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

The description clearly states the tool is the onboarding entry point for an agent that just connected and wants to know what is worth asking, with specific verb 'returns category-bucketed example questions'. It distinguishes itself from siblings by being the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains that calling with no arguments gives full spread, and passing 'topic' focuses the results. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Description discloses that the row is deactivated (not deleted) and historical events remain available, adding behavioral context beyond annotations. Annotations already indicate non-destructive behavior (destructiveHint=false), and the description aligns and expands on it.

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

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

Three sentences effectively cover purpose, ownership, and behavioral nuance with no waste. Front-loaded with core action.

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

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

For a single-required-parameter tool with no output schema, the description provides adequate coverage: purpose, ownership constraint, and post-cancellation behavior.

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

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

Schema description coverage is 100% and the schema already describes the 'id' parameter as a UUID from subscribe. The description does not add meaningful semantic value beyond repeating 'by id'.

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 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific, and it is distinct from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Includes ownership enforcement ('you can only cancel your own subscriptions'), which guides usage context. However, it does not explicitly state when not to use this tool 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 behavioral context beyond annotations: it states the tool returns a verdict, extracted structure, actual value with citation, and percent delta. It also reveals the use of SEC EDGAR + XBRL as sources. Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description is consistent.

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

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

The description is concise yet comprehensive. It starts with trigger phrases, explains usage, scope, and return information in a logical order. Every sentence serves a purpose 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?

For a tool with one required parameter and no output schema, the description fully covers what the tool does, what inputs it accepts, what outputs it returns, and its domain limitations. It is complete enough for an agent to understand and use correctly.

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

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

The schema has 100% coverage with a description for the single 'claim' parameter. The description adds value by providing concrete examples ('Apple's FY2024 revenue was $400 billion') and explaining how the tool processes the claim. This goes beyond the schema's minimal description.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It uses trigger phrases like 'fact check' and 'verify the claim' and distinguishes from siblings by noting it replaces multiple sequential calls.

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

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

The description clearly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims). It does not explicitly mention when not to use or name alternative tools, but the context is sufficiently clear.

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