Mychem

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

The description adds significant behavioral context beyond annotations: default model (Workers AI Llama-3.3-70b, free), BYO key for Anthropic with direct billing, and return structure (per-model objects plus combined view). Annotations already declare readOnly, openWorld, idempotent, non-destructive; description agrees and elaborates.

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: two sentences with a clear front-loaded purpose, followed by default behavior, optional key explanation, return structure, and use cases. Every sentence adds value without redundancy.

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

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

The description covers all key aspects: what it does, input parameters (with defaults and optionality), output structure (per-model and combined), pricing/free model, and use cases. No output schema exists, but the description adequately describes return fields.

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 explaining default model behavior, the optionality of _apiKey (only needed for anthropic), and the return format (score, confidence, signals, raw_response). This goes beyond the schema's parameter descriptions.

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

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

The description uses specific verbs 'probe' and 'score' with clear resource 'LLMs for what they know about a business/brand/product/topic'. It distinguishes from sibling tools like 'ask_pipeworx' by focusing on AI visibility scoring rather than general Q&A or entity profiles.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not provide explicit when-not-to-use or alternatives, but the context signals and sibling list help infer that this tool is specialized for visibility checks rather than general 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?

Beyond annotations (readOnly, openWorld, idempotent), the description adds that it routes to 3,650 tools, fills arguments, and returns stable pipeworx:// URIs, giving helpful 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 front-loaded with key guidance and uses bullet-like examples, though it is slightly lengthy; each 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 many sibling tools and rich annotations, the description covers purpose, usage, and behavior well; lacks detailed output format explanation but the citation URIs imply 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% but the description adds value by giving concrete examples and confirming that any natural language question is acceptable, which goes beyond the schema's alias 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 answers factual questions using structured data from many sources, and distinguishes itself from web search and likely siblings by emphasizing its authoritative data and citation URIs.

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 over web search and lists many use cases and example queries, but does not explicitly state when not to use it or detail alternatives like 'ask_pipeworx_grounded'.

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, openWorldHint, destructiveHint=false. Description adds substantial behavioral details: routing through 3,650 tools, extracting answer only from tool result, explicit refusal reasons (e.g., 'not_in_source'), and cost of one extra LLM call — going well beyond annotations.

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

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

Description is concise (about 5 sentences), front-loaded with the key differentiator (hallucination-resistant), and every sentence adds value without redundancy.

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

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

Despite no output schema, description fully explains return structure (answer, evidence, confidence, source, refusal_reason) and covers all possible refusal reasons, making the tool's behavior completely understandable for high-stakes 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%, so schema already documents the parameter and its aliases. Description does not add new semantic meaning beyond what is in the schema, thus 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?

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads', specifies verb 'ask' and resource 'Pipeworx — Grounded', and explicitly distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call cost and use cases.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and directly says 'prefer ask_pipeworx for casual lookups', defining clear when-to-use and when-not-to-use along with alternative.

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

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

The description adds extensive behavioral detail beyond annotations: it explains low-confidence match suppression, closed market handling, wide-spread warnings, resolver contract, parent event extractor, news fallback mechanisms, and response shapes. This complements the readOnlyHint, idempotentHint, and openWorldHint annotations without contradiction.

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

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

The description is long but well-structured, starting with purpose, progressing to classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, and safety. Each section is clearly demarcated. However, it could be more concise; some details (e.g., exhaustive fan-out examples) might be trimmed without losing clarity.

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

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

Given the tool's complexity (3 parameters, no output schema, numerous edge cases), the description is extraordinarily complete. It covers input handling, depth behavior, output shapes for multiple scenarios, resolver contract inspection, parent event extraction, news fallback, and safety conditions. No important context is missing.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by clarifying the 'depth' parameter (quick vs thorough) and the 'include_raw' effect on response size (~20KB vs 50-500KB). It also explains acceptable market input formats beyond the schema. This extra context raises the score to 4.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input forms (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive data gathering for betting decisions.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes when not to fully trust results (low-confidence resolution, closed markets, wide spreads) and explains blocking conditions, making it clear when to use this tool vs 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, destructiveHint. Description adds no behavioral details beyond what annotations provide, but does not contradict 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?

