Codestats

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

Describes default model, BYO API key for Anthropic, and return structure (per-model score, confidence, signals, raw_response + combined view). Annotations confirm read-only, idempotent, non-destructive; description adds cost and data flow 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?

Three concise sentences: first states core action, second adds key details (default model, API key), third lists return and use cases. No wasted words.

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

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

Despite no output schema, the description fully explains inputs, behavior, and outputs. Annotations cover safety. Complete for a probing tool with moderate 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?

All 4 parameters have schema descriptions (100% coverage). Description adds value by explaining default model, API key necessity, and providing example use for entity and context parameters.

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

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

The description starts with a specific verb ('Probe') and resource ('LLMs'), clearly stating the tool scores visibility per model. It distinguishes itself from siblings by focusing on general entity visibility across models, not limited to Pipeworx.

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 lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Lacks explicit when-not-to-use or direct sibling differentiation, 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 already indicate readOnlyHint, openWorldHint, idempotentHint, and nondestructive. The description adds valuable context: it routes to 4,774 tools, fills arguments, returns structured answer with pipeworx:// citation URIs, works on every tier, and is a fast single call. 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 the key preference statement, then details scope, examples, and usage alternatives. It is slightly long but every sentence adds value. It earns a high score due to clear structure.

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 a query router covering thousands of sources, the description is remarkably complete: it explains when to use, provides examples, cites alternative tools, and notes constraints like tier availability and citation format. No output schema, but return values are described 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%, with all 6 parameters (including aliases) described. The description does not add new semantics beyond the schema, though it provides examples and reemphasizes aliases. Baseline 3 is appropriate.

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

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

The description clearly states it routes questions to a large set of sources to answer factual questions with citations. It uses specific verbs like 'routes', 'fills arguments', 'returns structured answer'. It distinguishes from sibling tools like ask_pipeworx_grounded and deep_research by specifying when to use each.

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 prefer this tool over web search for factual questions, provides numerous examples of query types (e.g., 'current US unemployment rate'), and instructs to step up only when needed, naming alternatives like ask_pipeworx_grounded or deep_research.

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

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

Annotations already indicate readOnly, idempotent, open world. The description adds critical details: refusal reasons, evidence return, using only tool result content, and explicit list of refusal scenarios.

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

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

Front-loaded with key purpose, but contains multiple sentences. Each adds value, though slightly verbose. Could be trimmed slightly without loss.

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 return format, refusal reasons, and use cases. All behavioral aspects are covered.

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

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

Schema coverage is 100% and the description only repeats that it accepts a natural language question with aliases. No additional semantics beyond schema are provided.

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

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

The description clearly defines the tool as 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by contrasting its rigorous extraction and refusal behavior.

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 ('high-stakes', when answer will be quoted/cited/acted on) and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), including cost trade-off.

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

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

Annotations indicate read/immutable/idempotent. Description adds extensive behavioral detail: resolver contract (confidence, alternatives, suggestions), parent event extraction, news fallback mechanisms, safety short-circuits for low confidence/closed markets, spread warnings, and cancellation rule parsing. 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?

Very long (multiple paragraphs), but well-structured with sections and examples. Front-loaded purpose, but excessive detail for an agent may hinder quick scanning. Could be more concise while retaining key points.

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 (resolver, fan-outs, edge cases, status codes), description is remarkably complete. Covers market match confidence, parent event, news fields, safety mechanisms, resolution rules. No output schema, but response shapes are described. Fully equips agent to use correctly.

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

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

Schema coverage 100%, baseline 3. Description adds significant value: explains depth quick vs thorough, market input types with examples, include_raw with size estimates and use cases. Exceeds baseline by providing contextual usage guidance for each parameter.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question) and outputs (evidence packet, comparison). It distinguishes from siblings by focusing on single-bet comprehensive research, not edge tracking or arbitration.

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 use cases: 'should I bet on X', 'what does the data say', 'is there edge'. Provides examples of fan-out per bet type. Lacks explicit when-not-to-use compared to siblings, 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 already declare safe read-only behavior. The description adds valuable context: parallel execution, correct handling of off-calendar fiscal years, sorted results, and citation URIs. No contradictions.

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

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

