Crystallography

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds crucial details: the default model, the BYO key arrangement for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} plus combined view). No contradictions with annotations.

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

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

The description is a single, concise paragraph of about 70 words, front-loaded with the primary action and outcome. Every sentence adds value—default model, optional Anthropic, return format, use cases. No redundant or filler 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?

Given no output schema, the description adequately explains return values (per-model details and combined view). It covers parameters, default behavior, and use cases. However, it omits potential considerations like idempotency (whether repeated probes yield same results) or rate limits, but these are partially addressed by annotations. Overall sufficient for safe 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 covers all 4 parameters with descriptions, achieving 100% coverage. The description further clarifies the relationship between models and _apiKey ('pass _apiKey to also probe Anthropic') and provides concrete examples for entity ('Pipeworx', 'OpenInvoice'). This adds meaning beyond the schema.

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

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

The description clearly states the tool's action: 'Probe one or more LLMs for what they know... and score visibility.' It specifies the resource (knowledge of a business/brand/product/topic) and distinct outcome (score 0-100). Among siblings like ask_pipeworx and compare_entities, this tool's unique function—visibility scoring across models—is well-defined.

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

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

The description provides explicit usage contexts: 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model behavior and the need for an _apiKey for Anthropic. While it doesn't explicitly list when not to use or contrast with siblings, the context is clear enough for an agent to decide.

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

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

Annotations already indicate readOnly, idempotent, open-world, and non-destructive traits. The description adds valuable context: the tool routes questions to many sources and returns structured answers with citation URIs. It doesn't discuss latency or failure modes, but the added transparency about the output format and sourcing is significant given the annotations already cover safety.

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

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

The description is moderately lengthy (over 100 words) but well-structured: the first paragraph establishes the tool's value proposition and scope, the second gives explicit usage triggers and examples. Every sentence adds value, though some redundancy exists (e.g., listing many data types). Overall it is efficient for the 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 the absence of an output schema, the description adequately explains the return type (structured answer with citations). It covers purpose, usage guidelines, and parameter semantics thoroughly. It does not address error scenarios or limitations, but for a tool that routes to many others, the provided context is sufficient for an agent to decide 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?

The input schema covers 100% of parameters with descriptions. The description goes beyond by providing examples of appropriate questions and specifying the natural language nature of the input. This helps the agent understand the expected content and format, adding practical semantics beyond the schema's alias listing.

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 factual questions using verified sources and returns structured answers with citations. It mentions specific domains (SEC filings, FDA, etc.), establishing a clear purpose. However, it does not differentiate itself from the sibling 'ask_pipeworx_grounded', which appears to be a closely related tool, slightly reducing clarity.

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 recommends preferring this tool over web search for a wide range of factual queries and provides concrete examples of when to use it ('what is', 'look up', 'find', etc.). It gives clear usage scenarios, covering both the types of data and the phrasing triggers, leaving no ambiguity about when to invoke it.

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

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

The description adds behavioral details beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains the tool picks the right tool from many sources, fills arguments, fetches data, and extracts answers only from the tool result, with explicit refusal reasons. No contradiction with annotations.

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

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

The description is a single paragraph that efficiently front-loads the purpose and key details. Every sentence adds value, though it could be slightly more structured (e.g., bullet points). Still, it is concise with no 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 the complexity (routing among many sources, structured return with evidence and refusals, no output schema), the description is complete. It covers purpose, usage, behavior, return format (including specific refusal reasons), and cost comparison with sibling tool.

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

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

The input schema has 100% description coverage, with each alias documented. The description does not add new meaning beyond what the schema provides for the parameters. Baseline 3 is appropriate as the schema already fully explains the parameters.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes like 'ask_pipeworx' but extracts answers only from tool results. It specifies the return format and distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call cost.

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 when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides examples like financial verdicts, legal claims. It also recommends preferring 'ask_pipeworx for casual lookups' due to the extra cost, giving clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description goes far beyond by detailing resolution logic (market_match_confidence, low-confidence short-circuits, closed market handling), classifier behaviors, fan-out examples, response shapes, parent event extraction, news fields with fallback info, and safety mechanisms (wide spread tradeability). This is comprehensive behavioral disclosure with 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 long and detailed, which is appropriate for a complex tool, but it could be more concise. The key purpose and usage are front-loaded, but subsequent paragraphs delve into many specific behaviors and edge cases. Every sentence adds value, but overall length reduces scannability.

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

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

