Data Cityofchicago

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

The description adds value beyond annotations by detailing return structure (per-model fields + combined view), cost implications for Anthropic probes, and model defaults. Annotations already indicate read-only, idempotent, and non-destructive behavior, which aligns with the description.

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, each with a distinct role: purpose/default, model options, return format, and use cases. No redundant or irrelevant information. Efficiently conveys all necessary details.

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 (4 params, no output schema) and rich annotations, the description sufficiently covers all aspects: purpose, parameter usage, output, and applicability. No missing critical information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantics for 'models' (default Workers AI) and '_apiKey' (required only for Anthropic), helping the agent understand usage. It does not add extra for 'entity' or 'context', but schema already covers those adequately.

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

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

The description clearly states the tool probes LLMs for entity awareness and scores visibility (0-100) per model, with a combined view. It distinguishes itself from siblings like 'ask_pipeworx' by focusing on multi-model visibility scoring for marketing audits.

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

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

Provides clear usage context (AI-marketing audits, brand checks, competitive monitoring) and explains default model and optional Anthropic key. However, it does not explicitly address when not to use or compare with closely related 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?

Beyond annotations (read-only, idempotent), the description reveals that the tool routes to thousands of tools, fills arguments automatically, and returns structured answers with citation URIs. This adds context about internal behavior 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 key guidance but is somewhat verbose with lists and examples. Every sentence serves a purpose but could be more concise.

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

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

Given no output schema, the description sufficiently covers behavior (routing, citation URIs) and diverse use cases. For a tool with many parameters (all aliases) and complex routing, it provides adequate completeness.

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

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

Schema coverage is 100% with clear parameter descriptions (including aliases). The description does not add further semantic detail for parameters beyond restating that it takes a natural language question. 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 that the tool answers questions about current/historical data from authoritative sources, explicitly contrasting with web search. It provides a specific verb (ask) and resource (Pipeworx) and distinguishes from sibling tools by prioritizing it over 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?

The description explicitly says to prefer this tool over web search and lists concrete query types ('what is', 'look up', etc.) with examples. It doesn't exhaustively exclude alternatives but provides clear when-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?

The description adds significant behavioral context beyond annotations: it explains the extraction process (using ONLY tool result), the structured response format with possible refusal reasons, and the one extra LLM call cost. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are not contradicted.

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 dense sentences, front-loading purpose, behavior, and output format. Every sentence adds essential information with no wasted words.

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

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

Despite lacking an output schema, the description fully explains the return structure (answer, evidence, confidence, source, refusal_reason) and provides complete guidance for high-stakes usage. It covers success and failure modes comprehensively.

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 3 is appropriate. The description mentions the question parameter accepts aliases, but this adds minimal meaning beyond the schema definitions already 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 states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads'. It specifies the verb (extract answers with evidence) and resource (data from 3,668 tools across 860 sources), and distinguishes it from the sibling 'ask_pipeworx' by noting the extra LLM call cost and use case.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and when not: 'prefer ask_pipeworx for casual lookups'. It provides clear context for tool selection relative to the sibling.

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

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

The description goes far beyond annotations by detailing resolution logic (market_match_confidence, market_match_score), fan-out behavior per category, safety mechanisms (low-confidence short-circuit, closed market handling), response shapes, and edge cases like wide spreads. This provides complete behavioral transparency.

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

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

The description is long but well-structured, with clear sections (classifiers, fan-out examples, response shapes, safety notes). Each part adds value, though it could be slightly more concise. Front-loading the core purpose helps agents quickly grasp 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?

Given the tool's complexity (multiple fan-out paths, safety logic, resolver contract, parent event extraction), the description covers all necessary aspects comprehensively. No output schema exists, but the description fully explains the response structure and 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?