The description is verbose but informative. It starts with query examples, which aids usability. Every sentence adds value, though it could be slightly more concise 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 and lack of output schema, the description covers return format (paired data, citation URIs) and sorting behavior. It could detail the return fields more, but it is sufficiently complete for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameters by explaining data sources for each type (10-K for company, FAERS/FDA/trials for drug) and providing examples, adding significant 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 explicitly defines the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single call. It provides example queries and contrasts with sequential lookups, making the purpose unmistakably clear.

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

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

The description tells when to use the tool (for comparisons) and strongly recommends it over sequential lookups. It implicitly distinguishes from the 'entity_profile' sibling but does not explicitly state when not to use it or list all alternatives.

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

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

Discloses account requirements, parallel decomposition behavior, return format (findings packet with evidence, confidence, source, gaps), and expected duration (15-60s). Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds context 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 well-structured with clear sections, but some details (e.g., full URL for signup) could be moved to documentation. It is informative without being overly verbose, earning a high score.

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 (parallel research, 1242 sources, 4774 tools), the description covers prerequisites, limitations, behavioral details, return format, and performance. No output schema exists, but description compensates fully.

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 described. The description adds value by explaining depth values (quick=3, standard=5, thorough=8 paid) and clarifying that question can be broad/multi-part. This goes beyond the schema but baseline is already high due to coverage.

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 ('decomposes', 'routes', 'returns') and clearly identifies the resource ('Pipeworx's 1242 structured data sources'). It distinguishes from sibling tools like ask_pipeworx by stating it is for broad/multi-part questions and not 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) and when not (breaking news, single lookup). Provides alternatives: ask_pipeworx for single lookup or breaking news. Also notes account requirements and free/paid tiers.

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, but the description adds behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly'. This enhances transparency without contradicting 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 then lists many domains, which is helpful for an agent. It is somewhat lengthy but every sentence contributes value, and the structure is logical.

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 6 parameters (all well-described in schema) and no output schema, the description adequately explains the return value (top-N tools with schemas and examples). It provides sufficient context for an agent to understand what the tool does and what it returns.

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

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

Schema coverage is 100% and the description does not add significant meaning beyond what the schema already provides for parameters like 'query' and its aliases. The description mentions aliases but schema already documents them, so minimal added 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 'Find tools by describing the data or task' and provides numerous domain examples, making it distinct from sibling tools which are specific actions. The verb 'discover' and resource 'tools' are 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 explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', giving clear when-to-use guidance. It does not explicitly state when not to use, but the positive context is strong.

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 readOnly, openWorld, idempotent, non-destructive hints. Description adds rich context: fans out across multiple sources, returns specific fields, and notes USPTO PatentsView API sunset with soft-fail behavior. 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 fairly long but well-structured: starts with example prompts, then purpose, behavior, returns, and input restrictions. No wasted sentences, though could be slightly more concise. Front-loaded with usage examples.

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, so description fully handles return values: lists cik, company_name, recent_filings (with URIs), fundamentals (specific fields), patents note, news, LEI. Also notes limitations. Complete for a complex tool.

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

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

Schema coverage is 100% with good descriptions. Description adds minor context (e.g., 'Only company supported today' and 'Ticker or zero-padded CIK') but mostly echoes schema. Baseline 3 justified as schema already does heavy lifting.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' with a specific verb ('profile') and resource ('US public company'). It lists data sources and returns, and distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies input requirements (ticker or CIK, not names) and directs to resolve_entity for names. Clear when-to-use and alternatives.

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

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

The description states 'Delete,' which aligns with the annotation's 'destructiveHint: true' and 'idempotentHint: true.' However, it does not add substantial behavioral context beyond what the annotations already provide, such as whether the operation is reversible or requires confirmation. Since annotations already cover the key behavioral traits, the description adds only marginal value here.

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

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

The description is concise with three sentences: one for purpose, one for usage guidelines, and one for pairing with siblings. Every sentence adds value, and there is no extraneous information.

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

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

For a simple tool with one required parameter and no output schema, the description covers the purpose, usage guidelines, and pairing. However, it lacks information about error handling (e.g., what happens if the key does not exist) or security implications. Despite this, the tool is fairly complete given its simplicity and the annotations provided.

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

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

The input schema has 100% coverage for the single required parameter 'key,' with the description 'Memory key to delete.' The tool description does not add any additional meaning beyond what the schema already provides. Therefore, it meets the baseline of 3.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory by key), distinguishing it from sibling tools like 'remember' (store) and 'recall' (retrieve). There is no ambiguity about its core 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 guidance on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall.' While it does not explicitly state when not to use it or list alternatives, the context provided is sufficient for an AI agent to make a reasonable decision.

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

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