Two sentences: first defines action and resource, second elaborates on id formats and return content. 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 read-only fetch tool with comprehensive annotations, the description fully explains what the tool does and returns. No missing gaps for agent invocation.

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

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

Schema coverage is 100%. Description adds examples for 'id' parameter and mentions return fields, but these are minor additions 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?

Describes specific verb 'Fetch' and resource 'full aggregated annotation for a single chemical/drug by id.' Clearly distinguishes from sibling tools like 'entity_profile' or 'resolve_entity' which are more generic.

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?

States typical id type (InChIKey) and alternative ids (DrugBank, ChEMBL, etc.), guiding when to use. Lacks explicit when-not-to-use or direct sibling alternatives, but context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URI returns. 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 somewhat long but well-structured, front-loaded with example queries. Each sentence adds value, explaining data sources, sorting, and replacement of sequential lookups. Minor redundancy could be trimmed, 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 tool's complexity and no output schema, the description provides a solid overview of inputs, behavior, and outputs (paired data + citation URIs). It covers both entity types and sorting. Some details like exact metrics per type could be clearer, but 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%, providing baseline 3. The description adds meaningful details: explains that type='company' pulls financials with specific fiscal year handling, and type='drug' pulls adverse event and trial data. It also clarifies values constraint (2-5 items) with examples. This raises the baseline to 4.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs, specifying data sources and metrics. Example queries like 'Compare X and Y' and 'which is bigger' show the intended use, and it distinguishes itself from sibling tools like entity_profile by noting it replaces sequential lookups.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example triggers. While it does not explicitly list when not to use, the guidance is strong and contextually clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds useful behavioral context: 'each result is ready to call directly, no second schema lookup needed' and mentions returned content (names, descriptions, schemas with examples). 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 comprehensive yet front-loaded with the core purpose. It could be slightly trimmed but every sentence adds value, making it appropriately sized.

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 (6 params, no output schema, many siblings), the description covers purpose, behavior, usage guidance, and return format adequately. It compensates for lack of output schema by describing results as 'top-N most relevant tools with full schemas.'

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 reiterates the query parameter accepts aliases and natural language, which is already in the schema, adding no additional value.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains the return format, distinguishing it from sibling tools which are domain-specific (e.g., chem, 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?

Explicitly advises to 'Call this FIRST when you have many tools available,' providing clear context for when to use it. It doesn't explicitly state when not to use it, 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 already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: it fans out across multiple APIs (SEC, XBRL, USPTO, news, GLEIF), specifies what each returns, acknowledges the USPTO PatentsView API sunset with soft-fail behavior, and notes that names are not supported. 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 informative and front-loaded with example queries, but it is somewhat long. However, every sentence adds value, and the structure flows logically from purpose to details. A minor reduction for verbosity.

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 aggregation) and the absence of an output schema, the description is remarkably complete. It enumerates all returned components (CIK, filings with URIs, fundamentals sorted by period_end, patents with sunset note, news via fallback, LEI). It also covers limitations, making it sufficient for an agent to understand the tool's capabilities.

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 essential meaning beyond the schema. It explains that 'type' is currently limited to 'company', gives examples for 'value' (ticker or zero-padded CIK), and explicitly states that names are not supported. This helps the agent avoid errors.

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

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

The description clearly states that the tool provides a 'full cross-source profile of a US public company' in one parallel call. It gives specific example queries and lists the exact data returned, making the purpose unmistakable. It also differentiates from sibling tools like resolve_entity by noting that names are not supported here.

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 advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. It also tells the agent when not to use it (if only a name is available, use resolve_entity first). This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and when to use, which complements the annotations without contradiction.

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

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

Two concise sentences: first states core action, second provides usage scenarios. Every word adds value, 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?

For a tool with one parameter, no output schema, and clear annotations, the description covers purpose, usage, and pairing. Nothing essential is missing given the tool's simplicity.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, using specific verb 'Delete' and resource 'previously stored memory'. It distinguishes from sibling tools 'remember' and 'recall' by implying it's the deletion counterpart.

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 (stale context, task done, clear sensitive data) and suggests pairing with 'remember' and 'recall'. Does not explicitly state when not to use, but the context is clear enough for an 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, openWorldHint, idempotentHint, destructiveHint, covering safety. The description adds value by describing the crawling, extraction, and output format, 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?

