tle

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 behavioral details: default model (Workers AI), optional Anthropic probe with BYO key, and return structure (per-model score, confidence, signals, raw_response). No contradictions.

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

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

The description is two sentences: first sentence covers core action and default, second sentence covers return and use cases. No unnecessary words; every sentence adds value.

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

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

Given the moderate complexity (multiple models, optional apiKey, no output schema), the description covers purpose, parameters, return format, and usage scenarios. It could mention cost/rate limits but is largely complete.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by explaining the relationship between apiKey and models, providing concrete examples for entity and context, and noting default behavior for models.

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

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

The description uses specific verbs ('probe', 'score') and identifies the resource ('LLMs') and target ('business/brand/product/topic'). It clearly distinguishes from siblings by specifying visibility scoring for any entity, not just competitors.

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

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

The description lists use cases ('AI-marketing audits', 'pre-launch brand checks', 'competitive monitoring') but does not explicitly state when to avoid this tool or mention alternatives among sibling tools like 'scan_competitor_ai_presence'.

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

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

Annotations already provide readOnlyHint and idempotentHint, but description adds important specifics: routes to 3,745 tools, 884 sources, returns pipeworx:// citation URIs. No contradictions.

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

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

Description is informative but somewhat long. It is well-structured, starting with preference statement, then examples. Could be slightly more concise.

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

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

Given the tool's single required parameter and no output schema, the description is thorough: explains purpose, usage, behavioral traits, and return value format. Leaves no gaps.

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

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

Schema description coverage is 100% with each parameter alias explained. Description adds context about natural language input but doesn't significantly enhance parameter understanding 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 routes questions to thousands of authoritative sources for structured data with citations. Distinguishes itself from web search with 'PREFER OVER WEB SEARCH' and lists many domains (SEC filings, FDA data, etc.).

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

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

Explicitly says when to use: for factual questions about current/historical data, and lists query patterns like 'what is', 'look up'. Suggests preference over web search, but doesn't exclude alternatives among 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 read-only, idempotent, non-destructive. The description adds significant behavioral context: costs an extra LLM call, returns explicit refusal reasons, and extracts answers only from tool results. This goes beyond annotations without contradicting them.

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

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

The description is front-loaded with key behavior, uses concise sentences, and every sentence adds value (purpose, routing, cost, usage guidance, refusal reasons). Nothing is wasted.

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

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

For a complex tool involving 3,745 tools and 884 sources, the description explains refusal reasons, return format, and trade-offs. Though no output schema is provided, the description adequately describes 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 all parameters documented as aliases for 'question'. The description only restates that 'question' expects natural language, adding no new meaning. At high coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode for high-stakes reads. It distinguishes from sibling 'ask_pipeworx' by noting the same routing but an extra LLM call and grounded extraction, making the purpose specific and distinct.

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 (answers that will be quoted, cited, or acted on, where invention is unacceptable) and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), providing clear usage boundaries.

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

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

The descriptions go far beyond the annotations (readOnlyHint, openWorldHint, etc.). It details the resolution process (market match confidence, parent event extraction), safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and response shapes (market, analysis, evidence). It also explains resolution-rule risk and news fallback behavior, providing deep behavioral context.

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

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

The description is lengthy but every sentence adds value, covering purpose, input, processing, safety, and response details. It is front-loaded with the primary action and use cases. While it could be slightly more structured (e.g., sections), the density of information justifies its length. It is concise for the complexity it addresses.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers input handling (slug, URL, text), processing steps (market resolution, classification, fan-out, parent event extraction), response structure (market, analysis, evidence), safety checks (low confidence, closed markets, wide spreads, resolution-rule risk), and edge cases (news fallback). No critical gap exists for an AI agent to safely and effectively use this tool.

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

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