The input schema already provides thorough descriptions for all three parameters (depth, market, include_raw) with 100% coverage. The tool description does not add significant new semantics beyond what the schema offers, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison), and distinguishes from sibling tools like polymarket_edges by focusing on comprehensive fan-out research.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples and hints at when to use (e.g., for comprehensive data), but does not explicitly mention when to avoid using it or compare to alternatives like polymarket_edges. Still, guidance 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). No contradictions.

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

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

Description is dense but front-loaded with example queries and key instruction. Every sentence adds value, though length could be trimmed slightly without losing meaning.

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

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

Covers entity types, data sources, count limits, sorting, and return format. No output schema exists but description indicates 'paired data + citation URIs'. Adequate for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds valuable context beyond schema: explains that type='company' pulls latest 10-K data and type='drug' pulls FAERS data, and clarifies values format (tickers/CIKs vs drug names). Slightly exceeds 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?

Description uses specific verbs ('compare', 'side-by-side comparison') and resources ('companies', 'drugs'), includes example queries, and explicitly distinguishes from sequential single-pack lookups, making the purpose crystal 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?

Description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8-15 sequential lookups, providing clear when-to-use guidance and directing away from 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, and idempotentHint. Description adds no behavioral context beyond the generic 'Search', missing details like rate limits or pagination behavior.

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 (three words) but under-specified for a search tool with three parameters. While front-loaded, it sacrifices necessary detail.

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 optional parameters and an output schema, the description lacks completeness. Missing parameter context, return value info, and usage scenarios.

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%, and the description provides no explanation of query, limit, or offset parameters. Examples in schema help but description adds no semantic 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?

Description clearly states verb 'Search' and resource 'dataset catalogue'. Purpose is straightforward but lacks differentiation from sibling search tools like query or search_within.

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 siblings such as query or search_within. Agent must infer usage from tool name alone.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral details: returns top-N tools with full input schemas ready to call. No contradiction.

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

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

Description is well-structured, front-loading purpose and usage. Each sentence adds value. Could be slightly trimmed, but no wasted words overall.

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 29 siblings, the description sufficiently explains the tool's role as a discovery entry point. No output schema, but description covers return format. Parameter count is 6 with aliases explained.

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

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

Schema coverage is 100%, so baseline is 3. Description notes aliases (q, task, search, description) but schema already documents them. No additional semantic value beyond what the schema provides.

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

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

Description clearly states verb 'Find tools' and resource 'tools' with natural language query. Distinguishes from siblings like 'search_within' and 'query' by focusing on discovery of available tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context. Does not list specific alternatives or when-not-to-use, but the guidance is strong enough.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral details: fans out across multiple sources in one call, returns specific fields (filings with URIs, fundamentals sorted by date, news via fallback), and notes the USPTO patents API has a sunset date and soft-fails. No contradictions with annotations.

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

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

The description is front-loaded with example queries and then describes the tool's capabilities. While it is lengthy, every sentence adds value. Minor verbosity could be trimmed, but overall well-structured and informative.

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

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

Given the tool's complexity (multiple sources, fallbacks, no output schema), the description is thorough. It covers all returned fields, data sources, limitations (patents sunset), input constraints, and even suggests using resolve_entity for names. This ensures the agent understands the tool's full scope.

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%. The description adds significant meaning: explains the type enum (only 'company' supported), how to format the value (ticker or zero-padded CIK, names not supported), and details the output structure (cik, company_name, filings, fundamentals, patents, news, LEI). 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 explicitly states the purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example queries (e.g., 'tell me about X', 'research Acme') and lists the resources it covers (SEC EDGAR, XBRL, USPTO, news, GLEIF), clearly distinguishing it from siblings like resolve_entity (for name resolution).

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 gives explicit guidance: 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' It also states when not to use: 'names not supported (use resolve_entity first if you only have a name).' This provides clear context for when to choose 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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and stale context, which is beyond what annotations provide, but does not add new behavioral details 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 concise sentences, front-loaded with the action, followed by usage guidance. No unnecessary words; every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, when to use, and context (pairing with siblings). It is complete and sufficient for an agent to understand correct usage.

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

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