Annotations already mark the tool as readOnly, idempotent, and nondestructive. The description adds behavioral context: it fetches the page, extracts specific elements, and outputs a single text blob ready for deployment. This goes beyond annotations by detailing the process and output 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 concise: two main sentences plus a list of use cases. It is front-loaded with the primary purpose and every sentence adds value. No redundant or missing information.

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

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

For a simple two-parameter tool with no output schema, the description covers the purpose, input, process, output format, and use cases. It provides sufficient information for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with both parameters described. The description does not add any additional semantic information about the parameters; it only mentions the URL implicitly. Baseline is 3 for high schema coverage.

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, with specific actions (fetches, extracts, emits standard format). It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitor. It implies when to use but doesn't explicitly state when not to use or mention alternatives, though context from sibling tools provides some differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds return field details and default scope (active only), but does not add significant behavioral context beyond that.

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

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

Two sentences: first states purpose and output, second provides usage guidance. 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?

Covers the essential aspects for a simple list tool with one optional parameter. Could be slightly improved by mentioning if there are any limits or ordering, but 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% with parameter description. The description reaffirms the default behavior (active only) but does not add meaning beyond the schema for the include_inactive parameter.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the return fields. It distinguishes itself from the sibling tools subscribe and unsubscribe by being the listing 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 advises when to use: 'before adding more or to find an id to cancel', which directly relates to sibling tools subscribe and 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?

Beyond annotations, the description discloses rate limiting (5 per identifier per day), that it doesn't count against tool-call quota, and is free. No contradictions with annotations (destructiveHint false is consistent with sending feedback).

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then gives guidance, then policy. Every sentence contributes essential information with no filler.

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

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

For a feedback tool with 3 parameters (2 required) and no output schema, the description covers purpose, usage, behavioral constraints, and parameter hints. It is fully complete for the agent to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds context on how to structure feedback (specific about tools/packs) but does not significantly enhance parameter meaning beyond schema. Baseline 3 plus slight improvement for usage context.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from all sibling tools as the only feedback mechanism.

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 when to use this tool (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). It also explains that feedback is read daily and influences the roadmap, guiding the agent's decision 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?

Description adds significant context beyond annotations: self-aggregating, no PII, cached 5min-1h, derived from analytics engine. Complements readOnly/idempotent hints.

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?

Concise, well-structured with bullet points. Every sentence serves a purpose. Front-loaded with main functionality.

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 sufficiently explains return types (top tools, packs, total call volume) and caching. Complete for a simple read-only 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 covers 100% with enum description, but description adds value by explaining when to use shorter vs longer windows. Adds meaning beyond schema.

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

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

Clearly states it returns top tools, packs, and call volume over a recent window. Distinguishes from siblings by focusing on trending data derived from other agents' calls.

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

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

Lists three explicit use cases (discovering hot sources, confirming canonical tools, aligning use case). Could mention when not to use, but guidance is clear and substantive.

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=false) are consistent and the description adds extensive behavioral detail: semantic anchor Jaccard ≥0.30, partition placeholder filter, fill-check against CLOB depth, and the instruction to not trade if realizable_edge_pp ≤0. No contradictions.

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

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