Given the tool's complexity (multiple input types, classifiers, fan-out patterns, response fields, safety mechanisms), the description is remarkably complete. It covers resolution, evidence sources, edge cases (low confidence, closed markets, wide spreads), and even internal resolver contract details. With no output schema provided, the description compensates fully, leaving little ambiguity.

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

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

Despite 100% schema coverage, the description adds significant value: it explains the 'market' parameter input types (slug, URL, question text) with examples, clarifies 'depth' enum values ('quick' vs 'thorough') and default, and details when to use 'include_raw' (false recommended, true for specific needs). These insights beyond the schema are crucial for correct 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It uses specific verbs (research, pull, resolve, classify, fan out, return) and distinguishes from siblings like ask_pipeworx by being specialized for Polymarket bets. The target audience understands exactly what they get.

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

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

The description provides explicit usage examples ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives fan-out examples for different bet types. However, it does not explicitly state when NOT to use this tool or mention alternatives from the sibling list, which would further clarify boundaries.

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 true, and destructiveHint false. Description adds context about data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting, and citation URIs. This complements annotations well 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 relatively lengthy but every sentence adds value, starting with example queries, then explaining behavior for each type, then noting output details. It could be slightly tighter, but it is well-structured and front-loaded with key usage phrases.

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

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

Given no output schema, description fully explains return structure: paired data + citation URIs per entity, sorted by primary metric. It covers both company and drug types in detail, including handling of fiscal year variations. The tool replaces 8-15 sequential lookups, showing efficiency benefit. Complete for its 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 both type and values described. Description adds meaning by specifying what data each type pulls (e.g., revenue, net income for company; adverse-event counts for drug) and constraints (2-5 items). This goes beyond the schema's enum and array description.

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

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

Description clearly states the tool conducts side-by-side comparisons of 2-5 companies or drugs, with explicit example phrases like 'compare X and Y' and 'X vs Y'. It distinguishes from sequential single-entity lookups by stating 'ALWAYS PREFER' over such approaches, leaving no ambiguity about 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?

Description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. However, it does not explicitly mention when NOT to use (e.g., for single entity lookups) or name alternatives like entity_profile, though the sibling list includes it. Still, the guidance is strong and actionable.

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=true, idempotentHint=true, and destructiveHint=false, indicating safe repeated calls. The description adds behavioral context: it returns 'top-N most relevant tools with... full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed'. No contradiction with annotations.

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

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

The description is a single paragraph of about 4 sentences, front-loaded with the core purpose. Every sentence adds distinct information: purpose, usage context, return value specifics, and a call to action. While slightly verbose, it is well-structured and efficient for the information delivered.

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 discovery nature and lack of output schema, the description fully explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas'. It also provides example queries and clarifies that results are executable without further lookups. No gaps remain.

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

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

Schema coverage is 100% with each parameter described. The description adds value by specifying that the query parameter accepts 'natural language description' and lists example queries like 'analyze housing market trends'. It also reveals aliases (task, q, search, description), which go beyond the schema's individual property descriptions.

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

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

The description clearly states the tool's function: 'find tools by describing the data or task'. It provides numerous specific examples (SEC filings, financials, FDA drugs, etc.) and explicitly mentions returning 'top-N most relevant tools with names, descriptions, and full input schemas'. This distinguishes it from sibling tools like search_within or get_structure.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set'. It also says 'Use when you need to browse, search, look up, or discover what tools exist'. While it doesn't explicitly state when not to use it, the guidance is clear and context-appropriate.

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 and destructiveHint=false, but the description adds valuable behavioral details: fans out across multiple sources, returns specific fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), mentions the USPTO PatentsView API sunset in May 2025 with soft-fail behavior, and notes the GDELT→GNews fallback. 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 dense but every sentence adds value, front-loaded with example queries. Despite length, it remains structured and easy to parse. 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?

