Vizier

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint as true, and destructiveHint as false. The description adds behavioral context: it probes LLMs, scores from 0-100, returns per-model results (score, confidence, signals, raw_response) plus combined view, and clarifies that the default model is free while Anthropic requires a BYO API key. 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 concise (two main sentences plus one for use cases) and well-structured. It front-loads the core functionality and then adds parameter details and use cases efficiently. Every sentence adds value without redundancy.

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

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

Given the tool has 4 parameters, no output schema, but moderate complexity, the description covers all key aspects: what the tool does, parameter details, return structure (per-model and combined view with specific fields), and use cases. It is sufficiently complete for an AI agent to select 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 baseline is 3. The description adds value beyond the schema descriptions: it explains the 'entity' parameter with examples, notes that omitting 'models' defaults to workers-ai, describes '_apiKey' as optional and passed through to Anthropic, and clarifies 'context' as disambiguation. This significantly aids parameter understanding.

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

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

The description clearly states it 'probes one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' This is a specific verb+resource, and the use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) distinguish it from siblings like 'scan_competitor_ai_presence' which may focus on competitors.

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

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

The description provides explicit context for when to use the tool (AI-marketing audits, pre-launch brand checks) and mentions default model and optional Anthropic integration. However, it does not explicitly state when not to use it versus alternatives, such as 'scan_competitor_ai_presence', but the use cases are clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context: it routes questions to 3,668 tools across 860 sources and returns structured answers with stable pipeworx:// citation URIs, which goes beyond the annotations.

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

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

The description is well-structured and front-loaded with the key directive. While some redundancy exists in listing many query types, it remains efficient and informative without unnecessary fluff.

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

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

Given the tool's complexity, no output schema, and the need for natural language input, the description covers the input format, the vast data sources, and the output nature (structured with citations). It is comprehensive enough for an 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 is 100% and documents all parameter aliases. The description adds the natural language aspect and provides examples, giving the agent a clearer understanding of how to formulate queries.

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: answering factual questions using authoritative structured data, with explicit examples and distinction from web search. The verb 'ask' combined with resource 'Pipeworx' and the scope of data sources is specific.

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

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

The description provides strong guidance: 'PREFER OVER WEB SEARCH' and lists many query types and examples. However, it does not explicitly state when not to use it or mention alternative tools, which would further improve clarity.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral details: explicit refusal reasons (not_in_source, no_tool_match, etc.), the return format, and the fact that it costs an extra LLM 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 a single dense paragraph. While each sentence adds value, it could be structured for easier parsing (e.g., bullet points for when to use, refusal reasons, return format). Still quite concise for the amount of information conveyed.

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 there is no output schema, the description fully explains the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible failure modes. For a high-stakes tool with many siblings, this is comprehensive.

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

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

Schema coverage is 100% with all parameter aliases documented. The description does not add extra meaning beyond what the schema provides. The tool effectively has one parameter (question) with multiple aliases, and the schema already describes those.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It explains the process (routing, fetching, extracting) and explicitly distinguishes from the sibling tool ask_pipeworx by noting the extra LLM call and appropriate use cases.

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

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

The description explicitly provides when to use (answers that will be quoted, cited, or acted on) and when not to use (prefer ask_pipeworx for casual lookups). It also mentions the cost trade-off (one extra LLM call).

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 transparently details the tool's behavior: market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread liquidity notes). Annotations already indicate read-only, idempotent, and non-destructive; the description adds significant context 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?

The description is very long (multiple paragraphs) with extensive detail. While it is well-structured with subheadings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with purpose, its verbosity reduces conciseness. Every sentence adds value, but a more streamlined version could improve 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?

Given the complexity (3 parameters, no output schema, multiple features), the description is highly complete. It covers inputs, behavioral workflow, response structure (including resolver contract, parent event extraction, news fields), safety mechanisms, and edge cases. Without an output schema, the description thoroughly explains the return format.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds context about the meaning of 'depth' (quick vs thorough) and 'include_raw' (summarized vs full payloads), but these are also explained in the schema. The description primarily elaborates on behavior rather than adding new parameter semantics 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 tool's purpose is clearly stated: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and scope (one call). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage, which have different focuses.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of fan-out for different bet types. However, it does not explicitly state when not to use this tool or list alternative tools for specific scenarios.

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, destructiveHint=false, openWorldHint=true, idempotentHint=true, covering safety and idempotency. The description adds no further behavioral context, so a baseline score of 3 is appropriate.

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 concise (5 words), but it omits usage guidance and behavioral details, so it is efficient but not fully earning its place. Score 4 for minimalism with gaps.

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 detailed schema, output schema, and annotations, the description is minimally complete but fails to explain what 'catalogue metadata' includes or how results are returned. Adequate but lacking richness.

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?