Well-structured with clear sections, but somewhat verbose. Every sentence adds value, though some technical details could be condensed. Still earns a high score for readability and front-loading of key points.

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 response structure (opportunities[], partition_check, fill_check), filter logic, and trade advice. Complements the input schema and annotations, leaving little ambiguity for the 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%, but the description vastly enriches parameter meaning: explains event mode expects a slug/URL, topic mode expects a seed question, provides examples, and clarifies the semantic anchor for cross-event pairs. Goes well beyond the minimal baseline.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) with distinct behaviors, effectively distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance: no args for trending scan, event slug for single-event mode, topic/seed question for cross-event mode. Explains why cross-event mode is useful (catches patterns single-event misses) and references polymarket_fill_risk for custom sizing, providing clear when-to-use and when-to-alternate advice.

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, and non-destructive behavior. The description adds substantial behavioral detail: caching (1h at KV level), diagnostic output for empty segments, and the fact that Fed bets are excluded from ranking with specific reasoning. 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 (purpose, model families, response structure, knobs). It front-loads the core purpose. While every sentence adds value, it could be slightly more concise by grouping technical details more tightly. Overall, it is organized and not wasteful.

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

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

Given the complexity (9 params, no output schema, nested concepts like model families and diagnostics), the description fully covers what an agent needs: how to interpret results (by_segment with segments explained), how to filter (knobs), and why segments might be empty (diagnostics). Caching is disclosed, and the fed-related note provides context. 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?

All 9 parameters have schema descriptions (100% coverage). The tool description adds significant extra meaning, such as explaining slippage_pp with Polymarket fee context, min_liquidity with practical guidance on walking the book, and min_partition_leg_kelly with reasons why it exists. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan') and resources ('top Polymarket markets'), and the detailed explanation of model families distinguishes it from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread.

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 'Built for "what should I bet on today"' and explains how it helps agents discover opportunities without manual paging. While it provides clear context and tradeable-edge knobs, it does not explicitly tell when not to use the tool or compare it to alternatives, though the purpose is well-understood from the 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?

The description provides extensive behavioral details beyond annotations, including response structure (tracked, expired, snapshot_dates), decay computation, and handling of gaps. 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 and front-loaded with core purpose, but it is somewhat lengthy and mixes response structure with parameter info. Still, each sentence adds value and the structure is logical.

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 thoroughly covers the response format, limitations, and edge cases (gaps, TTL), compensating for the lack of an output schema. Complete enough for an agent to understand what the tool returns.

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

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

Schema coverage is 100% with clear descriptions. The description restates parameter info (days, window) but adds minimal new semantics beyond clarifying that 'window' refers to snapshot family. Baseline of 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge longevity and distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current 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 this tool (to differentiate fresh vs. old edges) and includes limits (60-day TTL, not intraday). However, it does not explicitly list alternatives or exclusions, leaving some ambiguity about when not to use it.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, meaning the tool is safe and read-only. The description adds valuable behavioral detail: it walks the order-book ladder, returns fill quality metrics, and warns about forced directional risk and thin legs. No contradiction with annotations.

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

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

The description is dense and well-structured with clear sections for each mode. However, it is relatively long, and some details (like the exact list of return fields) could be shortened if the output schema were provided. Still, every sentence earns its place, and the structure is logical.

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 all return fields for both modes, including edge cases like thin legs and forced directional risk. It also covers usage context, parameter defaults, and the range of size_usd. No significant gaps.

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

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

Schema coverage is 100%, but the description adds crucial semantics beyond the schema: it explains the exclusivity requirement of 'market' vs 'event', the different interpretations of 'size_usd' for single-market vs basket modes, and the default auto-selection for 'side' in basket mode. This enriches understanding beyond the 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools (polymarket_arbitrage, polymarket_edges) by stating when to use it. The verb 'check' and resource 'edge against depth' are 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?

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of partial fills and unhedged positions, giving clear when-to-use and when-not-to-use context.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral context: response fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and conditions for false signals. No contradiction with annotations.

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

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

The description is dense and front-loaded with purpose, but lengthy due to thorough explanation of modes, safety fields, and warnings. While justified for complexity, 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?

Despite no output schema, the description comprehensively covers input parameters, response structure (leg-by-leg, spreads, safety fields), edge cases (compatibility_warning, temporal_alignment), and limitations ('pre-mapped ≠ tradeable'). Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by listing the 10 topic shortcuts, providing explicit parameter examples, and explaining override behavior.

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 verbs like 'auto-fetch' and 'expose'. It distinguishes itself from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on multi-venue 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 explains two modes (topic and explicit) and when to use each. Provides guidance that most pre-mapped topics return compatibility_warnings, helping agents know when not to expect tradeable spreads.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds valuable context: scoping to an identifier (IP, key hash, or account ID) 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, front-loaded with the core purpose, and 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 tool with one optional parameter and no output schema, the description sufficiently covers purpose, behavior, scoping, and relationships to sibling tools. No gaps remain.

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

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