No output schema exists, so description compensates by fully explaining return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and limitations (patents sunset, name not supported). Given the complexity of a multi-source profile, this is highly 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 100% of parameters (type and value). Description reinforces meanings: type only 'company' for now, value as ticker or zero-padded CIK. It adds context that names are not supported, which goes beyond schema. Baseline 3, plus extra context justifies 4.

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

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

Description starts with multiple example queries ('Tell me about X', 'research Acme') and clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call'. It lists the specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, making the purpose very specific and distinguishing it from sibling tools like compare_entities or 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 states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing clear when-to-use guidance. Also warns that names are not supported and recommends using resolve_entity first if only a name is available, giving precise when-not-to-use instructions.

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 destructiveHint=true and idempotentHint=true. The description confirms deletion but does not add significant behavioral context beyond what annotations provide. No contradictions.

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

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

Two sentences, front-loaded with the action, no wasted words. Efficient and clear.

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 one parameter, no output schema, and comprehensive annotations, the description fully covers what is needed. It includes purpose, usage guidelines, and sibling context.

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 'key' described as 'Memory key to delete'. The description only mentions 'by key' without adding extra 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 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific, and among siblings like 'remember' and 'recall', it is distinct as the deletion counterpart.

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

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

Explicitly states when to use: 'context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember' and 'recall,' providing clear guidance on 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, so the agent knows it's a safe, read-only, idempotent operation. The description adds key behavioral context: it fetches the page, extracts specific elements, and outputs a standard format. 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 concise (3 sentences) and front-loaded with the main action. Every sentence adds value: verb+resource, process explanation, and use cases. 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 the tool's simplicity (2 parameters, no output schema, strong annotations), the description fully covers purpose, behavior, parameters, and use cases. It is complete and leaves no significant gaps 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 description coverage is 100% with clear parameter descriptions. The description adds value by elaborating the url parameter with an example and clarifying max_links defaults and limits, which goes beyond the schema.

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

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