The description is three sentences plus a concise bullet list, front-loaded with the core purpose, then details and use cases. Every sentence adds value with no redundancy.

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

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

For a simple tool with 2 params, no output schema, and strong annotations, the description covers purpose, use cases, process, and output format. Minor gaps: no mention of error handling or prerequisites (e.g., URL reachability), but overall sufficient.

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

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

Schema coverage is 100%, with both parameters well-described in the schema. The description adds no further detail for max_links and only a minor example for url, so it does not significantly enhance 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 clearly states the verb 'generate', the resource 'llms.txt file', and the actions: fetch, extract, emit. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation, not just visibility analysis.

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

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

The description provides explicit use cases (client indexing, own project, competitor auditing), giving clear context. However, it does not explicitly state when not to use this tool or mention alternative sibling tools for similar tasks.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing the return fields and mentioning 'active' vs 'include_inactive', but no additional behavioral traits like scope or pagination.

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

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

Two sentences, front-loaded with purpose, then usage guidance. No filler or redundancy. 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?

For a list tool, the description covers purpose, returned fields, usage context, and parameter semantics. No output schema exists, but the description provides the return fields. It lacks details on ordering or pagination, but those are not critical for this tool's simplicity.

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

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

Schema coverage is 100%, so the parameter is well-documented in the schema. The description adds marginal context by implying the default behavior (active only) through the phrase 'active subscriptions' and the parameter name.

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

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

The description clearly states the action ('list'), the resource ('the caller's active subscriptions'), and specifies the returned fields (id, type, etc.). This distinguishes it from sibling tools 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 provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' It suggests when to use but does not explicitly mention when not to use or name alternatives, though siblings are available.

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 idempotent, readOnly, non-destructive, and openWorld behavior. The description adds context about returning statistics and metadata, but does not disclose any additional behavioral traits such as data freshness or format.

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

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

The description is a single sentence of 9 words, highly concise and front-loaded with the core purpose. Every word contributes meaning.

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

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

For a simple tool with no parameters and no output schema, the description is adequate but vague. It does not specify what 'statistics' entail or the format of metadata, leaving some ambiguity.

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 are no parameters, so schema coverage is 100%. The description does not need to add parameter information; baseline score is high. However, it adds minimal value beyond the schema.

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

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

The description states 'Dataset statistics and source/release metadata for MyChem.info,' which clearly indicates the tool provides statistical and metadata information. It is specific but does not explicitly differentiate from sibling tools, so not a perfect 5.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer 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?

The description discloses important behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, and doesn't count against quota. Annotations are minimal (no readOnly, etc.), so this added context is valuable for agent behavior planning.

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—five sentences with no wasted words. It front-loads the purpose, then covers usage, constraints, and quotas in a logical order. Every sentence earns its place.

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

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

Given the tool's simplicity (no output schema, 3 parameters with full schema descriptions), the description is complete. It covers purpose, usage guidelines, behavioral traits, and parameter usage nuances, leaving no gaps.

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

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

Schema description coverage is 100%, so the schema already documents each parameter well. The description adds value by explaining what not to include in the message (e.g., 'don't paste the end-user's prompt') and by reiterating the types in context, which helps the agent form better messages.

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 uses a specific verb ('send feedback') and resource ('Pipeworx team'), and it naturally distinguishes itself from all sibling tools, as none are for feedback.

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

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

The description provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes what not to do: 'don't paste the end-user's prompt.' This gives clear guidance for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the data source (CF analytics-engine), the lack of PII, and the caching behavior (5min-1h depending on window), providing useful 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?

The description is concise and well-structured: a one-sentence summary followed by bullet-point use cases and a note on data source and caching. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what it returns, use cases, caching, and data source. It lacks an explicit return format, but the listed outputs (top tools, top packs, total call volume) are sufficient for an AI agent to understand the tool's functionality.

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 the single 'window' parameter fully described in the schema via enum and description. The tool description adds a slight nuance about shorter vs longer windows, but this is minimal. 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 starts with a clear verb ('Returns') and states the specific resource: top tools, top packs, and total call volume from other AI agents on Pipeworx. While it does not explicitly differentiate from sibling tools like 'discover_tools', the purpose is specific and unambiguous.

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

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

The description provides three explicit use cases in bullet points: discovering hot data sources, confirming canonical tools, and aligning use cases. It does not list when not to use the tool or suggest alternatives, but the guidance 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 discloses key behaviors beyond annotations: it explains the algorithms, the 3pp threshold for signals, the Jaccard similarity requirement, the partition filter on placeholder slugs, and what the response contains. There is no contradiction with annotations (readOnlyHint, etc.).

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 but slightly dense. It is front-loaded with the requirement and mode differentiation, and every sentence adds value. Minor reduction for length, but it remains clear and 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 modes, multiple algorithms, filtering criteria, no output schema), the description is complete. It explains all key aspects: how each mode works, thresholds, filters, and response fields, leaving no critical 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%, and the description adds significant meaning: it explains the difference between the two modes, gives examples of valid inputs (slugs, URLs, seed questions), and describes the semantic anchor and partition filter, which are not in 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (single-event and cross-event) and provides specific examples, making it easy to understand what the tool does and how it differs from siblings.

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 requires exactly one of 'event' or 'topic' and warns that no-args calls fail. It recommends when to use each mode (e.g., 'recommended for a specific market' for event, 'for cross-event scanning' for topic) and provides examples and constraints like Jaccard similarity threshold and placeholder filter, giving 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 already indicate safe, read-only, idempotent behavior. The description adds extensive behavioral details: caching at KV level keyed to all knobs, output structure (by_segment, diagnostics), model formulas, edge calculations, and parameter effects. 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 long but well-structured, with clear sections for model families, response structure, knobs, and caching. It front-loads the purpose. However, some redundancy exists (e.g., repeat of 'Tradeable-edge' details). It earns its length given the tool's complexity.

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

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