Input schema has 100% description coverage and clearly describes the 'key' parameter as optional (omit to list keys). The description reiterates this behavior but adds no new semantic details beyond the schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, specifying the verb 'retrieve' and the resource 'saved value'. It also distinguishes itself from sibling tools 'remember' and 'forget'.

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

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

The description provides explicit when-to-use guidance: 'to look up context the agent stored earlier... without re-deriving it from scratch'. It also mentions scoping, but does not explicitly state when not to use or alternatives.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and not destructive. The description adds the time window (~last 12 hours) and specifies 'coding activity,' which provides some 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 very short (one sentence) and front-loaded with the key function and time range. However, it lacks structure and omits parameter details, making it efficient but incomplete.

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

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

Despite having an output schema (not shown) and annotations, the description fails to document the single required parameter, leaving the tool's usage ambiguous. It is not complete for effective 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 description coverage is 0%, yet the description does not mention the 'username' parameter at all. It only says 'for a user' but fails to explain the parameter's purpose, format, or constraints, leaving a significant gap.

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 'recent coding activity' with a specific time range (~last 12 hours) for a user. It distinguishes from sibling tools like 'recent_alerts' and 'recent_changes' by focusing on general coding activity.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It simply states the tool's function.

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

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

Description states mark_read:true flags events as read (a write action), but annotations declare readOnlyHint=true. This contradiction causes confusion and scores 1.

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 (3-4 sentences), front-loads the main purpose, and every sentence adds necessary information without fluff.

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

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

Despite the contradiction, the description covers what the tool returns, filtering, mark_read behavior, polling suitability, and an alternative endpoint, making it complete for an AI agent to use.

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

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

Schema covers all parameters with descriptions (100% coverage), and description adds value by providing an example for 'type' ('sec_8k') and clarifying the effect of 'mark_read'.

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 'pull' and the resource 'fired events from your subscription feed', and distinguishes it from siblings like 'recent' or 'list_subscriptions' by specifying it returns alerts with detailed fields.

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 usage hints like filtering options and mark_read behavior, and mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly exclude other tools or contrast with 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 readOnly, openWorld, idempotent, and non-destructive traits. The description adds significant behavioral context: fan-out to three sources, fallback logic (GDELT→GNews on rate limit), soft-fail for USPTO, parallel execution, and output structure. 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 a single dense paragraph that efficiently packs many details. It is front-loaded with example queries, making it scannable. While comprehensive, it could be slightly more concise, but it earns its 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?

Given the complexity (three sources, fallback, soft-fail) and lack of output schema, the description fully covers what the tool does, how it behaves, and what it returns. It also provides clear guidance on when to use an alternative tool.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters. The main description does not add substantial new information beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the tool provides a change feed for a company over a time window, fanning out to multiple external sources. It distinguishes itself from the sibling 'entity_profile' by explicitly stating when to use that alternative.

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

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

The description provides explicit example queries and directly states when to use 'entity_profile' instead: 'Use entity_profile instead when you want the static profile... regardless of window.' This clearly guides the agent on when to use this tool vs. an 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?

Adds context beyond annotations: scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous. 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?

Five sentences, front-loaded with purpose, every sentence 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?

Given simplicity of tool (2 params, no output schema), description covers purpose, usage, scoping, retention, and related tools 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%, description adds example values for keys and values, but the schema already defines both parameters clearly.

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 saves key-value pairs for later reuse, distinguishes from siblings recall and forget by naming them.

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

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

Explicitly tells when to use (discover something worth carrying forward), gives examples, and provides context about scoping and retention.

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, and openWorldHint, so the description carries a lower burden. It adds valuable context beyond annotations: the tool cascades through multiple lookup endpoints (replacing 2-3 manual lookups), auto-disambiguates company names, and returns citation URIs. No contradiction with annotations.

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

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