The description clearly states the verb ('Generate') and resource ('llms.txt file'), specifies the target audience (AI crawlers), and outlines the output format. It distinguishes itself from sibling tools by focusing specifically on llms.txt generation, while siblings address different concerns like AI visibility or competitor scanning.

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 (getting a client's site indexed, drafting for own project, auditing competitors), providing practical context for when to use the tool. It does not mention when not to use it or alternatives, but given the distinct sibling set, this 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the specific return fields (compound name, formula, space group, cell parameters, bibliographic info, CIF link) beyond annotations.

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

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

Three sentences, front-loaded with purpose, then lists return fields. No unnecessary words, efficient and well-structured.

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

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

For a simple lookup tool with one required parameter and no output schema, the description fully covers what the tool does and returns. It mentions all return fields, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% (one parameter well documented). The description adds an example ('1009000') but no additional semantic depth beyond the schema, hence baseline 3.

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

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

The description clearly states the tool looks up a single crystal structure by numeric COD ID, specifying the resource (Crystallography Open Database) and distinguishing from sibling 'search_structures' which is used for searching.

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 mentions 'Keyless' (no API key needed) and implies usage when a specific COD ID is known. It does not explicitly state when not to use, but the sibling 'search_structures' covers the searching alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which cover safety and idempotency. The description adds value by detailing the returned fields and the default behavior (active only), with 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 two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, well-structured for quick understanding.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides adequate context. It lists all returned fields and the usage scenario. Minor lack of pagination info does not significantly detract.

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 single parameter 'include_inactive' is fully described in the input schema (100% coverage). The tool description does not add additional semantic information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates the returned fields (id, type, params, etc.). This specific verb-resource pair distinguishes it from siblings like subscribe and unsubscribe.

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

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

The description explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It provides clear context and implicitly contrasts with sibling tools for adding or removing subscriptions.

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

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

Annotations are all false, so description carries the burden. It discloses rate limits (5 per day), quota-free usage, and implies non-destructive nature. Does not mention confirmation or queuing but is sufficient for a simple feedback action.

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

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

Description is a single paragraph but efficiently packs purpose, usage, constraints, and impact. Each sentence contributes, and critical info is front-loaded.

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

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

Given no output schema, the description adequately covers when and how to use, constraints, and expectations. Return value omission is acceptable for a feedback tool; otherwise 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 all parameters with descriptions (100%). Description adds value by advising on message specificity, length (1-2 sentences, 2000 chars), and how to use the context field, enhancing 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 the tool is for sending feedback to the Pipeworx team, categorizing it into bug, feature, data_gap, or praise. It distinguishes itself from all sibling tools as the only feedback mechanism, using specific verbs like 'tell' and 'use when'.

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 criteria for each feedback type (bug, feature, data_gap, praise), what to avoid (don't paste prompts), and includes rate limits and quota impact, aiding agent decision-making.

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: cached (5min-1h), self-aggregating, no PII, derived from analytics engine. Annotations already declare safe read operations; description enriches with performance and data origin 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?

Three concise sentences plus bullet-like use cases. Front-loaded with purpose, then specifics, then examples. Every sentence earns its place; 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 one parameter and no output schema, description covers purpose, use cases, data source, caching, and parameter semantics. Complete and self-contained.

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 parameter fully with enum and description. Description adds semantic explanation: 'shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing meaning beyond schema.

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

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

Description clearly states verb 'returns' and resource 'top tools, top packs, total call volume'. Specific verb+resource, distinguishes from sibling tools like discover_tools by focusing on trending data.

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

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

Provides three explicit use cases (discovering hot data, confirming canonical choice, aligning use case). No explicit exclusions, but context is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: monotonicity checks, partition-sum computations, placeholders filtering, and semantic similarity requirements, all 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 moderately long but well-structured: starts with requirement, then purpose, then detailed mode explanations, and ends with response format. While every sentence adds value, slightly 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 fully explains return fields (opportunities array, partition_check object). It covers all necessary context for correct tool usage, including error conditions and filtering logic.

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 have schema descriptions (100% coverage). The tool description adds significant context: examples of event slugs and topic seeds, mode behavior, and how each parameter affects processing, far exceeding baseline value.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) and effectively differentiates from sibling tools like polymarket_edges and polymarket_kalshi_spread.

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

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

The description explicitly requires one of 'event' or 'topic' and warns that call with no args fails. It recommends 'event' for specific markets and 'topic' for cross-event scanning, explaining advantages and conditions like Jaccard similarity threshold.

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 behavior. The description goes far beyond by detailing caching (1h at KV level), response structure with segments and diagnostics, edge calculation methodologies, and tradeable-edge knobs. 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 long and dense with technical details, which may overwhelm some agents. While it is front-loaded with the main purpose, it is not concise. Every sentence adds value, but the overall length could be reduced.

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

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

Given the complexity (9 parameters, no output schema), the description is extremely comprehensive. It covers response structure, diagnostics, caching, model details, tradeable-edge filters, and limitations (e.g., Fed data unreliability). It fully compensates for the missing 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?

All 9 parameters have descriptions in the schema, but the description adds significant value beyond schema definitions. For example, it explains why min_partition_leg_kelly is needed alongside min_kelly and how tradeable-edge knobs like max_spread_pp and min_liquidity work in context.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, for the use case of 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge detection using specific model families.

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 (discovering opportunities without paging hundreds of markets) and provides context for when not to rely on it (e.g., Fed bets are excluded due to unreliable data). However, it does not explicitly list alternative tools for different 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 declare the tool is read-only, idempotent, and non-destructive. The description goes far beyond these by detailing response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning reasons, temporal_alignment, skipped counters), and behavioral nuances (non-equivalent bet shapes, temporal misalignment). No contradictions exist.

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

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

The description is comprehensive and front-loaded with purpose, followed by modes, response, and safety fields. Every section adds necessary context, though some redundancy exists (e.g., repeating compatibility_warning conditions). For a tool with rich behavior, the length is justified, but slight trimming could improve conciseness.

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

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

Without an output schema, the description fully explains the response structure (leg prices, spread array, safety fields) and all edge cases (non-equivalent shapes, temporal gaps). It covers both modes, parameter interaction, and caveats like pre-mapped ≠ tradeable. Completeness is excellent for a tool with 3 parameters and no required fields.

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

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

