Nrel

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: the default model is free, Anthropic probing requires a BYO key (cost implication), and returns 'per-model {score, confidence, signals, raw_response} + a combined view.' This adds useful 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?

Three sentences: first front-loads purpose and output, second covers key parameters and cost, third lists return structure and use cases. Every sentence earns its place with zero waste.

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

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

No output schema, but description adequately explains return format (per-model objects and combined view). Covers default behavior, optional parameters, and use cases. For a tool with 4 parameters and moderate complexity, this is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description enhances parameter understanding: clarifies 'models' values ('workers-ai' free default, 'anthropic' needs key), explains '_apiKey' is passed straight through, and gives examples for 'context.' This adds meaning 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: 'probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb 'probe', the resource 'one or more LLMs', and the output format. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' which focuses on competitors, while this tool is for general visibility.

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

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

Provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Explains when to use the free default model and when to provide an API key for Anthropic. However, it does not explicitly state when to avoid using this tool relative to siblings, which are listed but not compared.

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, idempotent, open-world. Description adds context: routes to 4,396 tools, returns structured answers with citation URIs, works on all tiers. 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 front-loaded with key purpose and guidance, then detailed examples. Slightly long but every part earns its place; no redundancy.

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

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

Given no output schema and 6 parameters, description covers purpose, usage, alternatives, examples, and hints at return format (structured answer with citation URIs). Fully 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% with parameter descriptions. Description adds value by providing usage examples and clarifying that question accepts multiple aliases, which is also in schema but reinforced.

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 answers factual questions using authoritative structured data, lists many domains, and distinguishes from siblings like ask_pipeworx_grounded and deep_research, with specific verb+resource.

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

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

Explicitly advises to 'PREFER OVER WEB SEARCH' and gives when-to-use vs alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad queries). Provides examples of query types.

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

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

Discloses that it extracts answers only from tool results, provides explicit refusal reasons, and costs one extra LLM call. Annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and complemented by behavioral details.

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 slightly long but well-structured, front-loaded with the key purpose. Every sentence adds value, though could be trimmed slightly without losing meaning.

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

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

Given the complexity of the tool (grounded QA with refusal logic), the description covers purpose, mechanism, return format, usage guidance, and cost trade-off. No output schema needed as return structure is described in detail.

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

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

Schema covers all 6 parameters with descriptions (100% coverage). Description adds value by grouping aliases (q, text, input, query, prompt) as interchangeable with 'question', simplifying understanding.

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

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

The description clearly identifies it as a hallucination-resistant, grounded answer mode for high-stakes reads, differentiating it from its sibling 'ask_pipeworx' by emphasizing verbatim evidence extraction and refusal on insufficient 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?

Explicitly states when to use (when answers will be quoted/cited/acted on, high-stakes domains) and when not to (prefer 'ask_pipeworx' for casual lookups due to extra cost).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by detailing resolution logic (market_match_confidence, low-confidence short-circuit), fan-out behavior (category-specific data packs), safety mechanisms (closed/dead markets, wide spreads), and resolution-rule risk. It also explains response shapes and blocking conditions. This level of detail well exceeds what annotations provide, and no contradictions are present.

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 (multiple paragraphs, many examples). While comprehensive, it could be more concise. For instance, the fan-out examples and resolution-rule risk paragraphs are detailed but somewhat verbose. The essential purpose is front-loaded, but some users may find the density excessive. A tighter structure would improve scannability.

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

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

Given the tool's complexity (multi-source fan-out, multiple response shapes, edge cases), the description is remarkably complete. With no output schema, it fully explains return fields: market_match confidence, parent_event extraction, news fallback fields, safety checks, and resolution-rule risk. Every aspect is covered, making the tool usable without additional documentation.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema. It explains the semantics of 'depth' (quick vs thorough), shows examples for 'market' input, and describes 'include_raw' with context on response size (20KB vs 50-500KB). The description makes the parameters meaningful and actionable, which is especially helpful given the tool's complexity.

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

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