Both parameters are fully described in the schema (100% coverage), so the description adds no additional meaning. Baseline score 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 'Search VizieR catalogue metadata' clearly states the verb (Search) and specific resource (VizieR catalogue metadata), distinguishing it from siblings like 'query_catalog' and 'cone_search' which target different scopes.

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 vs alternatives like 'query_catalog' or 'cone_search'; the single-sentence description lacks context for appropriate usage.

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

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

Adds data sources (SEC EDGAR/XBRL, FAERS), metrics pulled, sorting behavior, and replacement of multiple lookups 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?

Front-loaded with examples, concise sentences, each sentence adds distinct 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?

Covers return format (paired data + citation URIs), handles both entity types, and explains sorting for comparative analysis.

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?

Adds context for type parameter (data sources for each) and values parameter (ticker/CIK for company, names for drug) beyond schema enums.

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

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

Description clearly states it performs side-by-side comparison of 2-5 entities in one call, with examples. Differentiates from sequential lookups.

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

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

Explicitly says to prefer over sequential single-pack lookups, specifies when to use (comparing entities) and what types (company/drug).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds no additional behavioral context (e.g., rate limits, pagination, source) beyond what annotations provide.

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

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

The description is extremely concise (one phrase) but sacrifices clarity and completeness. It is not well-structured to convey essential information front-loaded, as it only states the basic concept without 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 5 parameters (4 required), low schema coverage, and the need to differentiate from siblings, a single sentence is wholly inadequate. The description does not mention return values (though output schema exists), available catalogs, or parameter semantics, leaving the agent with insufficient context to use 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 description coverage is only 40% (ra and dec have descriptions). The tool description only mentions RA and Dec, ignoring catalog, radius_deg, and max. It does not compensate for the low coverage, leaving the agent without sufficient parameter 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 'Cone search around (RA, Dec)' identifies the tool as performing a spatial search on celestial coordinates, which is somewhat clear. However, it lacks a verb and does not specify what the search returns or how it differs from siblings like query_catalog or search_within, making it only moderately distinct.

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

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

No usage guidance is provided. The description does not indicate when to use cone_search versus other catalog query tools, nor does it mention any prerequisites or contexts.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are consistent. Description adds valuable behavioral context: returns top-N tools with names, descriptions, and full input schemas, ready to call directly.

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

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

The description is thorough but moderately long. It front-loads the purpose and usage, then lists categories and return format. Every sentence adds value, though it could be slightly more concise.

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

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

For a discovery tool with no output schema and 6 parameters (all documented), the description fully explains what the tool does, what it returns, and how to use it. Examples are provided, making it complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description includes curated examples and explains that query accepts aliases (task, q, description, search), adding 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's purpose: 'Find tools by describing the data or task.' It distinguishes from sibling tools by positioning itself as a meta-tool for discovery, which is unique among the sibling list.

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: 'Call this FIRST when you have many tools available and want to see the option set.' Also lists specific use cases, making it clear when to use. Lacks explicit when-not-to-use, but the context is sufficient.

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

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

Adds behavioral details beyond annotations: fans out across multiple sources, mentions patents soft-fail after May 2025, and notes names not supported. 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?

Front-loaded with examples, every sentence adds value, but slightly long. Minor deduction for 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 complexity, description is complete: covers input constraints, output contents, error modes, and precedence over other tools. No output schema but return fields 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?

Adds meaning beyond schema: explains value can be ticker or zero-padded CIK, type is only company for now. Schema coverage is 100%, but description enhances clarity.

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

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