Schema coverage is 100% and already describes the 'key' parameter as 'Memory key to delete'. The description does not add any additional semantic meaning to the parameter beyond what the schema provides.

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

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

The description clearly states the tool deletes a memory by key, uses specific verb 'Delete' and resource 'memory by key', and distinguishes from siblings like remember and recall.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with remember and recall, providing clear usage context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob.' This explains the process and output format beyond 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?

Three sentences, each serving a purpose: purpose, process, use cases. No redundant phrases or fluff. Front-loads the key action and result.

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 a simple tool with two non-nested parameters, no output schema, and comprehensive annotations, the description covers all necessary aspects: what it does, how it works, and when to use it. No gaps in understanding for an AI agent.

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

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

Schema coverage is 100% for two parameters. The description reinforces the url parameter by stating 'for any URL' and implies the max_links parameter by mentioning 'Maximum number of link entries to include' with defaults. It adds value by linking parameters to the tool's purpose.

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' and the resource 'a production-ready llms.txt file for any URL'. It distinguishes itself from sibling tools by focusing on a specific output format for AI crawlers, which is unique among tools like 'ai_visibility_check' and 'scan_competitor_ai_presence'.

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

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

The description explicitly lists three use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), providing clear context for when to use. It lacks explicit when-not or alternatives, but the use cases are specific enough.

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

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

Annotations already declare readOnlyHint and non-destructive; description adds return fields and the include_inactive parameter behavior, though no additional behavioral details needed.

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 front-load the main purpose and then add specific usage guidance, no wasted words.

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

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

For a simple list tool with one optional parameter, the description covers return values and usage context adequately without needing an output schema.

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

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

Schema coverage is 100% with a clear description of the only parameter. Description does not add further parameter meaning but provides context on return fields, meeting the baseline.

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

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

Clearly states it lists the caller's active subscriptions and enumerates the return fields, distinguishing 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?