Schema description coverage is 100%, with each parameter described. The description adds value by explaining mode interaction (topic vs explicit tickers, override behavior) and providing examples. While schema already documents, the description clarifies semantics and use cases, earning 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 states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. This distinguishes it from siblings like polymarket_arbitrage (intra-venue) and polymarket_edges (same venue patterns). The verb 'spread' and resource 'Polymarket–Kalshi' plus the qualifier 'same resolving question' make the purpose specific and unambiguous.

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

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

The description explains when to use it: to compare prices across venues for equivalent outcomes, with two modes (pre-mapped shortcuts or explicit tickers). It also warns that pre-mapped topics often yield compatibility warnings and that spreads are only meaningful when temporal_alignment.aligned is true. However, it does not explicitly compare with alternative tools or state when not to use it versus other polymarket tools, leaving a minor 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=true and idempotentHint=true, so the tool is clearly a safe read operation. The description adds valuable context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and how it pairs with remember/forget.

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 highly concise, with three sentences front-loaded with the main action. No wasted 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?

While there is no output schema, the description explains both modes (with and without key) and scope, which is sufficient for a simple retrieval tool. Minor omission: no mention of behavior when key is not found.

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 single parameter 'key'. The description reiterates the schema's meaning (omit to list all keys) without adding deeper semantics, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('Retrieve' or 'list') and the resource ('value previously saved via remember' or 'all saved keys'), and distinguishes itself from sibling tools like 'remember' and 'forget'.

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

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

The description provides clear use cases (e.g., looking up stored context like ticker or address) and mentions scoping and pairing with other tools, but does not explicitly state when not to use or list alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds details on return fields (source, citation_uri, raw payload), filtering by type/since, and mark_read effect on subsequent calls. 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?

Four sentences, front-loaded main purpose, then details return fields, filtering, mark_read, and alternative access. No fluff, 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?

Despite no output schema, description explains what the output contains. Covers filtering, mark_read, polling, and alternative URL. Edge cases not addressed, but sufficient for selection and invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds value with example for type ('sec_8k'), explanation that since is ISO timestamp, and clarifies mark_read behavior ('flag returned events read so the next call only shows newer ones'). Not all parameters elaborated, but enough.

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 'Pull fired events from your subscription feed' with specific verb and resource. Distinguishes from siblings like 'list_subscriptions' and 'recent_changes' by focusing on events from a subscription feed.

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: 'Polls work fine' and offers an alternative method via URL. Explains mark_read behavior on future calls. Could add when-not-to-use vs siblings, but overall good.

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. The description adds valuable context: multi-source fan-out (SEC, GDELT→GNews, USPTO), fallback logic, soft-fail for USPTO, and return structure with grouped changes and citation URIs. No contradictions.

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

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

The description is detailed but well-structured: starts with example queries, then explains sources, parameter details, return info, and sibling comparison. It is front-loaded with the main purpose. Could be slightly more concise but 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 count, citation URIs). It covers error/fallback behavior for GDELT→GNews and soft-fail for USPTO. With 3 fully described parameters and annotations, the description is complete for agent 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% (all three parameters described). The description adds meaning for `since` (ISO date or relative shorthand like '7d', '30d', '3m', '1y'; recommends '30d' for monitoring) and for `value` (ticker or CIK), enriching 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 tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' with clear verb and resource. It distinguishes from the sibling tool entity_profile, which provides static profile data.

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

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

The description gives explicit when-to-use guidance with example queries like 'What's new with X' and directly states 'Use entity_profile instead when you want the static profile.' It also provides parameter advice (e.g., 'Use "30d" or "1m" for typical monitoring').

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

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

Annotations declare idempotentHint=true and destructiveHint=false. The description adds behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' No contradiction.

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

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

Three sentences with no wasted words. The first sentence front-loads the purpose. Each sentence earns its place: purpose, usage guidance, behavioral details, and pairing with siblings.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, scope, persistence, and sibling tools. It is complete and self-contained.

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% for both parameters. The description adds guidance on key formatting (e.g., 'subject_property') and notes that value is 'any text', but this is minimal additional value. 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: 'Save data the agent will need to reuse later'. It specifies the verb (Save), resource (data), and context (reuse later, across sessions). It distinguishes from sibling tools 'recall' and 'forget' by explicitly naming them.

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

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