With no output schema, the description fully explains the response structure (by_segment, diagnostics, Fed note, etc.), model logic, and caching. It covers all aspects needed for an agent to understand call behavior 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%, so baseline is 3. The description enhances parameter meaning by explaining context (e.g., 'Tradeable-edge filter', 'Partition arbs always return kelly_fraction_half=0'), going beyond the schema's type and description fields.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and the detailed segmentation into model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) distinguishes it from potential sibling tools like polymarket_arbitrage.

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

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

The description provides usage context ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets'), which implies when to use it, but it does not explicitly state when not to use it or compare to alternatives like polymarket_arbitrage. Exclusions are only implicit (e.g., Fed bets are excluded from ranking).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds extensive behavioral detail: two modes, response structure (leg-by-leg prices, spreads, safety fields), and edge cases (compatibility_warning types, temporal alignment, skipped pairs). This goes far beyond the annotations, giving the agent a full picture of what the tool does and when results should be trusted.

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 (TWO MODES, RESPONSE, SAFETY FIELDS), making it easy to parse. It front-loads the core purpose. However, it is somewhat verbose, with detailed technical explanations that could potentially be summarized. Every sentence adds value, but a slightly tighter edit could improve efficiency 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?

No output schema exists, so the description must fully explain return values. It does so comprehensively: per-venue leg prices, spread array, compatibility_warning with two cases, temporal_alignment fields, and skipped pair counters. Given the tool's complexity (two modes, multiple error states, cross-venue comparison), this description is remarkably complete, leaving no major gaps for an AI agent to misunderstand.

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 adds meaning by explaining the two operational modes ('topic' vs explicit), providing concrete examples ('fed', 'btc'), and detailing how each parameter behaves (overrides, auto-fetching). This adds moderate value beyond the schema, clarifying the interaction between parameters and the response fields.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' with specific verb+resource. It distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue spreads, and explains two distinct modes (topic shortcuts and explicit pairings), leaving no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool, including safety fields that indicate when spreads are meaningless (incompatible bet shapes, temporal misalignment). It implicitly guides away from use when compatibility warnings are triggered, though it does not explicitly name alternative tools. The pre-mapped topic caveat ('most pre-mapped topics return compatibility_warning today') is helpful but could be more directive.

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, etc. The description adds value by explaining the return type (aggregated hits with cross-references) and the variety of accepted query formats, which is 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 two sentences, front-loaded with the main action, and every sentence adds essential information. No redundancy or wasted words.

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

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