Explicitly advises when to use: to review monitoring before adding more or to find an id to cancel, providing clear 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 clearly indicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds no additional behavioral context (e.g., what happens if the resource doesn't exist, data freshness). The description does not contradict annotations.

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

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

The description is extremely concise at only two words, but it sacrifices valuable information. It is under-specified rather than efficiently informative, failing the 'every sentence earns its place' criterion.

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

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

Given the low parameter count and the presence of a dedicated output schema (not shown), the description should still clarify what metadata is returned (e.g., timestamps, permissions) and how to interpret the single parameter. It falls far short of being 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?

With 0% schema description coverage, the description bears full responsibility for explaining the parameter 'resource_id', but it provides no details on its format, examples, or valid values. The input schema has raw types and an example but no semantic guidance.

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 'Resource metadata' is a tautology that simply restates the tool name 'metadata' without specifying the action (e.g., retrieve, update) or what resource it refers to, making it vague and unhelpful for distinguishing the tool's 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?

No guidance is provided on when to use this tool versus its many siblings (e.g., ai_visibility_check, entity_profile, resolve_entity). There are no hints about prerequisites, context, or exclusions, leaving the agent without decision support.

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 rate-limiting (5 per identifier per day) and that it's free with no quota cost. Annotations indicate read/write status; description adds actionable behavioral context. 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?

Concise, front-loaded with purpose, then usage guidelines, followed by behavioral notes. 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?

Given no output schema, the description explains the outcome (team reads digests, influences roadmap) and provides sufficient context for the tool's operation. Complete for its purpose.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description reinforces the enum types and optional context, but adds limited meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs and resources, and the examples differentiate it from sibling tools, which are mostly query/informational.

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

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

Explicitly provides when to use for bug reports, feature requests, data gaps, or praise. It also mentions rate limits and that it's free, giving clear context for usage. No exclusions, but the positive 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, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses the aggregation source, privacy, and caching behavior.

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

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

The description is concise yet comprehensive, with clear bullet points and no redundant information. 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 simple parameter set, rich annotations, and clear return description, the tool definition is fully self-contained. The agent has all necessary information to select and invoke it correctly.

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

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

Schema coverage is 100% (only one parameter with enum). The description adds further semantic value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately.

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 what the tool returns (top tools, top packs, total call volume) and specifies the time window options. It distinguishes from siblings by emphasizing that it's an aggregated trending signal rather than a direct query or discovery tool.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs) and provides guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: the semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder drops), and what happens on failure. No contradictions. The description is transparent about all key behaviors.

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 but well-structured, front-loading the requirement and then explaining modes. Every sentence adds value, but it could be slightly more concise. Still effective and not overly 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?

Given no output schema, the description describes the response structure (opportunities[], partition_check). It covers edge cases (no args, placeholder filtering, low similarity). The tool is simple (2 params, no nested objects), and the description leaves 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 coverage is 100% with descriptions for both parameters. The description adds significant meaning: examples of valid values, the context of each mode (single-event vs cross-event), and how the tool processes them. This exceeds the baseline.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and explains each. This differentiates it from sibling tools like polymarket_edges and polymarket_kalshi_spread, which likely serve different purposes.

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 warns that calling with no args fails and guides which mode to use (event for specific market, topic for cross-event scanning). It provides context for when each mode is appropriate but does not explicitly mention when to use alternatives like polymarket_edges.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: caching behavior ('Cached 1h at the KV level'), edge calculation methodology, Kelly fraction handling, and filter 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 very detailed and structured with bullet points and segment explanations. However, at over 500 words, it is quite verbose. While informative, an agent might struggle to parse the key points quickly. The front loading is good, but overall conciseness could be improved.

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

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

Given the tool's complexity (9 parameters, no output schema, three response segments), the description is remarkably complete. It explains the output structure (by_segment, fed_candidates, diagnostics), the rationale for each segment, and the edge calculation components. An agent has sufficient context 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%, so the schema already documents all parameters. The description adds significant value by explaining specialized parameters like min_partition_leg_kelly (why min_kelly doesn't apply to partition arbs) and tradeable-edge knobs (min_liquidity, max_spread_pp). It clarifies the meaning of default values and usage nuances.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx data disagreement.

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 it is 'Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets.' It provides guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and when to adjust parameters like slippage. However, it does not explicitly contrast with siblings like polymarket_arbitrage, leaving some ambiguity about 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 indicate readonly, openworld, idempotent. Description adds valuable context: compatibility warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal alignment flag, and counters for skipped comparisons. 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 lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value; no redundancy. Could be slightly more concise but structure helps readability.

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

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

Despite no output schema, description explains response fields (leg-by-leg prices, top_spreads_pp, safety fields). Covers all necessary context for a complex cross-venue tool with multiple modes and warnings. Comprehensive given 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% and describes parameters. Description adds context: explains how topic auto-fetches matching events and provides examples for explicit parameters (e.g., 'KXFED-26OCT'). Adds value but 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 the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies the resource (spread between two venues) and action (retrieve spread). This distinguishes it from siblings like polymarket_arbitrage which likely focuses on intra-venue 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?

Explicitly describes two modes (topic shortcuts and explicit event IDs) and provides guidance on when spreads are meaningful (temporal alignment true, compatibility warning absent). Warns that pre-mapped topics often return compatibility warnings, indicating when not to use. Includes criteria for when spreads are meaningless (temporal gap).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. However, the description adds no behavioral context beyond the term 'query', failing to explain return behavior, pagination, or error handling.

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 extremely concise (2 words) but underspecified. Conciseness should not come at the expense of clarity. It lacks necessary details to be helpful.

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 high parameter count (7), low schema coverage, and no param descriptions, the description is completely inadequate. Even with annotations and an output schema, the agent cannot properly invoke this tool without understanding SoQL syntax and parameter semantics.

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%, and the description does not explain any of the 7 parameters. The examples in the schema provide some context, but the description itself adds zero semantic value. The agent must infer parameter meanings solely from names like 'group' and 'where'.

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 'SoQL query' identifies a specific tool purpose (executing a SoQL query) but is too vague. It does not elaborate on what the query does or how it relates to data retrieval. It distinguishes from siblings only minimally by naming a specific query language.

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 usage context is provided. There is no mention of when to use this tool versus alternatives like 'search_within' or 'metadata'. The description lacks any guidance on prerequisites or typical use cases.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to user identifier and pairing behavior, adding value beyond annotations.

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

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