The description opens with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output shape (evidence packet + comparison). This distinguishes it from sibling tools like 'polymarket_edges' or 'deep_research' by focusing on single-bet research with fan-out. The purpose is unambiguous and specific.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and fan-out examples, giving context for when to invoke. However, it does not explicitly state when NOT to use this tool (e.g., for non-Polymarket bets or general questions) or name direct alternatives, which would be helpful. The guidance is strong but lacks exclusionary clarity.

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, idempotentHint, etc. The description adds significant behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citations. No contradiction with annotations.

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

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

Description is informative but not overly verbose. Each sentence adds value: trigger phrases, usage guidelines, behavioral details. Front-loads key info. Could be slightly trimmed but overall well-structured.

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

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

Given no output schema, the description explains the return format (paired data + citations) and key behaviors (sorting, fiscal year handling). Covers both entity types comprehensively. No gaps for a tool with this complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful context: explains what data each type pulls and gives example values. This enhances understanding beyond the schema alone.

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

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

Clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. Specifies data sources and distinguishes from sequential lookups. The verb 'compare' and resource 'entities' are well-defined with examples.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases. Gives context for when to use (comparison of multiple entities) and implies alternatives (single lookups). Clear guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds behavioral details: returns gaps[] for unanswered facets, never invents, 15-60s latency, and account requirement. 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 thorough and front-loaded with critical info (account requirement, alternative). While slightly verbose, every sentence adds value; minor redundancy in listing data sources and tool count.

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 (findings packet with evidence, confidence, source, fetched_at, citation gaps[]). Covers prerequisites, alternatives, and limitations.

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

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

Schema coverage is 100%; description adds meaning beyond schema: explains depth enum values (quick=3, standard=5, thorough=8) and notes paid plan for thorough; question described as natural language and multi-part suitable.

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 ('grounded multi-source research') and resource ('Pipeworx's 1102 structured data sources'), distinguishing from siblings like ask_pipeworx (single lookup) and explicitly contrasting with open-web 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?

Explicitly states when to use (broad/multi-part questions over structured data), when not (breaking/current news), and provides alternatives ('prefer ask_pipeworx'). Also notes account requirement and paid tier for 'thorough' depth.

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, etc.), the description adds that the tool returns top-N relevant tools with full schemas and examples, and that results are ready to call directly. It also implies it's a safe, exploratory tool by suggesting it be called first.

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 purpose, then usage, then output details, then a directive. It is about 140 words with no filler, and every sentence adds value. It is a model of conciseness.

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 explains the return format (names, descriptions, schemas with examples) and the usage order (call first). It lacks details on error handling or ranking, but for a discovery tool of moderate complexity, it is mostly complete.

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

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

Schema coverage is 100%, so each parameter is already well-described. The description adds overall context but does not significantly enhance parameter understanding beyond what the schema provides. 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 that the tool finds tools by describing data or task, lists specific domains, and clarifies that it returns ready-to-call results. This clearly distinguishes it from sibling tools by positioning it as the first call for discovery.

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

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