The input schema has 100% coverage with descriptions for all three parameters. The description further enriches the parameter semantics: for 'market' it gives examples of slugs, URLs, and question text; for 'depth' it explains 'quick' vs 'thorough'; for 'include_raw' it details when to pass 'true' (recompute deltas, cite observations) and the impact on response size. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the core action (research a bet) and the resource (Polymarket via Pipeworx). The provided use cases ('should I bet on X', etc.) and input examples further clarify its role, distinguishing it from sibling tools like polymarket_arbitrage or 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 explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context. While it does not directly list alternatives to avoid, the surrounding sibling tool names and the detailed use case phrasing indirectly provide differentiation. The guidance is clear but lacks 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=true and idempotentHint=true. The description adds valuable behavioral context: off-calendar fiscal year handling, citation URIs, and efficiency gains. 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 somewhat lengthy but each sentence adds value. It starts with common query phrasings, then specifies data sources, then explains output and alternatives. Could be slightly more structured, but 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?

No output schema is provided, so the description must explain return format. It mentions 'paired data + pipeworx:// citation URIs per entity' but does not detail the structure of 'paired data' or example output. For a tool that replaces 8-15 lookups, more specifics would aid agent understanding.

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 meaning by explaining the enum values ('company' vs 'drug'), providing usage examples (tickers/CIKs for companies, drug names), and clarifying valid entity counts (2-5). 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 compares 2-5 companies or drugs side-by-side, with specific verbs and resources (SEC EDGAR/XBRL for companies, FAERS for drugs). It contrasts with sequential lookups and provides example natural language queries, leaving no ambiguity.

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

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

Explicitly prefers this tool over sequential single-pack lookups and gives concrete context for when to use. It clarifies data sources and handling of fiscal years. However, it does not mention when NOT to use it or suggest alternatives for single entity queries.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds rich behavioral details: returns structured findings with verbatim evidence, confidence, source, fetched_at, citation, gaps array, and states that facts are pre-verified and never invented. Expected duration (15-60s) is also noted. No contradiction.

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

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

The description is relatively long but every sentence adds value, front-loading the core function. Could be slightly more concise, but structure is logical and efficient.

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

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

Despite no output schema, the description thoroughly explains the return structure (findings packet with evidence, confidence, source, citations, gaps). It covers prerequisites, alternatives, timing, and even warns about paid tier. Complete guidance for a complex 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 baseline 3. The description adds value by explaining the depth enum values (quick=3, standard=5 default, thorough=8 paid) and clarifying that the question can be broad/multi-part. This provides meaningful context beyond the schema definitions.

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

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

The description clearly states the tool's function: grounded multi-source research in one call, with decomposition into sub-questions and parallel routing. It explicitly contrasts with sibling ask_pipeworx, distinguishing it as the appropriate choice for broad or multi-part questions.

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 (broad/multi-part questions) and when not to (single lookups, for which ask_pipeworx is recommended). Also mentions prerequisites: Pipeworx account and paid plan for depth:'thorough'.

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

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

Annotations already indicate read-only and idempotent. Description adds that results include full schemas with examples and are ready to call directly, which goes beyond annotation info.

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

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

Description is front-loaded with purpose and efficient. Slightly lengthy due to domain list, but that list serves as helpful context without being excessive.

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 description adequately explains return format (top-N tools with schemas) and notes results are call-ready, covering essential 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%, so baseline 3. Description adds value by explaining the purpose of 'query' parameter with examples and listing aliases, making it more intuitive.

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

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

The description clearly states the verb 'find' and resource 'tools', listing many specific domains. It distinguishes from sibling tools by focusing on tool discovery vs. data queries.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. Does not include when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the exact data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), the return fields (filings with URIs, fundamentals with specific metrics, patent soft-fail note, etc.), and the limitation on name inputs. This provides a rich behavioral picture 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 relatively long but packs essential information: sample intents, data sources, return fields, and usage notes. It is front-loaded with examples and structured logically. Minor verbosity could be trimmed, but the density of useful information makes it efficient.

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

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