Four sentences, front-loaded with purpose. Every sentence adds value: retrieve/list, use case, scoping, pairing. No redundancy or waste.

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

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

Given simple schema, no output schema, and strong annotations, the description fully covers retrieval behavior, listing, scoping, and complementary tools. Complete 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 covers the one parameter fully. Description adds real-world examples of what keys might represent (ticker, address, notes), providing context beyond the schema's description.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', specifying verb and resource. Distinguishes from siblings 'remember' and 'forget' through pairing mention.

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

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

Explicitly states when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget. No explicit when-not, but 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?

Adds behavioral context beyond annotations by describing the return structure, the effect of setting mark_read (flags events read so next call shows newer ones), and notes that polling works fine. There is no contradiction with the annotations (readOnlyHint, openWorldHint, 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 four concise sentences, front-loaded with the primary action and return values, then filters, then additional notes. No redundant information, 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 has 5 parameters, no output schema, and annotations provide behavioral hints, the description covers all necessary aspects: what it does, what it returns, filtering options, the mark_read feature, and even provides an alternative access method. It is behaviorally complete for an agent.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds semantics by providing an example for type ('sec_8k'), specifying 'since' as an ISO timestamp, and explaining the effect of mark_read. This goes beyond the schema descriptions, justifying a score 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 pulls fired events from a subscription feed, specifies the return fields (source, citation_uri, raw event payload), and is distinct from sibling tools like 'list_subscriptions' which manage subscriptions rather than retrieve alerts.

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 guidance on filtering by type and since, explains the mark_read feature for managing read state, and mentions that polls work fine and an alternative endpoint exists. However, it does not explicitly state when not to use this tool versus siblings, though the 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 and idempotentHint. The description goes beyond by detailing the data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback behavior, and a soft-fail due to API sunset. This provides rich 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 well-structured and front-loaded with examples. It is moderately lengthy but each sentence contributes useful information. Slightly verbose for very concise standards, but still effective.

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 explains the return structure (changes[] grouped by source, total_changes, citation URIs). It covers all data sources, fallback mechanisms, and parameter quirks. Complete for a tool of this complexity.

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

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

Schema description coverage is 100%, but the description adds significant value by explaining the `since` parameter's supported formats (ISO date and relative shorthand like '7d', '30d') and the `value` parameter's acceptance of ticker or CIK. This is 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 that the tool returns a change feed for a company over a specified time window, using examples like "What's new with X". It explicitly distinguishes itself from the sibling entity_profile tool, which provides static 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 provides explicit guidance on when to use this tool (for recent changes) and when to use entity_profile instead (for static profiles). It also gives example queries that trigger the tool.

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

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

Annotations already indicate idempotent hint true and non-destructive. Description adds key details: key-value pair scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) users, which goes 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 (4 sentences), front-loaded with purpose, then usage, then behavior. 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 tool's simplicity (2 simple params, no output schema), the description covers all needed aspects: purpose, use cases, storage behavior, session handling, and pairing with recall/forget. Fully 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 covers both parameters with descriptions (100% coverage). The description does not add extra semantics beyond what the schema provides, though it does repeat the concept of key-value storage. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, specifying the verb 'Save' and resource 'data the agent will need to reuse later'. It distinguishes from sibling tools like 'recall' and 'forget' by mentioning them explicitly.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also mentions pairing with recall and forget, giving clear context and alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by noting it cascades through several lookup endpoints and replaces 2-3 manual lookups, providing 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 well-structured, starting with example queries, then usage guidance, then detailed type breakdowns. It is informative without being overly verbose; 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?