The description provides clear guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It pairs with 'recall' and 'forget', but does not explicitly state when not to use. However, the context is strong enough for most 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the cascading lookup behavior and specifying return formats (ticker+CIK for company, RxCUI+ingredient for drug). There is no contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured, starting with examples before stating purpose and details. Every sentence adds value. It could be slightly more concise, but the front-loaded examples aid quick understanding.

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 lookup tool with two entity types and no output schema, the description is complete. It explains input, output, behavior, and multi-step internal process. Combined with strong annotations, no gaps remain.

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

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

Schema coverage is 100% with both parameters described. The description significantly enriches semantics by detailing the output per type, acceptable input formats (e.g., ticker, CIK, name for company), and auto-disambiguation. This exceeds baseline expectations.

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: resolving names to canonical/official identifiers. It provides example queries and lists supported types (company, drug) with return details. While it doesn't explicitly differentiate from siblings, the examples and 'Use FIRST' guidance imply it is the primary ID resolution tool, distinct from entity_profile or search_structures.

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 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, reinforcing its utility. It does not explicitly state when not to use it, but the guidance is clear and actionable.

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=false. The description adds value by revealing internal mechanics: it probes each entity with ai_visibility_check, ranks by score, and returns specific fields (score, confidence, signal density). No contradictions with annotations.

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

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

Four well-structured sentences with no wasted words. First sentence states main action, second explains mechanism, third provides use case, fourth summarizes output. Ideal front-loading and efficiency.

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 return fields (score, confidence, signal density) and explains the process (probing, ranking). It could mention whether results are sorted or if order is consistent, but it is complete enough for accurate agent invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: entities are 'brand/business/product names', first entry is treated as the 'subject' for narrative, models default to workers-ai, _apiKey only needed if anthropic is included, context disambiguates common names. This 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?

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check internally, ranks results, and surfaces which entity is most/least recognized. It includes a concrete example and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more general).

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 frames it for competitive AI-marketing audits with a sample question ('does Claude know about us as well as our competitors?'). It implies usage context but does not explicitly state when NOT to use it or list alternatives, though the purpose inherently differentiates it from single-entity 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 declare safe, idempotent behavior. Description adds behavioral details: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed listing timeouts. This goes beyond annotations to set expectations.

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 core purpose, but the description is relatively long. However, every sentence adds value (return structure, fallback behavior, ecosystem limits). Could be slightly tighter 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, description details the return format: summary block, per-advisory detail, links, alternative versions. Explains partial failures and ecosystem constraints, providing complete context for tool 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 describes both parameters well (package name, version). Description adds context: scoped packages (@types/node) accepted, version defaults to latest. This adds value 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 it's a composite check for adding npm packages, covering license, advisories, version history, and bundle size. It specifies the verb 'scan' and resource 'dependency', and the phrase 'in ONE call' distinguishes it from separate 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?

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM-only in v1 and directs to deps.dev:version for other ecosystems, providing clear context but no strict 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 indicate readOnly, openWorld, idempotent, and not destructive. The description adds key details: keyless, returns unit-cell parameters, space group, year, and CIF link. 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, front-loaded, and every sentence provides 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?

Despite no output schema, the description lists return fields sufficiently. Could mention default limit or pagination, but not essential.

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

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

Schema covers 100% of parameters, but the description adds crucial usage guidance ('provide at least one of...') and explains the sparsity of the mineral field, enhancing understanding beyond the schema.

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

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

The description explicitly states it searches the Crystallography Open Database for crystal structures by compound name, chemical formula, or mineral name, clearly distinguishing it from sibling tools like get_structure.

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 advises providing at least one of query, formula, or mineral, and notes that the mineral field is sparsely populated, offering practical guidance. However, it does not explicitly contrast with 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?

Disclosures beyond annotations include embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K chars with truncation and flag), and return details (passages with offsets and similarity scores). Annotations already declare readOnlyHint=true, idempotentHint=true, so 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?

Front-loaded with purpose and usage, then technical details. Every sentence provides unique information. Could trim 'Pairs with ask_pipeworx_grounded' repetition slightly, but overall efficient.

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

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