Given the complexity and absence of an output schema, the description provides a thorough list of return components (cik, filings with URIs, fundamentals with metrics, patents, news, LEI). However, it does not specify the exact structure or ordering of the output. The openWorldHint annotation helps, but a bit more detail on output shape 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% with descriptions for both 'type' and 'value'. The description adds context by noting that names are not supported and suggesting resolve_entity as an alternative. This extra guidance justifies a score above the baseline of 3, though it does not elaborate on the format of value further.

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: producing a full cross-source profile of a US public company in one call. It lists example user intents like 'Tell me about X' and specifies the output includes CIK, filings, fundamentals, patents, news, and LEI. This differentiates it from sibling tools like compare_entities or deep_research, which are more granular or analytical.

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

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

The description explicitly says to prefer this tool over chaining multiple single-source lookups for holistic views. It also warns that names are not supported and directs users to resolve_entity when only a name is available. This provides clear when-to and when-not-to-use guidance.

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

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

Descriptors state 'Delete' which aligns with destructiveHint=true. Adds context about why deletion is needed (stale context, sensitive data). 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?

Two sentences, front-loaded with the core action. No unnecessary words. Every sentence adds value: first states purpose, second gives usage guidance.

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

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

Tool is simple with one parameter and no output schema. Description covers purpose, usage context, and hints at side effects. Complete for effective use.

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

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

Schema covers the single 'key' parameter fully (100% coverage). Description does not add additional meaning beyond the schema parameter description, so baseline score of 3 applies.

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

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

Clear verb (delete) and resource (memory by key). Description states 'Delete a previously stored memory by key.' It distinguishes from siblings by referencing 'remember' and 'recall' as paired tools.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data...' Also mentions pairing with remember and recall, providing alternative context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds transparency about its internal process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains what happens beyond just generating, but could mention potential fetch delays or errors. 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 reasonably concise given the detail needed. It front-loads the purpose and output format, then lists use cases. One sentence could be trimmed (e.g., 'ready to drop at site-root/llms.txt' is clear but slightly redundant with previous sentence). Overall efficient.

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

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

Given no output schema, the description explains the return value as 'a single text blob ready to drop at site-root/llms.txt.' It covers the tool's behavior enough for an agent to understand input and output. The context signals (2 params, 100% schema coverage, no enums) are well addressed. Missing explicit mention of error handling or URL validation, but still adequate.

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

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