With no output schema, the description fully compensates by specifying exactly what is returned for each type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). Also mentions auto-disambiguation and internal cascading. Complete for a two-parameter 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%, baseline 3. The description adds detailed semantics for each type: for company, returns ticker, CIK, company_name, citation URI; for drug, returns RxCUI, ingredient, brand, citation. It also mentions auto-disambiguation for company inputs.

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, using verbs like 'resolve' and providing specific examples (ticker, CIK, RxCUI). It distinguishes from siblings like compare_entities and entity_profile by focusing on identifier lookup.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not explicitly state when not to use alternatives, but the context signals and sibling tool names imply distinctions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false, covering safety traits. The description adds behavioral detail: it probes each entity with ai_visibility_check, returns ranked list with score, confidence, and signal density. No contradictions. It does not mention rate limits or performance, but with annotations covering most behavior, this is acceptable.

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 front-load the main action, followed by utility context. Every sentence adds value with 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?

Given no output schema, the description sufficiently explains the return format (ranked list with score, confidence, signal density). Parameters are well-documented in both schema and description, and the example clarifies usage. The tool is complete and actionable.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds additional semantics: 'First entry treated as the 'subject' for narrative', which is not in the schema. This helps the agent understand how to use the entities parameter effectively.

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 by stating 'Compare AI visibility across multiple entities side-by-side', which specifies the core purpose with a clear verb and resource. It further explains the process: probes each entity, ranks by score, surfaces most/least recognized. This clearly distinguishes it from sibling tools like ai_visibility_check (single entity).

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 it is 'useful for competitive AI-marketing audits' and provides an example question, which indicates appropriate usage context. However, it does not explicitly state when not to use this tool or list alternatives, though the sibling list implies alternatives exist.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond by detailing: fans out to external services, partial failures degrade gracefully, initial bundlephobia measurement can take 5-30s, and sources_failed will list timeouts. This transparency helps the agent understand latency and error handling.

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 packed with useful information but is relatively long (8 sentences). It is well-structured, front-loading the purpose, then use cases, then return structure, then limitations. Could be slightly more concise, but no irrelevant content.

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

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

Despite no output schema, the description fully specifies the return structure: summary block fields, per-advisory detail, links, alternative versions. It also addresses edge cases (scoped packages, first-measurement delay, partial failures). This is complete for an agent to understand what to expect.

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

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

Schema covers both parameters with descriptions (package name, version default). The description adds no new parameter info beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the scope (NPM ecosystem only) and distinguishes from sibling tools like deps.dev:version for other ecosystems. The verb 'scan' and resource 'dependency' are well-defined with concrete examples.

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

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

Explicitly tells when to use: whenever an agent asks about safety, popularity, or size of an npm package. Also states what falls under alternative tools (deps.dev:version for non-NPM). This provides clear guidance and prevents misuse.

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 rich behavioral context beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets in results. 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?

Two clear sentences with front-loaded purpose, followed by usage, technical details, and limitations. Every sentence earns its place with zero waste.

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

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

Despite no output schema, description explains return format: top-N passages with character offsets and similarity scores. Covers truncation behavior. Complete for a 3-parameter 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 baseline is 3. Description adds meaning: explains how 'text' is used, 'query' as natural-language with examples, 'limit' default. Also clarifies max char for text beyond 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?

Clearly states semantic search inside a fetched record. The verb 'search' and resource 'text inside a record' are explicit. Distinguishes from sibling 'ask_pipeworx_grounded' by explaining 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 says to use when the record is too big for the prompt, and pairs with ask_pipeworx_grounded. Implies when not to use (small records directly in prompt) but no explicit exclusion.

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

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