Given no output schema, the description explains the return type qualitatively but lacks specifics on the response structure (e.g., JSON format, field names). It is adequate but could be more detailed.

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

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

Schema description coverage is 100%, and the description adds examples for the 'query' parameter (plain name, InChIKey, fielded query) and mentions 'size' and 'fields' implicitly. This enhances 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 clearly states the tool searches MyChem.info for drugs and chemical compounds, accepts multiple query formats, and returns aggregated hits with cross-references. It provides specific verbs and resources but does not differentiate from sibling tools like 'chem'.

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 this to resolve a drug name into structured identifiers,' providing clear guidance on when to use. However, it lacks explicit when-not-to-use instructions or alternatives among 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 provide readOnlyHint=true and idempotentHint=true, and the description adds value by specifying scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and pairing with remember/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 with no wasted words. It front-loads the purpose, provides usage guidance, and adds contextual completeness efficiently.

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

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

For a tool with 1 optional parameter and no output schema, the description fully explains the dual behavior (single retrieval vs. listing), scoping, 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% and already describes the parameter 'key' as 'omit to list all keys'. The description repeats this without adding new semantics. 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 explicitly states the verb ('retrieve') and resource ('value previously saved via remember'), and distinguishes from siblings ('list all saved keys (omit the key argument)'). It clearly differentiates from remember and forget by name.

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: 'look up context the agent stored earlier' and 'without re-deriving it from scratch'. It provides context on scoping and pairing with remember/forget, but does not explicitly state when not to use or provide alternatives.

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

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

The description adds behavioral context beyond annotations: describing that mark_read flags events as read affecting future calls, and that polling is suitable. However, there is a contradiction with the idempotentHint annotation because mark_read is a side effect.

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 four sentences, each serving a purpose: stating purpose, listing key fields, explaining parameters and side effects, and noting polling and alternative access. No wasted words.

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

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

Given no output schema, the description covers key returned fields (source, citation_uri, raw payload) and explains mark_read's effect. It mentions filtering and polling. Minor omissions: limit parameter and unread_only are not described in text, but schema covers them.

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 explaining the effect of mark_read and mentioning filtering options, as well as specific returned fields, 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 pulls fired events from a subscription feed and returns alerts with source, citation_uri, and raw payload. It is specific about the action and resource, but does not explicitly distinguish from sibling tools like list_subscriptions or recent_changes.

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 filtering by type and since, the effect of mark_read, and that polling works fine. It also provides an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or compare to 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, idempotent, non-destructive behavior. The description adds significant behavioral context: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and return format (changes[] grouped by source). 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 thorough and well-structured, with examples front-loaded and technical details following. Could be slightly more concise, but every sentence serves a purpose and the length is justified by the tool's complexity.

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

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

For a complex tool with multiple data sources, fallback behavior, and no output schema, the description is remarkably complete. It covers source specifics, edge cases (soft-fail, fallback), and return structure (grouped changes, total_changes, citation URIs). No gaps identified.

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

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

Schema coverage is 100% with descriptions, but the description adds meaning beyond schema: clarifies 'since' formats (ISO date, relative shorthand like '7d', '30d'), that 'value' accepts ticker or CIK, and provides typical monitoring hint. This extra guidance enhances agent 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?