Schema coverage is 100% for both parameters ('url' and 'max_links'). The description adds context: for 'url' it clarifies 'Full URL of the site to summarize' with an example, and for 'max_links' it explains 'Maximum number of link entries to include (default 25, max 50).' This adds meaningful guidance beyond the schema descriptions.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file'), and clearly states the tool's purpose: producing a standard llms.txt for AI crawlers. It distinguishes from sibling tools by specifying the output format and intended use cases (getting a client's site indexed, drafting for own project, auditing competitors), which differentiates it from other tools like 'scan_competitor_ai_presence'.

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

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

The description lists explicit use cases ('Useful for:...') and implies when to use the tool (when an llms.txt is needed). However, it does not explicitly state when not to use it or provide alternatives. The sibling tools are many, but the description doesn't directly compare, so there is some room for improvement.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying the return fields (satellite name, epoch date, TLE lines), which is not in the annotations. 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?

Two sentences convey the core action and return information with no filler. Front-loaded with the action verb 'Fetch', making it efficient for an agent 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?

The tool is simple (1 required param, no nested objects) and has an output schema. The description covers the main purpose and return content, sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% and the description restates the purpose of the norad_id parameter. The description adds mild context (examples) but no new semantic meaning beyond what the schema 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 precisely states the tool fetches a TLE set for a satellite by NORAD ID, using specific verbs and resource terms. It distinguishes from sibling search_satellites by focusing on a single satellite retrieval.

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

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

While the description implies use when a specific satellite's TLE is needed, it does not explicitly state when not to use it or compare to alternatives. The sibling list provides implicit context but not 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?

Description adds context beyond annotations: specifies sorting order and scope (recently launched/updated). Annotations already declare read-only, idempotent, non-destructive. No contradiction. The description enriches the behavioral profile.

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, 14 words, front-loaded with the action. Every word is necessary and contributes to understanding. No fluff or redundancies.

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

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

For a simple, one-parameter list tool with an output schema, the description is complete. It covers purpose, scope, ordering, and implicitly the output format. No gaps given the low complexity.

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

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

Input schema has 1 parameter (limit) with full coverage (100%). Description does not add additional meaning to the parameter beyond the schema's description. Baseline 3 is appropriate as the schema already documents the parameter.

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

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

Description clearly states verb 'list', resource 'satellites', scope 'most recently launched or updated', and sorting 'by epoch date descending'. It distinguishes from siblings like search_satellites which is for searching/filtering.

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

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

No explicit guidance on when to use vs alternatives. While the purpose is clear, there is no mention of when to prefer this tool over search_satellites or get_tle. It's adequate but lacks explicit use case differentiation.

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, destructiveHint. Description adds return field details but not much behavioral 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?

Two sentences: first states action and output, second gives usage guidance. No verbose language.

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 strong annotations, description covers purpose, output, and usage. No missing critical information.

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 description for include_inactive. Description implies active-only default, adding little 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?

Specifies verb 'list' and resource 'the caller's active subscriptions', and lists returned fields. Clearly distinguishes from siblings subscribe/unsubscribe.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides context for using before adding subscriptions.

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

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

Annotations are all false, so the description carries the burden. It discloses that the feedback is read by the team daily, affects roadmap, is rate-limited to 5 per identifier per day, and is free without consuming tool-call quota. However, it does not specify whether the action is synchronous or what the immediate response will be, slightly reducing transparency.

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 yet informative, with each sentence serving a distinct purpose: purpose, usage triggers, formatting advice, team practices, and limits. It is front-loaded with the most critical information and contains no redundant or off-topic content.

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

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

Given no output schema, the description adequately covers the tool's behavior and how to provide feedback. It explains the feedback lifecycle (team reviews, roadmap impact) and usage constraints. However, it could mention the expected return value (e.g., a confirmation message) to fully set expectations.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds value by advising to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which guides correct usage of the context and message fields. This goes beyond the schema's own 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 starts with a specific verb-resource pair 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature/data_gap, praise) which clearly differentiates it from sibling tools like ask_pipeworx or discover_tools. This makes the tool's purpose unmistakable.

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

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

Explicit conditions for use are given: when a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or for praise. It also provides negative guidance: 'don't paste the end-user's prompt.' Additional constraints like rate limiting and quota usage are stated, leaving no ambiguity about when and how to invoke the tool.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description adds caching behavior (5min-1h), data source (CF analytics), and privacy (no PII). 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: first sentence defines output, then bulleted use cases, then additional context. No redundant sentences; every element 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?

Despite no output schema, the description covers what the tool returns (top tools, packs, volume), why to use it, data derivation, and caching. Complete for a simple tool with rich annotations.

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 with 100% description. Description adds practical usage advice on window selection (shorter for hot trends, longer for steady-state), enhancing understanding 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?

The description clearly states the tool returns trending tools/packs and call volume, with three specific use cases. It distinguishes itself from sibling tools like discover_tools by focusing on real-time aggregated call 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?

The description provides three explicit use cases that guide when to use the tool, but does not contrast with alternatives or state when not to use it.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behaviors: that calling with no args fails, the checks performed (monotonicity, partition sum, Jaccard similarity filter, placeholder filter), the fill check against CLOB depth, and criteria for trading. This is comprehensive and adds significant value.

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 and dense, containing many details in paragraph form. While thorough, it could be more concise and better structured (e.g., bullet points for modes and checks). Longer than necessary for an AI agent to parse quickly.

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 format: opportunities[] with fields (gap_pp, suggested_trade, etc.) and partition_check with details. It also covers edge cases (fill check, low similarity, placeholder filter) and trade recommendations. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'event', it gives examples and confirms full URLs accepted; for 'topic', it explains how it searches related events. It also elaborates on the modes and the underlying logic, which goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with examples and explains when to use each. It also differentiates from sibling tools by mentioning custom sizing via polymarket_fill_risk.

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 usage guidelines: it requires one of 'event' or 'topic', explains when to use each mode, and notes that cros-event mode catches patterns missed by single-event. It also suggests using polymarket_fill_risk for custom sizing. However, it does not explicitly contrast with other sibling tools like polymarket_edges.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description richly discloses internal model families, caching behavior, response structure (by_segment, diagnostics), and exclusions (Fed bets). This adds substantial context 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 long but efficiently structured with segments and knobs. The first sentence states the purpose. Every sentence adds value, though it is verbose; still 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 the tool's complexity (9 parameters, 3 segments, diagnostics) and absence of output schema, the description covers input filters, response format, caching, and edge cases (Fed bets excluded). An agent has enough 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?