The description is relatively long but well-structured: it starts with example queries, states the core purpose, gives a usage directive, then details supported types. Every sentence conveys necessary information. It could be slightly more concise, but the structure is logical and front-loaded.

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 adequately explains return values for each type (including citation URIs) and mentions internal cascading behavior. It covers the essential aspects for an agent to use the tool correctly, though it omits error handling or edge cases.

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 providing concrete examples for 'value' (ticker, CIK, name; brand/generic) and explaining what each 'type' returns. This adds significant 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 clearly states the tool resolves a user-spoken name to a canonical identifier, with examples and explicit mention of supported types (company, drug). It distinguishes itself from siblings by positioning itself as the first step when an ID is needed, and the detail on what each type returns (ticker, CIK, RxCUI) further clarifies its purpose.

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 direct guidance on when to use the tool. It also lists the supported entity types. However, it does not explicitly state when not to use it or mention alternative tools, though the sibling list may imply 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 readOnly, openWorld, idempotent, and non-destructive. The description adds value by revealing the composite behavior: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations, though it does not mention the dependency on model parameters or API keys.

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, front-loaded with the main action verb. Each sentence adds meaningful information: core purpose, mechanism (calls ai_visibility_check), output, and a concrete use case. No redundant or vague phrasing.

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

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

Given the tool's complexity (composite, 4 parameters, no output schema) and rich annotations, the description sufficiently explains the input semantics (first entity as subject), the process (probes and ranks), and the output format (ranked list with score/confidence/density). All schema-described parameters are covered, and the description doesn't miss critical behavioral aspects.

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 semantic value by stating that the first entity is treated as the 'subject' for narrative and the rest as competitors. This ordering nuance is not in the schema. The description also clarifies that context disambiguates common names, reinforcing 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 tool's purpose: compare AI visibility across multiple entities side-by-side, using verbs like 'Compare', 'probes', 'ranks', and 'surfaces'. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by being specific to AI visibility and multi-entity 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?

The description explicitly gives a use case: 'competitive AI-marketing audits' with a concrete question example. It doesn't explicitly state when not to use this tool versus alternatives, but referencing ai_visibility_check implies the distinction. Clear context is provided, but lacks explicit exclusions.

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

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

Annotations indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context: partial failures, first measurement delay (5-30s), and that sources_failed lists timeouts. 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 a single dense paragraph, front-loading the core purpose and then providing usage, caveats, and return details. 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?

Given the complexity of a composite check across multiple external services, the description covers purpose, usage, edge cases (timeouts, fallback), and return fields (summary block with is_latest, license, etc.). No output schema exists, so the description adequately 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 clear parameter descriptions. The description adds semantic value by specifying scoped packages are accepted and that version defaults to latest. It also reinforces the NPM-only scope.

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 as a composite check for evaluating npm packages, naming specific services (deps.dev, bundlephobia) and the types of information returned. It distinguishes from siblings by its unique composite nature.

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 gives example queries ('is X safe / popular / small', 'what does adding lodash cost me') and states limitations (NPM only in v1, other ecosystems fall under deps.dev:version directly). Also explains graceful degradation on bundlephobia timeouts.

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, etc.), it adds specific algorithm details (BGE-base-en, cosine, 500-char windows) and truncation behavior (200K char cap with flag).

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 and usage, zero fluff, every sentence adds value.

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

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

Given 3 parameters and no output schema, the description covers mechanism, truncation, and pairing advice, making it fully informative.

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

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

Schema coverage is 100%, and description adds contextual examples for query and clarifies text parameter as 'already pulled' content, adding value beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with examples (SEC 10-K, article) and distinguishes from sibling tool ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, but does not explicitly state when not to use.

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 behavioral details beyond annotations: account requirements, delivery channel constraints (sms cap, webhook auto-disable), and type-specific parameters. Annotations already indicate non-readonly and non-destructive; description enriches but does not conflict.

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?

Efficiently front-loads purpose and return value, then organizes types with examples, and delivery channels with constraints. Every sentence adds value; no redundancy.

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

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

Covers auth requirements, multiple subscription types with parameter patterns, delivery channels with constraints, and return value. No output schema, but description sufficiently explains return. Comprehensive for a complex tool.

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

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