Description starts with numerous example queries ('What's new with X', 'latest on Y'), then clearly states the tool provides a change feed for a company over a window, fanning out to multiple sources. It explicitly distinguishes itself from entity_profile, making purpose and differentiation 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?

Provides explicit when-to-use examples and contrasts with sibling tool entity_profile ('Use entity_profile instead when you want the static profile'). Also gives usage guidance for the 'since' parameter (e.g., 'Use "30d" or "1m" for typical monitoring').

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 key-value pair storage, scoping by identifier, and persistence differences (authenticated vs. anonymous, 24-hour retention). Adds value beyond annotations which already indicate idempotent and non-destructive traits.

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, no redundant information. Every sentence earns its place with concise wording.

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

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

For a simple 2-param tool with no output schema or nested objects, the description fully covers purpose, usage, behavior, and parameters. 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 covers 100% of parameters with descriptions. Description adds examples for key values (e.g., 'subject_property') and clarifies value as 'any text', providing incremental context.

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

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

Description clearly states the tool 'save data the agent will need to reuse later' with specific verb and resource. It distinguishes from siblings like 'recall' and 'forget' by pairing.

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 you discover something worth carrying forward') and provides exclusions (scope, persistence). Pairs with recall and forget, giving 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safe, idempotent, read-only behavior. The description adds that it cascades through several lookup endpoints internally, replacing 2-3 manual lookups, which provides useful 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?

The description is somewhat lengthy but well-structured: it starts with query examples, then states the primary use case, then details supported types. Every sentence adds value, and it is not overly verbose for the complexity of the tool.

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

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

Given no output schema, the description sufficiently explains return values for each type. It covers internal behavior (cascading lookups) and placement in the tool list (first step). The sibling list includes entity_profile, which suggests a complementary tool, providing enough context for an agent to decide when to invoke this tool.

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

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

The input schema covers 100% of parameters with descriptions. The description adds rich meaning for each parameter value (e.g., company accepts ticker, CIK, or name; drug accepts brand or generic) and explains the returned fields per type, 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 explicitly states the tool's purpose: resolve a user-spoken name to a canonical identifier, with concrete examples like 'What's the ticker for…'. It clearly distinguishes itself as the first step before using other tools that require IDs, and lists supported entity types (company, drug) and their outputs.

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

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

The description provides clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It details what the tool accepts and returns for each type, but does not explicitly mention when not to use it or compare to sibling tools like entity_profile, though the context 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 safe, idempotent, non-destructive behavior. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density, which is valuable context not in annotations.

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

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

Three sentences, front-loaded core function, efficient process description, and concrete use case. 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?

Tool has 4 params (1 required), no output schema, but annotations are comprehensive. Description explains output structure, gives usage examples, and covers behavioral aspects sufficiently for the 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%, baseline 3. Description adds meaning by explaining first entity treated as 'subject' for narrative, clarifies count 2-8, and gives example for context. Adds value beyond schema.

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

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

Description clearly states tool compares AI visibility across multiple entities side-by-side, using specific verb and resource. Distinguishes from sibling like ai_visibility_check (single probe) and compare_entities (generic).

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 frames use case for competitive AI-marketing audits with an example question. Implies when to use but does not provide explicit exclusions or alternatives beyond mentioning ai_visibility_check.

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 critical behavioral details: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also describes the return content structure (summary block, per-advisory detail, links, alternative versions), which is not covered by annotations.

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

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

The description is front-loaded with the core purpose and efficiently packs details in a few sentences. Each sentence adds value (purpose, use cases, ecosystem limit, failure behavior). Slightly longer than minimal, but every sentence earns its place; no redundant phrases.

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 has only 2 parameters, no output schema, and moderate complexity, the description fully covers: what the tool does, when to use, ecosystem scope, performance caveats, error handling, and return structure. No gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor value by noting 'Scoped packages (e.g. "@types/node") are accepted.' for the 'package' parameter, but does not provide additional meaning beyond the schema for 'version' (which already states defaults). Baseline of 3 is appropriate.

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

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

The description starts with a specific verb ('Scan Dependency') and clearly defines the tool's composite action: it fans out across deps.dev and bundlephobia to answer the question 'should I add this npm package to my project'. It explicitly lists the aspects checked (license, advisories, version history, bundle size, etc.), making the purpose unambiguous. Among siblings, no other tool performs npm dependency scanning, so it is 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?

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a clear out-of-scope condition: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing the agent to alternative approaches for non-npm ecosystems.

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

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

Beyond annotations (which already mark the tool as safe and idempotent), the description discloses the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), character cap (200K with truncation flag), and return format (passages with offsets and scores). This is rich behavioral context that significantly aids correct invocation.

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 (about 6 lines), front-loads the core purpose and usage case, and packs technical details efficiently. Every sentence adds value without redundancy.

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

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