The description adds significant behavioral context beyond annotations: it explains that the tool creates a resource (consistent with readOnlyHint=false), returns an ID, and details constraints like delivery caps, phone verification, and webhook signing. 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 long but front-loaded with the main purpose. Every sentence adds value, though some detail (e.g., webhook HMAC verification) could be condensed. It remains well-structured and readable.

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

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

Given the complexity of the tool (nested parameters, no output schema), the description is comprehensive: it covers all subscription types, required params, delivery channels, and constraints (phone verification, rate limits). The lack of an output schema is mitigated by stating the return value ('new subscription id').

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?

Despite 100% schema coverage, the description enriches each parameter with concrete examples (e.g., sec_8k items, polymarket_edge topic) and clarifies delivery channel behavior, adding meaning beyond the schema's brief descriptions.

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

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

The description uses a specific verb ('Create') and noun ('proactive monitoring subscription to a live-data event stream'), clearly stating the tool's function. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation of a subscription.

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

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

The description explicitly states the requirement for a Pipeworx OAuth account and outlines when each subscription type is appropriate with examples. However, it does not explicitly state when NOT to use this tool versus alternatives like '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 readOnlyHint=true, idempotentHint=true, and no destructiveness. The description adds value beyond these by disclosing that the tool returns questions with exact tool+argument shapes drawn from a live catalog, and that it serves as an entry point for meta-tools.

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 slightly long but well-structured, front-loading the purpose with example triggers. Every sentence adds value, covering triggers, return content, and parameters. It could be slightly more concise, but remains effective.

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 value (categorized example questions with tool+argument shape), the tool's role as entry point, parameter usage, and relationship to meta-tools. It is complete for 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 one optional parameter 'topic' described. The description adds extra meaning by listing example values and specifying that omitting topic gives a cross-category spread, enhancing the agent's understanding of parameter usage.

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: an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from sibling tools by focusing on learning what Pipeworx can do, not on executing specific queries.

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

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

The description explicitly says to use this tool first when unsure what Pipeworx can do, and explains when to pass the topic parameter. It provides clear context but does not explicitly state when not to use it, though the purpose is well-defined.

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

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

Adds critical context beyond annotations: ownership enforcement, deactivation (not deletion), and that historical events remain via recent_alerts. Annotations indicate mutation but not soft-delete or ownership.

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 well-structured sentences. Front-loaded with action, each sentence provides unique value with no redundancy or 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 single-parameter tool with no output schema, the description fully covers effect, ownership, and relationship to recent_alerts. No gaps remain.

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

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

Schema coverage is 100%; description adds marginal value by noting the id is 'returned by subscribe', but does not elaborate on format or constraints. Baseline 3 is appropriate.

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

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

Description uses specific verb 'cancel' with resource 'subscription by id'. Clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and soft-delete 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 ownership enforcement ('you can only cancel your own subscriptions') and explains the soft-delete effect, guiding when to use and the tool's impact on historical data.

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 behavioral context beyond annotations: it uses SEC EDGAR + XBRL, returns verdicts with specific options, and provides citation and delta. Annotations already indicate safety (readOnlyHint, idempotentHint), so description enhances transparency 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?

Description is slightly verbose but well-structured: starts with examples, states usage, domain, returns, and efficiency benefit. Every sentence adds value, but could be trimmed slightly for brevity.

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

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

Tool is simple with one parameter, good annotations, and no output schema. Description sufficiently covers domain, supported claims, return values, and efficiency. Could mention limitations (e.g., only company-financial) but overall 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?

Only one parameter (claim) with 100% schema coverage. Schema description is already clear; the description adds usage examples but no additional semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool verifies natural-language claims against authoritative sources, with specific examples and supported domain (company-financial claims for US public companies). It distinguishes itself from siblings by its unique functionality.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and notes it replaces multiple sequential calls, providing clear context. Does not mention when not to use or alternatives, but sufficient for a focused tool.

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