All 9 parameters are described in the schema, so baseline is 3. The description adds meaning with explanations of defaults, behavioral effects (e.g., 'min_kelly skips opportunities too small to bet sensibly'), and real-world context (e.g., slippage on Polymarket). This goes beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, explicitly calling out its purpose as 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by mentioning Pipeworx 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?

The description provides clear context for when to use, especially for daily betting discovery, and details the three segments and filter knobs. It does not explicitly state when not to use but implies the scope, and alternatives are not directly named, though sibling tools exist.

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 safe, read-only, idempotent operation. The description adds significant behavioral context: history depth bound by 60-day TTL, decay computed from daily closes (not intraday), snapshot gaps explained, and response structure covering expired opportunities and median lifespan as a 'competition clock'. 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 with clear sections (RESPONSE, LIMITS) and provides essential details without excessive verbosity. Some minor redundancy (e.g., explaining decay computation twice) could be tightened, but overall it is efficient and front-loaded with key purpose.

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

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

Given the absence of an output schema, the description thoroughly documents the response fields: tracked[], expired[], snapshot_dates[]. It also covers limitations (60-day TTL, decay from daily closes) and best practices (median lifespan as competition clock). This is exceptionally complete for a tool with 2 optional parameters and 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%, but the description adds meaning beyond the schema: explains 'days' default and max (14 and 30) and clamps behavior, 'window' with explicit examples ('24hr', '1wk', '1mo') and default '1wk'. The description clarifies that these are snapshot families, enriching the schema definition.

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 tracks edge persistence and decay from daily snapshots, distinguishing a fresh wide edge from a stale one. It explicitly contrasts with polymarket_edges sibling by focusing on time-series behavior. The verb+resource combination is specific: 'edge persistence and decay telemetry'.

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 clear use case: distinguishing edges based on age. It implies that polymarket_edges provides current edges, but does not explicitly name alternatives or state when not to use. However, the context is sufficient for an agent to infer appropriate usage.

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=true, idempotentHint=true) indicate it's a safe check; description adds details about walking the ladder, return fields (slippage_pp, verdict), and warns about forced directional risk on partial fills, fully consistent with annotations.

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

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

Dense and informative, but slightly verbose (200+ words) with a bullet-like style; front-loaded key purpose but could be more streamlined.

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 lack of output schema, description comprehensively lists return fields (top_of_book, vwap, slippage, shares_filled, verdict, etc.) and addresses edge cases (thin legs, forced directional risk), making it self-contained for agent decisions.

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; description adds significant meaning: explains mode selection (market vs event), defaults (size_usd=1000), interpretation per mode (spend vs target proceeds vs settlement notional), and return structure not in 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 precisely states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, clearly differentiating from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains consequences of not using it (partial basket fills convert arb into unhedged directional position).

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds extensive behavioral context: it explains compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the fact that real spreads are rare. 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 detailed but somewhat verbose (over 300 words). It is well-structured with clear sections for modes, response, and safety fields, but could be more concise for quicker consumption.

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 and the absence of an output schema, the description thoroughly explains the response structure: legs, spread[], top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_* counters. It covers edge cases and what each field means.

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 meaning by listing the 10 pre-mapped topics, explaining that explicit tickers override the topic side, and providing examples. This adds value beyond the schema descriptions.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparisons.

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

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