Description clearly states it provides a full cross-source profile of a US public company, listing specific data sources and return fields. It distinguishes itself from sibling tools like resolve_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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also notes when to use resolve_entity first if only a name is 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 indicate destructiveHint=true and idempotentHint=true, which the description aligns with by saying 'delete.' However, the description adds no further behavioral details beyond what the annotations imply, such as idempotency behavior or error handling. Given the annotations' clarity, the description's contribution is adequate but not enhanced.

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

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

The description is two sentences: the first states the action, the second gives usage guidance and sibling references. It is front-loaded, concise, and contains no redundant information, earning its place efficiently.

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

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

Given the tool's simplicity (one required parameter, no output schema, clear annotations), the description covers all necessary aspects: purpose, usage context, and sibling tool relationships. It is complete for an agent to select and 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 the parameter fully described as 'Memory key to delete.' The description mentions 'by key' but adds no semantic nuance beyond the schema. Thus, the description provides baseline value without extra meaning.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory by key). It distinguishes itself from siblings by explicitly pairing with 'remember and recall,' making its role in the memory triad unmistakable.

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

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

The description provides explicit contexts for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' hinting at alternatives. However, it does not explicitly state when not to use the tool, which would make guidance more comprehensive.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds that it fetches the page, extracts title/description/links, and emits standard llms.txt markdown. No contradictions with annotations.

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

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

Two sentences plus a bullet-like list of use cases. Every sentence adds value, front-loaded with purpose. No fluff.

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

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

For a simple tool with 2 params and no output schema, the description covers purpose, behavior, output format, and multiple use cases. Output is described as a single text blob ready for deployment. Complete enough.

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 only minor context (e.g., URL can be a landing page), so it meets the baseline for high 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 a given URL, listing specific AI crawlers and the output format. It distinguishes from sibling tools like 'ai_visibility_check' by focusing on file generation rather than visibility checking.

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

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

Explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitors. Provides clear context for when to use, though it does not explicitly mention when not to use or compare to 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 read-only, idempotent, and non-destructive behavior. Description adds value by specifying return fields and the ability to include inactive subscriptions via the parameter, 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?

Two sentences, front-loaded with purpose, no unnecessary words. 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 low complexity (one optional parameter, no output schema), the description is sufficient. It lists return fields and usage context, though it might be improved by mentioning potential pagination (if any) or clarifying what 'active' means.

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

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

Schema coverage is 100% so baseline 3 is appropriate. The description does not add additional meaning for the 'include_inactive' parameter beyond what the schema already 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 it lists active subscriptions and lists return fields. It distinguishes itself from sibling 'subscribe' and 'unsubscribe' by implying it is a read-only review tool, though not explicitly naming them.

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

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