Given the absence of an output schema, the description fully explains what the tool returns (passages with offsets and scores), how it works (embeddings/windowing), and its limits (200K chars). It also contextualizes usage with a sibling tool, making it complete for this simple search tool.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description does not add new semantic details beyond the schema—it merely restates the text limit and query purpose. Baseline 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' immediately clarifying the verb (search) and resource (inside a record). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with tools that might perform broader searches.

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

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

The description gives explicit guidance: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also explains how it pairs with ask_pipeworx_grounded, providing a workflow context. This clearly tells the agent when to prefer this tool over alternatives.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive nature. The description adds that it requires OAuth, returns an id, and details delivery channels and SMS caps.

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 well-structured with bullet points for types and delivery. It front-loads the main purpose. 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 the tool's complexity (3 params, nested objects, multiple types, delivery options), the description covers prerequisites, type-specific filters, delivery channels, and limits. No output schema, but return value is mentioned.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains the type enum values, gives specific examples for params structure, and adds delivery constraints (email validation, SMS verification, cap).

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

It explicitly requires a Pipeworx OAuth account and provides context on when to use each subscription type with examples. However, it does not explicitly contrast with alternatives like list_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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the output format (category-bucketed questions with tool+argument shape) and that it draws from a live catalog. 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 front-loaded with clear synonyms and purpose, but slightly lengthy. It efficiently covers what the tool does, how to use it, and when to use it. Every sentence adds value, but could be 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 no output schema, the description fully explains the return value (category-bucketed examples with tool+arguments). It covers input, output, and usage context. It also explains the origin of examples (live catalog). 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 already includes detailed description for the `topic` parameter, including the list of options and the default behavior. The tool description adds no new information beyond restating the schema content, so baseline 3.

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

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

The description clearly states the tool is an onboarding entry point returning example questions. It lists synonyms like 'what can I ask Pipeworx?' and distinguishes from siblings by explicitly saying 'Use this FIRST when you do not yet know what Pipeworx can do.'

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

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

The description provides explicit guidance: call with no arguments for full spread, or pass `topic` to filter. It also states when to use it ('when you do not yet know what Pipeworx can do') and mentions meta-tools like ask_pipeworx.

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 important behavioral context beyond annotations: it clarifies that the row is deactivated (not deleted) and that historical events remain available via 'recent_alerts'. 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?

Two concise sentences pack all essential information: action, resource, ownership constraint, and effect. No wasted words; front-loaded with the core purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage constraints, behavioral outcome, and relationship to sibling tools. 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 coverage is 100% with the 'id' parameter well-described. The description adds a semantic constraint: the id must be the user's own subscription, which is not in the schema. This adds value beyond the schema description.

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

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

The description clearly states the action 'cancel a subscription by id', specifies the resource 'subscription', and adds ownership constraint ('you can only cancel your own subscriptions') and behavioral detail ('deactivated, not deleted'). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states 'you can only cancel your own subscriptions', providing clear context for use. It does not explicitly mention alternatives, but the sibling tool list includes related tools, and the description effectively implies when 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich details: verdict categories (confirmed, refuted, etc.), structured output with citation and delta, and the underlying data sources (SEC EDGAR + XBRL). 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 moderately long but well-structured: starting with purpose, usage guidance, then return details. Each sentence adds value, though it could be slightly tightened without losing information.

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

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

Given no output schema, the description thoroughly explains the return values (verdict types, citation, delta). It also explains the efficiency gain (replaces 4-6 calls). For a single-parameter tool, this is comprehensive.

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 sole parameter 'claim' has a descriptive schema example. The description adds extra context about acceptable phrasing and domain constraints, going beyond the schema. With 100% schema coverage, baseline is 3 but the description provides additional value.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries and specifies the domain (company-financial claims), distinguishing it from siblings like 'ask_pipeworx_grounded' which is more general question-answering.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives example intents. However, it does not explicitly state when not to use it or name alternative tools for out-of-scope claims.

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