It explicitly describes two usage modes (topic shortcuts vs. explicit tickers) and provides guidance on when spreads are valid. It warns that most pre-mapped topics currently return compatibility warnings, advising that pre-mapped does not equal tradeable.

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

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

Annotations already convey readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping to an identifier and the dual behavior (retrieve vs. list). 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 concise and front-loaded with the primary action. Four sentences cover purpose, usage, scoping, and pairing without extraneous information.

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

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

For a tool with one optional parameter and no output schema, the description fully covers behavior: retrieval, listing, scoping, and integration with sibling tools. 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 coverage is 100% and the description explains the optional 'key' parameter: omit to list keys, provide to retrieve. It gives concrete examples of key values (ticker, address, notes), adding meaning beyond the schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs 'retrieve' and 'list' with the resource 'memories'. It distinguishes from siblings by explicitly naming paired tools '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 clear context for when to use the tool: to look up previously stored context like tickers or addresses. It mentions scoping and pairing with remember/forget, though it doesn't 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?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it explains that setting 'mark_read:true' flags events as read so subsequent calls return only newer ones, and it mentions that polling works fine. These details go beyond the annotations and help the agent understand side effects and usage patterns.

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

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

The description is three sentences totaling about 70 words. The first sentence immediately states the core purpose. Subsequent sentences add essential details without redundancy. No filler or fluff. 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?

Despite the absence of an output schema, the description clearly explains that returned events carry 'source, citation_uri (pipeworx:// when available), and the raw event payload'. It covers all parameters, explains behavior of mark_read, and provides an alternative access method. For a read-only polling tool with 0 required parameters, this is complete and actionable.

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

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

Schema coverage is 100% for 5 parameters. The description adds value by clarifying parameter semantics: it gives an example for 'type' (e.g., 'sec_8k'), explains 'since' expects an ISO timestamp, and describes the effect of 'mark_read' on subsequent calls. It does not repeat schema descriptions but provides practical usage context. Baseline 3 is elevated to 4 due to this added clarity.

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

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

The description starts with 'Pull fired events from your subscription feed' which is a specific verb and resource. It clearly distinguishes from siblings like 'list_recent' and 'recent_changes' by focusing on subscription feed alerts. The details about return fields (source, citation_uri, payload) make 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 guidance on when to use the tool: it explains filtering options (type, since, mark_read, unread_only) and states that 'polls work fine'. It also mentions an alternative access method ('same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'), which helps the agent decide between this tool and direct API. However, it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: fan-out to multiple sources, GDELT→GNews fallback, patents soft-fail. No contradictions; adds value 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 relatively long but well-structured with examples and clear separation of sections. Every sentence adds value, though could be slightly tightened.

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 complexity (multiple sources, fallbacks, flexible parameters) and no output schema, the description thoroughly explains return format (structured changes grouped by source with counts and URIs) and patent situation.

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. Description adds meaning: explains 'since' accepts ISO date or relative shorthand with examples, 'value' accepts ticker or CIK, and 'type' currently only supports 'company'.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, covering SEC filings, news, and patents. It distinguishes from sibling tool entity_profile by noting the static profile use case.

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 examples ("What's new with X") and when to use entity_profile instead for a static profile without time window. Also explains fan-out behavior and fallbacks.

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 context beyond annotations: key-value scoped by identifier, persistence duration (24h for anonymous, persistent for authenticated), and idempotency implied. Does not contradict annotations.

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

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

Four sentences, front-loaded with purpose, then usage, then technical details, then sibling references. No wasted words, well-structured.

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

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

For a simple write tool with no output schema, the description covers purpose, usage, persistence, scoping, and sibling tools. Completely sufficient for an agent.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining scoping and providing usage examples, enhancing understanding 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 the tool saves data for reuse across sessions, with specific examples like 'resolved ticker' or 'user preference'. It clearly distinguishes from siblings 'recall' and 'forget'.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' and directs to pair with recall/forget, indicating alternatives. Tells when to use and what the tool is for.

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, destructiveHint) already declare safety. The description adds that each call cascades through several lookup endpoints internally, which provides useful behavioral context beyond annotations. No contradiction.

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

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