The description says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It provides clear context for when to use it, though it could explicitly mention when not to use it (e.g., if you already know the specific 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 (readOnlyHint, idempotentHint), the description details parallel fan-out across SEC EDGAR, XBRL, USPTO, GDELT, GLEIF, and specifies return fields (cik, company_name, filings, fundamentals, patents, news, LEI). It also discloses the patent soft-failure due to API sunset.

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 and front-loaded with examples, but the technical return structure is somewhat dense and could be better organized (e.g., bullet points). It is not overly verbose but loses some scannability due to length.

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

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

Without an output schema, the description fully compensates by enumerating all return fields (cik, company_name, recent_filings with URIs, fundamentals with specific KPIs, patents, news via fallback, LEI) and noting limitations like USPTO sunset. This provides complete guidance 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%, so baseline is 3. The description adds value by specifying that 'value' must be a ticker or zero-padded CIK, and that names are not supported (recommending 'resolve_entity' instead). This provides practical guidance beyond the schema.

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

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

The description uses specific verbs like 'profile,' 'brief me,' 'research' and provides example queries. It clearly identifies the tool as a holistic multi-source profile for US public companies, distinguishing it from siblings like 'resolve_entity' (only resolution) and 'compare_entities' (comparison).

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises to use 'resolve_entity' when only a name is available. It also notes that names are not supported as input, guiding the agent away from invalid 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 already indicate destructiveHint=true and idempotentHint=true. The description adds context about the nature of the operation (delete) and appropriate use cases, but does not elaborate on specific behavioral details beyond the annotations. It is consistent with 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 two sentences, front-loaded with the primary action, and every sentence adds value. No unnecessary text.

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

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

For a simple single-parameter destructive tool with no output schema and clear annotations, the description provides all necessary context: purpose, when to use, and relationship to sibling tools. It is complete.

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

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

Schema coverage is 100% for the single parameter 'key'. The tool description does not add any additional meaning beyond what the schema already provides (schema description: 'Memory key to delete'). 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?

The description clearly states the verb 'delete' and the resource 'previously stored memory by key', making the purpose unambiguous. It also distinguishes from sibling tools 'remember' and 'recall' by implying it is the complementary operation.

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

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

The description explicitly lists three scenarios for use: context stale, task done, or clearing sensitive data. It also mentions pairing with 'remember' and 'recall', providing excellent guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral details: fetches page, extracts title/description/key links, outputs standard markdown. No contradictions.

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

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

Two sentences plus a concise list of use cases. No wasted words, highly efficient, front-loaded with purpose.

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

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

With no output schema, the description adequately explains the output as a single text blob. Parameters are fully covered, annotations provide behavioral hints, and the description is complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal extra semantic value, repeating 'Full URL' and default/max for max_links. 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 generates a production-ready llms.txt file for any URL, specifies the verb 'generate' and the resource 'llms.txt', and distinguishes it from siblings like 'scan_competitor_ai_presence' by focusing on a specific output format and use cases.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It provides clear context but does not explicitly state when not to use 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by detailing the response fields and the behavior of the include_inactive parameter, which goes 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?

Two concise sentences that front-load the purpose and immediately follow with usage guidance. No unnecessary words or restatements.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, returned data, and usage context 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 coverage is 100% with a description for the only parameter. The tool description does not add new parameter information beyond the schema, but it implicitly introduces the default behavior (active subscriptions), providing minimal added meaning.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.), distinguishing it from siblings like subscribe and unsubscribe.

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

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

The description advises using the tool to review monitored subscriptions before adding more or to find an id to cancel, providing clear context. It does not explicitly state when not to use, but the guidance is sufficient.

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

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

Annotations are all false (no special behavior). The description adds key behavioral traits: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It also mentions the team reads digests daily and feedback affects roadmap, exceeding annotation coverage.

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

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

The description is concise and well-structured: opens with purpose, then usage guidance, then behavioral notes. Every sentence adds value without redundancy. No fluff.

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

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

Given the low complexity of a feedback tool (no output schema needed), the description comprehensively covers purpose, usage, parameters, constraints (rate limit, quota), and behavioral expectations. It leaves no gaps for an AI agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by providing usage tips for each parameter (e.g., 'be specific, 1-2 sentences typical, 2000 chars max' for message) and explaining the 'type' enum with examples. This elevates the parameter understanding.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies feedback types (bug, feature, data_gap, praise) and distinguishes this tool from siblings, which are mostly query/action tools, making the tool's unique role obvious.

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

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

The description provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and what not to do ('don't paste the end-user's prompt'). It also gives best practices (describe in terms of tools/packs) and mentions rate limits and quota exemptions.

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 safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral details: data source (CF analytics), no PII, caching window. No contradictions.

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

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

Two sentences plus a bullet list, front-loaded with core purpose. Every sentence adds value; no redundancy or fluff.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers data source, privacy, caching, and typical use cases. Complements annotations well.

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

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

Schema coverage is 100%, with a clear enum and description for the 'window' parameter. The description doesn't add new semantic info beyond reinforcing the difference between short and long windows.

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, using specific verbs like 'returns' and 'self-aggregating signal'. It distinguishes from sibling tools like 'discover_tools' by focusing on agent usage trends.

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

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

Three explicit use cases are listed, covering discovery, confirmation, and alignment. No explicit when-not-to-use or alternatives, but the sibling list provides context.

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

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