With 100% schema coverage, description adds significant meaning: explains type enum, gives concrete examples for each type's params, and details delivery channel limitations (phone verification, cap, webhook signature). Goes well 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' with a specific verb and resource, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types with examples, and delivery channels. Lacks explicit 'when not to use' vs alternatives, but implicit guidance from sibling tool names (e.g., recent_alerts for pull-based access) is present.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds behavioral details: it returns example questions with exact tool+argument shapes, and that calling with no arguments gives a full spread or with topic focuses. 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 efficient. It front-loads common phrasings, then precisely describes output and usage. Every sentence serves a purpose, and the length is appropriate for the tool's role as an onboarding entry point.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description fully covers usage, output, and when to invoke. No gaps or missing 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 a single optional parameter. The description adds value by listing example values ('finance', 'pharma', etc.) and explaining that omitting returns a cross-category spread. This goes beyond the schema's description, earning a point above the baseline of 3.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx. It distinguishes itself as the onboarding entry point, using specific verbs and resource description. Sibling tools like ask_pipeworx are mentioned as meta-tools to learn, reinforcing differentiation.

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

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

Explicitly advises to use this tool FIRST when uncertain about Pipeworx's capabilities or to learn about meta-tools. It describes when to use with topic parameter vs. without, and implicitly indicates when to move on to other tools. This meets the 'explicit when/when-not/alternatives' criterion.

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 non-destructive mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds that the row is deactivated, not deleted, and ownership is checked, which enriches the behavioral profile beyond annotations.

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

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

Two sentences, front-loaded with the core action, no redundancy. Every clause adds value (ownership, deactivation vs deletion, historical availability).

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?

Adequate for a simple tool with one parameter and no output schema. The description explains the effect (deactivation) and side effects (history preserved), though it could explicitly state the return value (e.g., success indicator).

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 describes the single parameter 'id' as a subscription uuid. The description adds nothing beyond stating 'by id', so it adds minimal value over the 100% schema coverage.

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') and distinguishes it from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and the deactivation behavior.

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 (cancel own subscription) and mentions ownership enforcement as a constraint. Implicitly guides against canceling others' subscriptions and clarifies that historical events remain 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?

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds that the tool returns XP data but does not disclose any behavioral traits beyond those already 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?

Extremely concise with key information front-loaded. Could include a bit more detail without becoming verbose.

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?

Has output schema (not provided) so return values are partially covered. But lacks parameter explanation and usage context. Adequate for a simple tool but with 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?

The description adds no meaning to the 'username' parameter beyond what the schema provides (which itself has 0% coverage). Examples exist in schema but not in 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?

Description clearly states the tool returns a public profile with specific data (total XP, per-language XP, per-machine XP). It distinguishes from sibling 'entity_profile' by specifying XP metrics, though it lacks an explicit verb like 'get' or 'fetch'.

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 on when to use this tool versus alternatives (e.g., 'entity_profile', 'resolve_entity'). No context about prerequisites or exclusions provided.

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 valuable behavioral details: returns a verdict with specific types, an extracted structured form, actual value with citation, and percent delta. It also mentions the tool's efficiency advantage, replacing multiple sequential calls. 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 somewhat lengthy but well-structured. It front-loads with example phrases, then states when to use, capabilities, return types, and efficiency. Every sentence adds value, though it could be slightly more concise 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 no output schema, the description adequately explains the return structure (verdict types, structured form, citation, delta). It also notes the tool's version and scope limitation (company-financial claims). This is sufficient for a single-parameter tool with comprehensive annotations.

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

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

There is a single parameter 'claim' with 100% schema description coverage. The main description reinforces the parameter semantics by providing natural-language examples of acceptable claims, adding context beyond the schema's description. This compensates for the lack of additional parameter details.

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

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

The description clearly specifies the tool's purpose: natural-language claim verification against authoritative sources, with a focus on company-financial claims. It uses specific verbs like 'verify', 'fact check', 'confirm or refute' and distinguishes itself from siblings by noting it replaces 4-6 sequential calls.

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

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

The description provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the current limitation to company-financial claims, implying when not to use (e.g., non-financial claims). However, it does not explicitly mention 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.