The description is front-loaded with examples and a clear purpose. It is moderately lengthy but every sentence adds value. Could be slightly more concise, but the structure is logical 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 complexity (two entity types, internal cascade), the description covers purpose, inputs, examples, and behavioral details comprehensively. No output schema exists, but the return values are adequately described within the type-specific sections.

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 enriches both parameters with examples and specific identifier formats (e.g., ticker 'AAPL', CIK '0000320193'). This adds substantial meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples like 'What's the ticker for…'. It distinguishes itself from sibling tools by focusing on name-to-ID resolution, a unique function among sibling tools.

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

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

Explicit guidance to 'Use FIRST whenever you have a name but need an ID.' It also mentions replacing manual lookups, indicating when it is beneficial. However, it lacks explicit when-not-to-use or alternatives, but the context is sufficient for basic usage decisions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. The description adds operational detail (probes with ai_visibility_check, returns ranked list with metrics) and does not contradict annotations.

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

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

Three sentences, each purposeful: purpose, mechanism, usage example with return info. No wasted words, front-loaded with the core action.

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

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

For a tool with no output schema, the description adequately covers return structure (score, confidence, signal density). It also explains when to use it and how it works, 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%, so parameters are already documented. The description adds valuable context: the first entity is treated as the 'subject', and context parameter is exemplified. This semantic grouping is beyond what the schema 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check as a sub-probe and returning a ranked list. It distinguishes from sibling tools like single-entity ai_visibility_check by emphasizing the comparative aspect.

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 clear use case (competitive AI-marketing audits) with an example question, implying when to use it. It does not explicitly exclude scenarios or mention alternatives, but the context is sufficiently clear for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint true. Description adds valuable behavioral context: fans out across services, partial degradation, timing of first measurement, and sources_failed field. Could mention what happens if package not found, but overall good.

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

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

Description is a single dense paragraph but front-loads purpose, then provides usage guidelines, edge cases, and return details. Every sentence contributes value. Could be broken into sections for readability, but 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 no output schema, description fully explains return format (summary block fields, per-advisory detail, links, alternatives). Also covers error handling (sources_failed) and timeouts. All necessary context for a two-parameter tool is present.

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

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

Schema coverage is 100%, so baseline is 3. Description restates that version defaults to latest and scoped packages are accepted, but these are already in schema. No new semantic depth 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?

The description clearly states the tool's purpose: a composite check for npm packages pulling from deps.dev and bundlephobia. It uses a specific verb ('check') and resource ('npm package'), and the scope is well-defined (NPM only). It distinguishes from siblings by naming alternatives (deps.dev:version for other ecosystems).

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

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

Explicitly tells when to use: when agent asks about safety, popularity, smallness, or cost of adding an npm package. Also specifies when not to use: for non-npm ecosystems, direct deps.dev calls are advised. Provides nuance about partial failures and timing (5-30s for bundlephobia).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds return fields (NORAD IDs, TLE data) which is useful. 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?

Single sentence, no redundant words. Every part adds value: action, resource, input hint, output summary.

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

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

With 2 simple parameters, annotations, and output schema (not shown), the description covers core functionality. Could mention ordering or pagination, but not required for basic use.

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

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

Schema coverage is 100% and schema already documents both parameters. Description reiterates 'by name or keyword' but adds no extra semantic detail 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?

The description clearly states the verb 'Search', resource 'satellites', and specifies return of NORAD IDs and TLE data. It distinguishes itself from sibling tools, none of which are satellite search.

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

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

The description implies when to use: when needing satellite info by name/keyword. No explicit alternatives or when-not, but sibling tools lack similar functionality, so guidance is adequate.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant technical context: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity method (cosine), and a 200K character limit with truncation flagging. 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 a single, dense paragraph but front-loaded with the core purpose. Every sentence adds value: use case, return format, pairing advice, technical details, and constraints. It could be slightly more structured (e.g., bullet points) but remains very efficient.

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

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