Adds significant behavioral context beyond annotations: explains the tool performs monotonicity checks, partition-sum checks, semantic similarity filtering, and fill checking. No contradiction with annotations (readOnly, openWorld, idempotent).

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 thorough and well-structured with clear sections, but it is lengthy. Every sentence adds value, though some redundancy exists. Front-loaded with the requirement and main purpose.

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

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

For a complex arbitrage tool, the description covers modes, checks, response structure, and even references sibling tools. Despite no output schema, the description compensates adequately.

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

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

Schema coverage is 100%, and the description adds rich meaning: examples of valid inputs, distinction between modes, and additional behavioral context (SEMANTIC ANCHOR, PARTITION FILTER) that elaborates on parameter effects.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, making the purpose unmistakable.

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

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

Explicitly states the requirement to use one of `event` or `topic`, and recommends `event` for specific markets and `topic` for cross-event scanning. It also explains when not to trade via the fill check. This provides clear guidance versus alternatives.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds extensive behavioral context: caching (1h KV-level), response structure (by_segment, diagnostics), detailed edge computation methodology, tradeable-edge knobs, and reliability warnings (e.g., Fed signal limitation). 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 detailed but well-structured with clear sections and front-loaded purpose. Every sentence adds value given the tool's complexity, though length could be trimmed for simpler use cases.

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 returned segments, diagnostics, tradeable-edge knobs, caching, and reliability caveats (Fed signal, fill assumptions). It comprehensively covers what an agent needs to invoke and interpret results.

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

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

Schema coverage is 100%, but the description adds meaning beyond bare schema, e.g., explaining that min_edge_pp is net of slippage, min_partition_leg_kelly applies inside partitions, and window filters by Polymarket volume. This adds practical context that aids correct invocation.

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

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

The description explicitly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and frames it for daily betting discovery. It distinguishes from siblings like polymarket_arbitrage by its focus on disagreement-based opportunities.

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

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

The description implies usage for daily betting discovery ('what should I bet on today') and mentions avoiding paging hundreds of markets, but does not explicitly state when to avoid this tool or provide direct 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 indicate the tool is read-only, open-world, and idempotent. The description adds valuable behavioral details: it reads from snapshots, explains data gaps due to cache-miss triggering, clarifies that decay is computed from daily closes, and notes the 60-day TTL limit. No contradiction with annotations.

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

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

The description is detailed but well-structured: it opens with a clear purpose, then describes the response fields, and ends with limitations. Every sentence adds value, though it 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 absence of an output schema, the description thoroughly explains the return value (tracked, expired, snapshot_dates) and their contents. It also covers limitations (TTL, snapshot gaps, decay computation). 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% with parameter descriptions. The description adds context: clarifies 'days' as lookback (consistent with schema) and explains 'window' as snapshot family. The response structure is elaborated, compensating for the lack of an output schema.

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

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

The description clearly states the tool's function: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on temporal evolution, not raw 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 explains when to use the tool—to differentiate between fresh and aged edges—and why the distinction matters for trading decisions. It implicitly contrasts with 'polymarket_edges' but does not explicitly list 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?

Despite annotations already indicating readOnly, idempotent, and non-destructive, the description adds substantial behavioral context: walks the order book ladder, returns specific fill metrics, and warns about risks like thin books converting arb into directional positions. It explains how size_usd is interpreted differently for each mode.

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 and well-structured with clear sections for single-market and basket modes. While slightly long, every sentence provides necessary value. The upfront requirement statement and mode breakdown make it 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 complex tool with two modes, 4 parameters, and no output schema, the description is remarkably complete. It covers all return fields for both modes, explains edge cases (partial fills, thin legs, directional risk), and provides usage thresholds. Nothing essential is missing.

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

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

With 100% schema description coverage, the description still adds significant meaning: explains default side for basket mode, clarifies the auto mode logic for basket, and details how size_usd is interpreted as settlement notional for baskets. This goes well beyond the schema's brief field 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 performs a realizable vs theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and lists specific return fields. It also differentiates from sibling tools like polymarket_arbitrage by stating when to use this tool before acting on arb signals.

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

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

Explicitly provides when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the differences between single-market and basket modes, including when to use each.

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

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