Description explicitly advises when to use the tool: to review before adding more subscriptions or to find an ID to cancel. This provides clear context for decision-making relative to sibling tools.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that resolution is via SIMBAD/NED, which is useful but does not disclose potential behaviors like rate limits, caching, or failure modes. The added value is moderate 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 a single sentence that conveys the core purpose efficiently. It is front-loaded and avoids redundancy, but lacks some contextual depth that could improve utility without significant bloat.

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 presence of an output schema (not shown), return values are covered. However, the description does not mention the astronomical domain explicitly (only by implied SIMBAD/NED), and does not address what happens when an object is not found or the expected structure. It is minimally adequate for a simple query 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 50% (only 'catalog' has a description). The description does not elaborate on parameters beyond the general query statement. The schema examples provide some usage hints, but the description itself adds no parameter-specific meaning, failing to compensate for the coverage 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 the action ('Query by object name') and the resource ('object name'), with the specific resolution method (SIMBAD/NED) providing domain context. This distinctively separates it from siblings like cone_search (spatial) or query_catalog (catalog-wide 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 implies usage for astronomical object lookups via SIMBAD/NED but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives. No exclusions or alternatives are mentioned, leaving the agent to infer from 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?

Discloses rate limit (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily. Adds value beyond annotations which only provide 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?

Every sentence adds value, but the description is longer than necessary. It is well-structured with front-loaded purpose followed by specifics.

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, the description covers all needed aspects: purpose, when to use, what to include, rate limits, and quota impact. No output schema needed for a feedback 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. The description adds extra context like '1-2 sentences typical' and 'don't paste the end-user's prompt,' which aids correct 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 it's for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools by specifying it's a feedback mechanism, not a query 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 tells when to use: bug, feature, data_gap, praise. Also says not to paste end-user prompt and describes what to include. Provides clear context for use 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds that data is aggregated from CF analytics-engine with no PII, and cached 5min-1h depending on window. This enriches transparency significantly.

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

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

Three sentences, front-loaded with the core purpose, no wasted words. The structure is efficient and easy to parse.

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

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

For a read-only simple tool with one optional parameter, the description covers what is returned, use cases, data source, privacy, and caching. No missing information 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% with well-described enum, but the description adds contextual meaning by explaining the trade-off between windows (hot vs. steady-state), going beyond the schema's basic descriptions.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on trending/popular usage.

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 use cases and differentiates between window options: shorter for hot right now, longer for steady-state demand. Provides clear guidance on when to use 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 (readOnlyHint, openWorldHint, idempotentHint) already provide safety signals, and the description adds rich behavioral context: the requirement for event/topic, the checks performed (monotonicity, partition), semantic anchor (Jaccard similarity), partition filter (placeholders), and response structure. No contradictions.

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

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

The description is thorough but slightly lengthy. However, it is well-structured with front-loaded requirement, clear separation of modes, and bullet-like details. Every sentence adds value, and there is 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 the complexity of two modes, multiple checks, and no output schema, the description is comprehensive. It covers the algorithm, filters, response fields (opportunities, partition_check), and edge cases (placeholder filtering, similarity threshold).

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 meaningful descriptions for both parameters, but the description adds significant value by explaining what each mode entails, what values to pass (slugs, URLs, seed questions), and the response format, beyond the schema alone.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, distinguishing between event mode and topic mode. It uses specific verbs and resources, differentiating it from sibling tools like polymarket_edges.

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

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

The description explicitly says 'REQUIRES one of event or topic — call with no args fails' and provides recommendations: 'event (recommended for a specific market)' and explains when to use each mode, including what cross-event mode catches that single-event misses.

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 read-only and idempotent. The description adds substantial transparency: caching behavior (KV-level 1h cache keyed on all knobs), diagnostics (why segments might be empty), and caveats (Fed signal unreliability). It fully discloses operational traits.

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

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

The description is long but well-organized with labeled sections, making it navigable. Every sentence contributes specific value; however, the length could be trimmed without loss. It front-loads the primary purpose and use case.

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

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

For a tool with 9 parameters, no output schema, and complex internal logic (three segments, diagnostics, caching), the description covers all aspects: purpose, parameter behaviors, response structure (by_segment, fed_candidates, _diagnostics), and caveats. It is exceptionally 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 good descriptions, so baseline is 3. The description adds extra context for some parameters, e.g., min_partition_leg_kelly explains that partition arbs have parent kelly_fraction_half=0, and min_liquidity clarifies applying to partitions. This elevates it above 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 defines the tool as scanning Polymarket markets to return opportunities where Pipeworx data disagrees with market price, directly addressing the use case 'what should I bet on today.' It details three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and what they produce, making the purpose unmistakable.

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

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

The description states it's 'built for what should I bet on today' and that agents discover opportunities without paging hundreds of markets, providing context. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, nor does it state when not to use it or recommend 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 mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: explains safety fields (compatibility_warning, temporal_alignment, skipped counters), response structure, and conditions for non-tradeable spreads. No contradiction with annotations.

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

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

Well-structured with sections for modes, response, safety fields. However, the text is somewhat dense and could be slightly more concise without losing essential 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 no output schema, the description thoroughly explains response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Covers all key aspects of the tool's behavior and output.

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 property descriptions. The description adds value by explaining how parameters interact (topic shortcuts vs explicit overrides) and providing the list of pre-mapped topics, which is not fully detailed in schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue comparison and explaining two modes of use.

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 when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility_warning, advising against assuming tradeability. Also explains when spreads are mathematically meaningless (temporal_alignment:false).

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, so the safety and idempotency profile is clear. The description adds 'rows of a single catalogue' but does not elaborate on return format or other behaviors. Minimal additional 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?

The description is a single, front-loaded sentence that conveys the core purpose efficiently. No unnecessary words or repetition.

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 that an output schema exists and annotations cover safety, the description is largely sufficient for a simple query tool. However, it lacks explicit differentiation from 'catalogs' and could clarify constraint syntax. Still, the example partially compensates.

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 75%, with good descriptions for 'max', 'columns', and 'constraint'. The tool description adds a usage example ('I/345/gaia2' for 'catalog') but does not provide additional semantic meaning beyond what the schema already offers. 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 operation ('Query rows of a single catalogue') and gives a concrete example catalog ID ('I/345/gaia2'). This distinguishes it from sibling tools like 'catalogs' (likely listing) and 'cone_search' (spatial query).

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

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

The description implies usage for querying a specific catalog but provides no explicit guidance on when to prefer this tool over alternatives like 'cone_search' or 'catalogs'. No exclusions or when-not-to-use are mentioned.

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 destructiveHint=false. The description adds behavioral context about scoping (anonymous IP, BYO key hash, or account ID) and what happens without a key (list all keys), which is useful beyond the annotations.

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

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

The description is three sentences with no wasted words. It front-loads the primary action and includes key behavioral details efficiently.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, behavior, scoping, and relationships with siblings completely.

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

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

Schema coverage is 100% with one optional 'key' parameter. The description reinforces the schema by explaining the behavior when the key is omitted. No additional parameter-level details are provided, 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?

The description clearly states the tool retrieves a saved value or lists all keys (with key omitted). It distinguishes itself from sibling tools 'remember' (save) and 'forget' (delete) by explicitly naming them.

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

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

The description explains when to use the tool: to look up context stored earlier without re-deriving it. It also notes scoping to a user identifier. It does not explicitly state when not to use it, but it is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: return structure (source, citation_uri, raw payload), filter parameters, and the mark_read effect ('flag returned events read so the next call only shows newer ones'). 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 concise (3 sentences), front-loaded with the main purpose, and each sentence adds useful information. It could be slightly tighter but is efficient 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?

Though no output schema exists, the description mentions return fields (source, citation_uri, raw event payload). It also provides an alternative access method (alerts.json endpoint) and notes that polling works fine. For a read-only fetch tool, this is fairly 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 5 parameters, each having a description. The tool description adds value beyond the schema by explaining the effect of 'mark_read' (future calls only show newer) and providing an example for 'type' (e.g., 'sec_8k').

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 'Pull fired events from your subscription feed' – a specific verb and resource. It differentiates from siblings like 'list_subscriptions' by focusing on fired events and mentions an alternative REST endpoint, implying a distinct 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 provides context for using the tool: polling works fine and an alternative URL exists for scripts/dashboards. It does not explicitly state when not to use it or compare to other tools, but the guidance is clear enough for an agent.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds source fan-out logic, fallback mechanism, output structure (changes grouped by source, total_changes, citation URIs), and parameter format details. 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 a single dense paragraph but well-organized with front-loaded examples. Every sentence adds value. Slightly long but appropriate for complexity; could benefit from bullet 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 the complexity (multiple sources, fallback, output format), the description covers all essential aspects: source behavior, error handling, parameter details, and return structure. No output schema, but description compensates.

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. Description adds relative shorthand examples for `since`, explicitly restricts `type` to 'company', and gives examples for `value` (ticker or CIK). Adds recommended default for `since`.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, listing specific sources (SEC, GDELT/GNews, USPTO) and example queries. It distinguishes from sibling tool 'entity_profile' by contrasting dynamic vs static profile.

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

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

Explicitly contrasts with entity_profile for static profile needs. Provides example queries and notes fallback behavior (GDELT→GNews) and soft-fail for USPTO. Gives recommended `since` values ('30d', '1m').

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 value beyond annotations: explains scoping by identifier, persistence for authenticated vs anonymous sessions, and non-destructive nature. Annotations already indicate idempotent and non-destructive, but the description adds contextual details.

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

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

Five sentences with no wasted words. Front-loaded with purpose, then usage, then behavioral details. Structured logically and easy to scan.

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?

Completely adequate for a simple write tool with two parameters. Covers purpose, usage, persistence behavior, and pairing with sibling tools. No missing information given the lack of 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 already has 100% coverage with clear descriptions for key and value. The description adds naming conventions and value types, which is helpful but does not significantly enhance understanding beyond schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' which is a specific verb+resource. It distinguishes from siblings by mentioning pairing with recall and forget, and specifies cross-session persistence.

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 when to use ('when you discover something worth carrying forward') with examples. Does not explicitly exclude cases, but provides clear context and references sibling tools for retrieval/deletion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds transparency about internal cascading lookups and that it replaces 2-3 manual steps, providing useful behavioral context beyond annotations.

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

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

The description is well-structured, front-loaded with example queries and clear purpose. It contains some redundancy (e.g., restating supported types in multiple places) but remains focused and informative without unnecessary fluff.

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

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

For a tool with only two parameters and no output schema, the description fully covers the purpose, input formats, return values for each type, and usage context. It mentions citation URIs and internal cascading, making it complete for an 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 description coverage is 100%, so baseline is 3. The description adds significant value by providing concrete examples for each parameter (e.g., 'ticker (AAPL)', 'CIK (0000320193)', 'ozempic', 'metformin') and clarifying which input forms are accepted for each type, which goes beyond the schema's generic descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific verb+resource ('resolve a user-spoken NAME to the canonical/official identifier'). It provides example queries and distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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 using this tool first when a name is present but an ID is needed. It lists supported entity types and explains the input formats. However, it does not explicitly mention when not to use it or name alternative tools, though the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and idempotency are clear. The description adds behavioral details: probing each entity, ranking by score, returning a ranked list with score/confidence/signal density. It does not cover error handling or rate limits, but given annotation coverage, this is adequate.

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 consists of three efficient sentences: purpose, mechanism, and a concrete use case example. No extraneous information; every sentence earns its place. It is front-loaded with the core function.

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 clearly states the return format (ranked list with score, confidence, signal density). It mentions dependency on ai_visibility_check. It does not cover edge cases or limits, but for a comparison tool with good annotations, it is reasonably 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 descriptions cover all 4 parameters (100% coverage). The description adds value by explaining that entities' first entry is treated as subject and rest as competitors, and that context is shared across probes. This enriches meaning beyond the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes, ranking, and surfacing most/least recognized. It gives a concrete use case (competitive AI-marketing audits) and distinguishes from the sibling ai_visibility_check, which operates on a 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 provides clear context for when to use this tool (competitive audits comparing multiple entities) and implies it's an aggregate of ai_visibility_check. However, it does not explicitly state when not to use it or mention alternatives like compare_entities. The context is sufficient but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds behavioral details about partial failures (degrading gracefully), timing (bundlephobia first measurement takes 5-30s), and error reporting (sources_failed). 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 well-structured, front-loading the main purpose. Every sentence adds value, though it is somewhat lengthy. No fluff, but 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?

No output schema exists, so description must explain return format. It details summary block fields, per-advisory detail, links, and alternative versions. Also covers partial failures and timing, making it complete for agent decision-making.

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

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

Input schema covers both parameters with 100% coverage. Description adds meaning by noting scoped packages are accepted for 'package' and that 'version' defaults to latest published when omitted. Provides extra context beyond schema.

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

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

Description clearly states it's a composite check for adding an npm package, covering license, advisories, version history, and bundle size. Distinguishes from siblings by being a single-call all-in-one check, which none of the other tools provide.

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 an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also specifies scope (NPM only in v1) and directs which sibling tools cover other ecosystems (deps.dev:version).

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?

Goes well beyond annotations by detailing return format (passages with character offsets and similarity scores), embedding model (BGE-base-en), chunking (500-char overlapping windows), and input cap (200K chars with truncation flag). This enriches the agent's understanding of tool 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 succinct (6 sentences), front-loaded with the core action, and every sentence provides essential information without redundancy.

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

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

Despite having no output schema, the description explains what is returned and key constraints. It is complete for a tool of this complexity, covering edge cases like truncation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example queries for the query parameter and restating the character limit, which clarifies usage beyond the schema.

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

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

The description clearly states the verb ('semantic search') and resource ('inside a fetched record'). It distinguishes from siblings by mentioning its pairing with ask_pipeworx_grounded, making it evident what this tool does uniquely.

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 the record is too big to cram into the prompt') and when not via alternatives ('Pairs with ask_pipeworx_grounded'). Provides clear context for appropriate invocation.

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

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

Annotations (destructiveHint=false, idempotentHint=true) are supplemented by details on OAuth requirement, return of subscription id, webhook key delivered once, and per-event SMS cap. 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 dense but well-organized, front-loading the main purpose. Minor points: could benefit from bullet formatting for 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?

Given the complexity (3 params, nested objects, multiple types/delivery options), the description covers prerequisites, type-specific filters, delivery constraints, and webhook details comprehensively. No gaps identified.

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

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

Schema coverage is 100%, and the description adds rich examples for each type and delivery channel, including validation rules (e.g., phone verification, webhook HMAC) beyond schema definitions.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream,' clearly stating the action and resource. It 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?

The description specifies prerequisites (OAuth account), supported types with parameters, and delivery channel limitations. It lacks explicit 'when not to use' guidance but provides sufficient context for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns example questions with exact tool+argument shapes drawn from a live catalog, explaining the output structure and the fact that it doesn't mutate state. 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 relatively long but front-loaded with key user-facing phrases and structured with examples. Every sentence serves a purpose: defining the tool, listing example questions, explaining output, and giving usage advice. Minor redundancy (e.g., repeated 'what can I ask') but overall efficient.

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

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

Given the tool's simplicity (one optional parameter, no output schema, clear annotations), the description is fully complete. It explains what the tool does, when to use it, what arguments to pass, and what the return value looks like (category-bucketed questions with tool+argument shapes). No gaps.

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

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

Schema coverage is 100% for the single optional parameter 'topic'. The description adds meaning by providing example values ('finance', 'pharma', 'betting') and explaining the effect of omission (cross-category spread) vs. focus (narrow results). This goes beyond the schema's basic 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: it's the onboarding entry point for a new agent, returning example questions bucketed by category. It uses specific verbs and resources (returns category-bucketed example questions, drawn from live catalog) and distinguishes itself from siblings like discover_tools and ask_pipeworx by positioning it as the first tool to use when unfamiliar with 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?

The description explicitly tells when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also provides guidance on arguments (call with no arguments for full spread, pass topic to focus) and mentions alternatives (meta-tools like ask_pipeworx, entity_profile, compare_entities).

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

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

Discloses that row is deactivated (not deleted), adding context beyond annotations which only indicate non-destructive write.

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—purpose first, then key behavioral details. 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?

Fully covers ownership, effect, and relation to sibling tools for a simple 1-param 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 already documents the 'id' parameter; description adds value by linking it to 'subscribe' return 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?

Clear verb+resource: 'Cancel a subscription by id.' Distinguishes from sibling 'subscribe'.

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?

Specifies ownership enforcement ('you can only cancel your own subscriptions') and mentions alternative for historical events via 'recent_alerts'.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: it reveals the tool is 'v1', supports only company-financial claims (revenue, net income, cash position) for public US companies, uses SEC EDGAR + XBRL as data sources, and returns a verdict with details like percent delta and pipeworx:// citation. This enriches the agent's understanding 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 concise yet comprehensive. It opens with attention-grabbing trigger phrases, clearly states the purpose, specifies scope and data sources, describes return values, and highlights efficiency benefits. Every sentence adds distinct value—no redundancy or filler. The structure is front-loaded with the most critical information for tool selection.

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 no output schema, the description fully explains the return structure: verdict (with specific categories), extracted structured form, actual value with citation, and percent delta. It also addresses the tool's replacement of multiple sequential calls. Given the tool's moderate complexity and rich annotations, the description provides all necessary contextual information for correct 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?

The input schema has 100% description coverage for the single 'claim' parameter, including an example. The tool description reinforces the parameter's meaning by listing example claim formats and specifying the supported domain (company-financial). While the schema already documents the parameter well, the description adds extra context about the nature of acceptable claims, earning a score above 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 starts with clear trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and specifies the tool's purpose: natural-language claim verification against authoritative sources. It also explicitly states the scope (company-financial claims for public US companies) which distinguishes it from sibling tools like ask_pipeworx or ask_pipeworx_grounded that handle more general 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and notes the tool replaces 4–6 sequential calls, implying efficiency. While it doesn't explicitly state when not to use it, the specific scope (company-financial claims) serves as an implicit exclusion. Sibling tools like search_within or remember provide alternative contexts, but no direct comparison is given.

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