Given the annotations (readOnlyHint, etc.) and 100% schema coverage, the description provides rich context: use case, returns (passages, offsets, scores), technical method, and constraints. No output schema exists, but the description mentions return fields. Minor gaps (e.g., error handling, empty results) but sufficient for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: for 'query' it gives natural-language examples (e.g., 'supply-chain risk'), for 'limit' it specifies range and default, and it explains the underlying retrieval mechanism (embeddings, sliding window), which helps the agent understand parameter semantics beyond schema types.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record', provides concrete examples (SEC 10-K, article), and specifies what it returns (top-N passages with offsets and similarity scores). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It also suggests a complementary tool (ask_pipeworx_grounded), providing context on alternative workflows. Exclusions are not explicitly stated but the guidance is clear enough.

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

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

The description adds behavioral details beyond annotations: it explains that OAuth account is required, SMS has a 10/day cap, webhook auto-disables after 10 failures, and returns subscription ID. No contradiction with annotations; idempotentHint is consistent with creating subscriptions.

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

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

The description is information-dense but well-structured: it front-loads the core purpose and requirements, then details types and delivery channels. Some redundancy could be trimmed, but it remains focused.

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 requirements, type-specific parameters, delivery options with constraints, and the return value. For a 3-param tool with no output schema, it provides sufficient 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 coverage is 100% with well-described parameters. The description adds concrete examples and delivery constraints, but does not significantly surpass the schema's own 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 that the tool creates a proactive monitoring subscription to a live-data event stream, specifies that it returns a subscription ID, and provides examples of supported types, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use the tool (requires Pipeworx OAuth account, not for anonymous/BYO), lists supported subscription types with examples, and mentions delivery channels, but does not explicitly compare with alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns category-bucketed examples, no arguments for full spread, optional topic. No contradiction.

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

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

Description is a single block that front-loads common user questions, then explains output and usage. Some minor redundancy but overall efficient and well-structured.

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

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

For a simple tool with 1 optional param and no output schema, the description covers purpose, parameters, output format, and usage instructions completely.

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

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

Schema already describes the 'topic' parameter. Description adds that omitting gives full spread and lists possible values (finance, pharma, etc.). Provides useful context 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?

The description clearly states that the tool returns category-bucketed example questions with exact tool+argument shapes, distinguishing it from siblings like ask_pipeworx which is a meta-tool for asking questions 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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. While it doesn't state when not to use, the context is clear and helpful.

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 value beyond annotations by explaining that 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies the non-destructive nature, consistent with destructiveHint=false, and provides additional context about data preservation.

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

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

The description is concise with three sentences, each serving a distinct purpose: stating the action, enforcing ownership, and explaining the effect. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership and effect adequately. It could mention success/error behavior but is sufficient for agents to use correctly.

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

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

The schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' with 100% coverage. The description does not add new semantic information beyond what is in the schema, so a baseline score of 3 is appropriate.

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

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

The description explicitly states 'Cancel a subscription by id,' clearly identifying the action (cancel) and resource (subscription). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying that it cancels an existing subscription.

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 clear guideline with 'Ownership is enforced — you can only cancel your own subscriptions,' indicating when the tool can be used. However, it does not explicitly mention alternative tools for scenarios like canceling others' subscriptions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: returns a verdict with five possible values, extracted structured form, actual value with citation, and percent delta. It also notes it replaces multiple calls, providing clear transparency.

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 examples up front, clear usage guidance, domain scope, and return value details. While somewhat verbose, every sentence adds value, and the structure aids 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?

Given no output schema, the description fully explains return values (verdict, structured form, actual value, citation, delta). The single parameter is well-documented, and the tool's complexity is adequately covered.

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?

There is only one parameter with a schema description that already provides examples. The tool description adds no new semantic information beyond the schema. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it verifies factual claims against authoritative sources, specifically company-financial claims for US public companies. It provides natural-language examples and distinguishes itself as a composite tool replacing 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 explicitly says to use it when the agent needs to check factual accuracy and specifies the domain (company-financial claims via SEC EDGAR + XBRL). It does not explicitly mention when not to use or alternatives, but the domain restriction is clear.

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