Given 3 parameters, no output schema, and no nested objects, the description covers key aspects: input requirements, behavior (embeddings, windowing), truncation policy, and return components. Missing explicit output format but provides enough inference. Good completeness for not having 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%, but description adds value: explains 'text' as fetched record, gives example queries for 'query', and specifies limit range (1-20, default 5). These examples clarify natural-language usage beyond 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 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K body, article, tool result). It distinguishes from sibling tools like ask_pipeworx_grounded by specifying that it operates on already-fetched text, not 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?

Explicitly states when to use ('record is too big to cram into the prompt') and provides alternatives ('pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'). Clear guidance on avoiding full document usage.

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

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

The description adds substantial behavioral context beyond annotations: account requirement, type-specific params, delivery constraints (e.g., phone verification, webhook auto-disable after 10 failures), and idempotency implications. 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 well-structured and informative, though slightly lengthy. Every sentence adds value, but could be slightly more concise without losing 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?

Despite no output schema, the description covers return value (subscription id), prerequisites, type behaviors, delivery channels, and error scenarios (webhook auto-disable). Complete for a 3-param tool with nested objects.

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 enriches parameters with concrete examples and constraints (e.g., phone must be verified, webhook HTTPS only), adding significant meaning beyond the schema.

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

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

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

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

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

The description provides explicit when-to-use guidance, prerequisites (Pipeworx OAuth account), types, and delivery channel constraints. It lacks an explicit when-not-to-use statement but the context is clear given sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. The description adds useful context about the tool being the onboarding entry point and returning non-destructive example questions, but does not disclose additional behavioral traits 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 well-structured with trigger phrases at the start, followed by explanation of output and parameter use. It is informative but could be slightly more concise; however, it remains efficient for the complexity involved.

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 an onboarding tool with no output schema, the description fully explains the purpose, when to use it, what it returns (category-bucketed questions with tool+argument shapes), and how to use the parameter. It is contextually 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?

The schema covers the single optional parameter with a description. The description adds meaning by explaining the effect of omitting the parameter (full spread) vs passing a topic, which goes beyond the schema description. Baseline 3 is exceeded.

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

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

The description clearly states the tool is an onboarding entry point that returns example questions categorized by topic. It uses trigger phrases like 'what can I ask Pipeworx?' and explains the output structure. It distinguishes itself from sibling tools like ask_pipeworx by being the first-use 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?

The description explicitly guides the agent to use this tool FIRST when it doesn't know what Pipeworx can do, and to learn how to call meta-tools. It also explains when to omit the topic parameter vs pass a specific topic, providing clear usage boundaries.

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 valuable behavioral context beyond annotations: that the row is deactivated (not deleted) and ownership is enforced. This aligns with annotations (destructiveHint=false, identity property hints consistent) and provides transparency about side effects.

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, concise, and front-loaded with the action. Every sentence adds 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?

For a simple tool with one param and no output schema, the description fully covers purpose, behavior, ownership, and side effects, making it complete for 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?

With 100% schema coverage, the description reinforces the param meaning by stating 'by id' and implicitly referencing the source ('returned by subscribe'), which adds value beyond the schema's own description.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions') and the consequence of deactivation, providing clear context for when to use. However, it does not explicitly state when not to use or suggest 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it uses SEC EDGAR + XBRL, returns a verdict with citation and delta, and replaces multiple sequential calls. It provides context beyond annotations without contradicting them.

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

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

The description is relatively long but well-structured, with examples and scope. It is front-loaded with the purpose and use cases. Every sentence adds value, though some minor redundancy could be trimmed.

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 one parameter and no output schema, the description effectively explains the input, return values (verdict, structured form, citation, delta), and domain scope. It is complete enough for an agent to understand 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% for the single 'claim' parameter with a good description. The tool description adds value by giving concrete examples of natural-language claims and explaining the domain, enhancing understanding beyond the schema.

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

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

The description explicitly states the tool verifies natural-language claims against authoritative sources, lists example queries, and distinguishes from sibling tools by noting it replaces multiple sequential calls. It is specific about the resource (company-financial claims via SEC EDGAR + XBRL).

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 specifies the scope (company-financial claims). It does not explicitly state when not to use, but the scope is clear enough to guide selection.

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