Annotations already indicate safe, read-only behavior. Description adds extensive behavioral context: explains incompatibility cases, temporal alignment, skipped cross-type/subtype counters, and real vs pre-mapped tradability. 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?

Well-structured with clear sections (purpose, modes, response, safety fields). Slightly verbose but every sentence adds needed context for a complex tool.

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

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

No output schema, yet the description fully explains the response structure (venue legs, spread, compatibility_warning, temporal_alignment, skipped counters). Covers all critical aspects for correct usage.

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

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

Schema coverage is 100%, but description adds value by explaining the relationship between topic and explicit overrides, providing concrete examples for topic values, and clarifying that explicit params override mapped sides.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two specific venues and emphasizing equivalence checking.

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 describes two modes (topic shortcuts vs explicit parameters) and provides guidance on when spreads are meaningful vs when compatibility warnings appear. Warns that most pre-mapped topics currently return warnings, managing user expectations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: scoped to identifier (anonymous IP, BYO key hash, account ID), behavior of listing all keys when key is omitted, and pairing with 'remember' and 'forget.' 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 three sentences, concise, and front-loaded with the main action. Every sentence adds value, no wasted words.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description is complete. It covers behavior, scoping, and relationship to siblings. Annotations provide safety profile.

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

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

Schema coverage is 100% with the 'key' parameter described. The description adds meaning: explains that omitting key lists all keys, and the memory was saved via 'remember.' This adds nuance beyond the schema.

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

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

The description clearly states the verb 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It identifies the resource (saved values/keys) and distinguishes from siblings 'remember' and 'forget' by explicitly naming them.

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

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

The description provides context for when to use: 'look up context the agent stored earlier ... without re-deriving it from scratch.' It also mentions scoping and pairing with 'remember' and 'forget.' However, it does not explicitly state when not to use it or exclude 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 read-only, idempotent, and non-destructive behavior. The description adds value by explaining the mark_read mechanism affects subsequent calls, and identifies the feed source, which is beyond annotation coverage.

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

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

The description is concise at five sentences with clear front-loading of purpose, followed by key details on return fields, filters, and additional behaviors. No wasted words.

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

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

The description covers input parameters, return fields, and polling safety. Although no output schema exists, the description provides sufficient context for an agent to understand the tool's behavior and response format.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for type and since, and explains the behavior of mark_read, providing 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 pulls fired events from a subscription feed and returns recent alerts with specific fields. It is specific about verb and resource but does not explicitly distinguish from sibling tools.

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

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

The description implies usage context (polls work fine) and provides an alternative access method via HTTP, but it lacks explicit when-to-use or when-not-to-use guidance compared to sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: it fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), describes fallback logic (GDELT preferred, GNews on rate limits/5xx), notes a known API sunset, and specifies the return structure (grouped changes, total_changes count, citation URIs). 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 a single paragraph that front-loads example queries. While it contains all necessary information, it is somewhat dense and could benefit from structured breaks (e.g., bullet points for data sources). However, every sentence earns its place and avoids redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, soft-failure), the description covers all critical aspects: what sources are queried, fallback logic, known limitations, parameter formats, and return structure. It also references the relevant sibling tool for alternative use cases. No output schema is provided, but the description sufficiently explains return values.

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 three parameters. The description enriches each: 'type' is clarified as only 'company' supported; 'since' includes examples and typical advice ('Use "30d" or "1m" for typical monitoring'); 'value' explains ticker vs. CIK formats. This adds practical 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 starts with clear example queries ('What's new with X') and explicitly states it returns a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It also distinguishes from sibling tool 'entity_profile' by specifying when to use the alternative. The purpose is specific, verb-driven, and resource-focused.

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 context with natural language examples and advises when not to use the tool ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews) and parameter recommendations, enabling correct invocation.

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 (idempotent, non-destructive), the description adds scope, persistence details (24h vs persistent), and scoping by identifier. 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?

Three sentences, front-loaded with main purpose, 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 key-value store with 2 params and no output schema, the description covers purpose, usage, persistence, and links to siblings 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 description coverage is 100%, so baseline is 3. Description provides examples of keys and values but adds limited new info 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 'Save data the agent will need to reuse later', uses a specific verb (save) and resource (data), and distinguishes from siblings like 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?

Explicitly says when to use ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: it mentions internal cascading through multiple endpoints (replacing manual lookups), auto-disambiguation for company, and specific return fields (ticker, CIK, RxCUI, citation URIs). No contradictions with annotations.

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

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

The description is front-loaded with examples and a clear purpose. Though somewhat lengthy, each sentence adds value. The structure uses quotes for examples and separates behavior from schema, making it well-organized.

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

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

Given the tool's complexity (two entity types, multiple outputs), the description adequately covers supported types, input expectations, and output details. It lacks an output schema but describes return values in prose. The mention of internal cascading provides a helpful mental model.

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

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

Input schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples (e.g., 'AAPL', 'ozempic') and noting auto-disambiguation for company input. This goes beyond the schema's basic descriptions.

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

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

The description starts with concrete examples like 'What's the ticker for...' and clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It specifies supported types (company, drug) and what each returns, making it highly specific and distinguishable from sibling tools like 'compare_entities' or 'entity_profile'.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the context strongly implies it's for name-to-ID resolution, which is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds behavioral context: probing each entity with ai_visibility_check, ranking, and return fields (score, confidence, signal density). 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 elegantly cover purpose, mechanism, use case, and return format. No wasted words; every sentence adds essential 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?

Despite no output schema, the description fully explains the tool's behavior (multi-entity comparison via ai_visibility_check), return format (ranked list with score, confidence, signal density), and utility. It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by stating that the first entity is treated as the 'subject' for narrative and others as competitors, which is not in the schema. This improves parameter understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs like 'probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized'. It distinguishes itself from sibling tools like ai_visibility_check by explicitly referencing multiple entities and competitive audits.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example query. However, it does not explicitly state when not to use the tool or mention alternatives like ai_visibility_check for single-entity checks. The guidance is clear for intended usage but lacks exclusion criteria.

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 readOnly, idempotent, not destructive. Description adds that it fans out to external services, returns a specific summary block, handles partial failures with sources_failed, and mentions bundlephobia's initial measurement can take 5-30s. Highly transparent.

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 moderately long but well-structured. It front-loads the main verb and resource, then provides details in a logical order. Could be slightly more concise, but every sentence adds value.

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

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

Given complexity (external dependencies, partial failures, specific output), the description covers return fields (summary block, links, alternatives), limitations (npm only, bundlephobia delay), and behavior. 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 descriptions for both parameters. Description adds value by explaining that scoped packages are accepted, version defaults to latest, and it's for npm. Provides meaningful usage 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 the tool's purpose: a composite check for adding an npm package, fanning out across deps.dev and bundlephobia. It uses specific verbs ('check', 'scan') and specifies the resource ('npm package'). It distinguishes from siblings by being a multi-source composite tool.

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

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

Explicit guidance: use when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies ecosystem (npm only in v1) and notes alternative for other ecosystems (deps.dev:version directly). Includes notes on partial failures and timing.

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

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

Annotations already indicate safe, idempotent read. Description adds significant detail: embedding model (BGE-base-en), window size (500 chars), overlap, character offsets, similarity scores, 200K char limit with truncation flagging. 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?

Three sentences, each earning its place: purpose, use case, technical details. Front-loaded with the main verb. No superfluous 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 explains return format (passages, offsets, similarity scores). Covers algorithm, constraints, and sibling tool pairing. 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?

100% schema coverage means parameters are already documented. Description adds value with query examples (e.g., 'supply-chain risk') and clarifies limit behavior (max passages). Text parameter's char limit is also noted.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the verb, resource, and scope. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining how they pair together.

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 to use when the record is too large for the prompt, saving context. Mentions pairing with ask_pipeworx_grounded for grounding. Lacks explicit when-not-to-use but context is well-defined.

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

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

The description adds significant behavioral context beyond annotations: it requires OAuth account, details delivery mechanisms (feed always on, optional email/sms/webhook with constraints like 10/day SMS cap and webhook signing), and notes the persistence of subscriptions. It does not contradict annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and aligns with the 'create' action.

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 front-loaded with the main purpose. Each sentence adds necessary information for correct usage. It could be slightly more concise, but given the complexity of subscription setup, the length is justified.

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

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

The description covers prerequisites, supported types with examples, delivery options with constraints, and the return value ('new subscription id'). No output schema exists, but the description adequately addresses what is returned. It is comprehensive for a creation tool with nested parameters.

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

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

Schema coverage is 100% with descriptions for all parameters. The description goes further by providing concrete examples for each type in 'params' (e.g., sec_8k: {ticker, items}) and elaborate delivery constraints (phone verification, webhook signing secret returned once). This adds substantial value beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create), resource (subscription), and return value, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description provides clear context for using the tool: requires Pipeworx OAuth account (not available to anonymous/BYO), lists supported types with examples, and details delivery channels with constraints (e.g., SMS cap, verification). While it doesn't explicitly contrast with alternatives, the context is sufficient to infer when to use this over list_subscriptions or unsubscribe.

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

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

The description adds behavioral context beyond the readOnlyHint, idempotentHint, and destructiveHint annotations by explaining the return format (category-bucketed examples with exact tool+argument shapes) and usage patterns (no args for full spread, topic for focus). There is no contradiction with annotations.

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

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

The description is front-loaded with alternative natural language queries and clearly states the purpose. It is slightly verbose but each sentence adds value, explaining what the tool returns and how to use it. Could be trimmed slightly but 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 the annotations (readOnly, openWorld, idempotent) and no output schema, the description fully explains the return type (example questions with tool shapes), usage (no args or topic), and its role as an onboarding entry point. It also ties into the meta-tools ecosystem, making it complete for an onboarding tool.

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

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

Schema coverage is 100% and the schema description already provides parameter details (optional topic with enumerated values). The tool description does not add significant new meaning to the parameter beyond contextualizing its role in focusing results, so it meets the baseline.

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

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

The description explicitly states the tool returns category-bucketed example questions for what to ask Pipeworx, using the live catalog. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists tools) by focusing on onboarding and suggestion.

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

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

The description clearly indicates when to use this tool: 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It implies it is the starting point for onboarding but does not explicitly list when not to use it or alternatives to avoid.

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

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

Annotations: readOnlyHint=false (write), destructiveHint=false, idempotentHint=true. Description says 'cancel' (consistent write) and clarifies 'deactivated (not deleted)' aligning with destructiveHint=false. Adds useful context that historical events remain available. No contradiction.

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

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

Two sentences: first fronts the core action 'Cancel a subscription by id.' Second adds ownership enforcement and behavioral details. Every sentence earns its place with no fluff.

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

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

With no output schema and only one parameter, the description sufficiently covers purpose, usage guidelines, and behavioral traits. No gaps remain for an agent to correctly select and invoke the tool.

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

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

Input schema has one required parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' Description mentions 'by id' but adds no additional semantic value beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id.', specifying the verb (cancel) and resource (subscription by id). It distinguishes from sibling tools like subscribe, list_subscriptions, and recent_alerts by focusing on the cancellation action.

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 'Ownership is enforced — you can only cancel your own subscriptions.' This tells the agent when to use it (own subscriptions) and implies when not to (others'). Also explains the deactivation behavior and reference to historical events via recent_alerts.

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, etc.), the description reveals return types (verdicts, citation, delta), supported data sources (SEC EDGAR+XBRL), and the efficiency benefit. 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 a compact paragraph with no wasted words. It front-loads with query examples, states purpose, scope, return info, and efficiency claim concisely.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers input, output, supported domain, and use case fully. It is complete for effective agent selection.

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

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

Schema coverage is 100% with a good parameter description. The tool description adds context that the claim must be about company finances, which is not in the parameter description itself.

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 verifies natural-language claims against authoritative sources, with examples and a specific scope (company-financial claims). It distinguishes from siblings by indicating it replaces 4-6 sequential calls, making its function unique.

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

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

The description explicitly says to use it when the agent needs to fact-check a user's claim and specifies the domain (company-financial claims). It does not explicitly exclude other domains or mention alternatives, but the scope is clear enough.

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