Arcgis Sanjoaquin

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 details: probes multiple LLMs, includes default model (free), requires API key for Anthropic, and specifies the return structure (score, confidence, signals, raw_response per model plus combined view). 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 (2-3 sentences), front-loaded with purpose, then details, then use cases. Every sentence adds value without fluff.

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

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

Given 4 parameters and no output schema, the description is complete. It explains input parameters, default behavior, optional models and API key usage, and explicitly states the return format including per-model fields and a combined view. Use cases are provided.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by clarifying default model behavior, that '_apiKey' is for Anthropic and costs are passed through, and that 'context' helps disambiguate. This 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 tool's purpose: 'Probe one or more LLMs for what they know about a business/brand/product/topic and score visibility'. It uses a specific verb and resource, and the tool is distinguishable from siblings like 'scan_competitor_ai_presence' which focuses 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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains the default model and the optionality of Anthropic with a BYO key. However, it does not explicitly mention when not to use this tool in favor of 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, idempotentHint, openWorldHint, and no destructiveness. The description adds behavioral context: it routes to one of 4,552 tools, fills arguments, returns structured answers with citation URIs, and is fast. This adds beyond annotations, though it doesn't discuss limitations or failure modes.

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 a clear top-level instruction, use cases, examples, and alternatives. Every sentence adds value, though slight verbosity prevents a 5. It front-loads the key preference statement.

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

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

Given the tool's complexity and the rich annotations, the description covers purpose, usage, and behavior thoroughly. It includes examples and alternatives. Missing details about error handling or empty responses, but overall sufficiently complete for a factual 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 100% with all aliases documented. The description adds minimal extra meaning beyond the schema; it provides examples but doesn't elaborate on parameter syntax or constraints. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to answer factual questions using a large set of verified sources, with a strong preference over web search. It specifies the types of data (SEC filings, FDA, etc.) and distinguishes from sibling tools like ask_pipeworx_grounded and deep_research, making it very 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 explicitly says 'PREFER OVER WEB SEARCH' and provides clear when-to-use and when-not-to-use guidance. It lists example queries and advises stepping up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad multi-part questions. This is comprehensive 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 readOnlyHint, idempotentHint, destructiveHint=false, so the description doesn't need to re-state safety. However, the description adds useful behavioral details: it follows the same routing as ask_pipeworx, selects the right tool, fetches data, and extracts answer only from the result. It also specifies exact refusal reasons. This adds 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: opening sentence with purpose, then mechanism, return format, use cases, and comparison to sibling. It is slightly long but every sentence contributes useful information. 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 large ecosystem (4,552 tools, many siblings), the description covers all essential aspects: purpose, when to use vs alternatives, how it works, return format including possible refusals. No output schema exists, so the description fully handles output expectations.

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

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

Schema coverage is 100%, so the description adds limited value for parameters. The description only mentions 'Your question in natural language' which duplicates the schema. It does not explain the aliases (q, text, etc.) beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads. It explicitly contrasts with sibling 'ask_pipeworx' by mentioning it costs an extra LLM call and is intended for when answers will be quoted or acted on, providing strong differentiation.

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

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

The description explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the sibling ('prefer ask_pipeworx for casual lookups'). It also gives concrete examples like financial verdicts, legal claims, etc.

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, but the description goes far beyond by detailing the fan-out process, resolver contract, parent_event extractor, news fields with fallback, safety mechanisms, and resolution-rule risk. All this additional context helps the agent understand the tool's behavior, side effects, and failure modes, with no contradictions to 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 detailed, covering many aspects of the tool's behavior. While it is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), it is not concise. Every sentence adds value, but the overall length could be reduced for quicker parsing. Thus, it scores average in 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?

Given the tool's complexity (3 parameters, no output schema), the description is exceptionally complete. It explains response shapes, resolver contract, parent_event extractor, news fields, safety mechanisms, and resolution-rule risk. Without an output schema, the description fully compensates, ensuring the agent knows what to expect and how to interpret results.

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

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

The input schema has 100% description coverage for all three parameters, so the baseline is 3. The description does add some nuance (e.g., 'include_raw' default behavior, 'depth' enum values), but it mostly restates what the schema already provides. It does not significantly enhance understanding beyond the 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research by pulling data). It also provides example inputs (slug, URL, question text) and concrete use cases ('should I bet on X', etc.), making it easy for the agent to select this tool over siblings.

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

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

The description offers explicit guidance on when to use the tool ('Use for...'), how to provide input (slug, URL, question text), and what to expect (classifiers, fan-out examples, response shapes). It also covers edge cases like low-confidence matches, closed markets, and wide spreads, providing comprehensive usage instructions without needing to list alternatives explicitly.

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

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

The description discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting, and citation URIs. This adds valuable context beyond the annotations (readOnlyHint, etc.), 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 a single paragraph that efficiently covers triggers, behavior, type details, and output format. It is dense but not overly long, and every sentence adds value.

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

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

Given no output schema, the description explains the return format (paired data, sorted, with citation URIs). It covers input, processing, and output adequately for a tool with 2 parameters.

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 has 100% coverage, but the description adds meaning: it explains what data is pulled for each type and gives examples. The type parameter's enum values are enriched with data source details.

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

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

The description clearly states that the tool performs side-by-side comparison of 2-5 companies or drugs in a single call. It uses specific verbs ('compare', 'rank') and distinguishes itself from siblings like entity_profile by focusing on comparisons.

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 trigger phrases and explicitly advises preferring this tool over sequential single-pack lookups. It explains when to use 'company' vs 'drug' type, but does not explicitly state when not to use it or list alternative 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, openWorldHint, idempotentHint, and destructiveHint. The description adds important behavioral details: account required, parallel execution, findings packet structure with gaps[], and expected response time (15-60s), providing significant 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 relatively long but well-structured with clear sections (account, purpose, alternatives, use cases, performance). Critical information is front-loaded (account required, alternative tool). Every sentence adds value, though some verbosity is justified by complexity.

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

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

Despite no output schema, the description thoroughly explains the return packet (verbatim evidence, confidence, sources, citations, gaps[]). Given the tool's complexity (1160 sources, 4552 tools), the description covers usage, behavioral, and output details comprehensively.

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

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

Schema coverage is 100%, baseline 3. The description adds meaningful semantics: explains depth values (quick=3, standard=5, thorough=8) and clarifies that the question parameter accepts broad/multi-part natural language. This enriches the schema's enum and string 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 performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to parallel tools. It distinguishes itself from sibling tools like ask_pipeworx (single lookup) and provides specific use cases and examples.

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

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

Explicit guidance on when to use (broad/multi-part questions over structured data) and when not to use (breaking news, prefer ask_pipeworx). Also mentions account requirements and depth tiers, with specific alternative tool recommendations.

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. The description adds that it returns 'ready to call directly, no second schema lookup,' which is a helpful behavioral detail beyond annotations. 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 paragraph but efficiently front-loads purpose, includes concrete examples, and ends with a usage hint. It is moderately concise but covers all necessary points without excessive 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?

Despite lacking an output schema, the description details the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also explains when to use, making it adequately complete for this discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the aliases ('Accepts task, q, description, search as aliases') and providing natural language examples in the schema, making parameter intent clearer.

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 provides numerous domain examples and distinguishes this tool as a meta-tool for discovering options, which is unique among siblings like search_datasets.

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

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

Explicitly advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This guides the agent to use it for exploration, not for direct answers.

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 it read-only, idempotent, and non-destructive. Description adds context: parallel call, patent API sunset soft-fail, and specific return fields. No contradiction.

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

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

Description is packed with information but front-loaded with example queries. Every sentence adds value. Slightly long but 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?

With 2 params and no output schema, description explains return fields, sources, and limitations (patent sunset, name unsupported). Sufficient for an agent to understand tool behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reinforces that 'type' is only 'company' and 'value' is ticker or zero-padded CIK, adding the constraint that names are not supported. This adds clarity 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 uses specific verbs like 'profile' and 'cross-source profile' and lists resources: SEC, XBRL, USPTO, news, GLEIF. It distinguishes from sibling 'resolve_entity' by stating names are not supported, and from other siblings like 'deep_research' by focusing on public company 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 says 'ALWAYS PREFER over chaining single-pack lookups when holistic view is needed' and warns 'Names not supported — use resolve_entity first if you only have a name.' Provides clear when-to-use and alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no additional behavioral details beyond what annotations provide, such as error handling or 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?

Two sentences effectively deliver purpose and usage context. No extraneous information; front-loaded with key action.

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 destructive tool with one parameter and no output schema, the description is complete: it states purpose, when to use, and how it relates to siblings.

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 parameter 'key' with full description. Description does not add new semantic meaning beyond the schema, maintaining baseline score for 100% schema coverage.

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

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

Description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by focusing on deletion.

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 three use cases: stale context, task completion, and clearing sensitive data. Also advises pairing with 'remember' and 'recall', giving clear guidance on when to use this tool versus 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?

Describes the internal process (fetch, extract, emit) and output format, complementing annotations (readOnlyHint, idempotentHint) without contradiction.

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

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

Three focused sentences with no waste, front-loading the primary action and delivering necessary context 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 simplicity, full annotation coverage, and explicit output description, the description is fully sufficient for correct tool 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% with detailed descriptions; the description adds minimal extra meaning 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?

The description clearly states 'Generate a production-ready llms.txt file for any URL' and lists specific use cases, differentiating it from sibling tools like scan_competitor_ai_presence.

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

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

Provides explicit use cases (client indexing, own project, competitor auditing) but lacks explicit when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds the 'by url' constraint and specific output fields, but doesn't provide additional behavioral context like rate limits or auth requirements.

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?

Single sentence, front-loaded with action and resource, lists outputs efficiently. 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?

Even without output schema, description fully explains return values (fields, geometry type, record count, capabilities). Annotations provide safety context. Sufficient for a simple one-parameter tool.

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

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

Input schema has 100% coverage for the single parameter 'url', including example. Description reiterates 'by url' but adds no new meaning beyond schema – baseline 3 applies.

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

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

Description uses specific verb 'Get' and resource 'ArcGIS Feature/Map Service layer schema', listing exact outputs (fields, geometry, record count, capabilities). Clearly distinguishes from siblings like 'query_layer' which likely queries features.

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 explicit guidance on when to use this vs alternatives (e.g., query_layer for data queries, search_datasets for broader search). Agent must infer from schema description alone.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds clarity by noting it returns active subscriptions by default and can optionally include inactive ones. 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?

Three concise sentences: purpose, return fields, and usage guidance. No wasted words, 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?

For a simple list tool, the description covers purpose, return format, usage scenarios, and the optional parameter. Given no output schema, listing return fields is sufficient. No gaps.

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

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

Schema description coverage is 100% and the description of the sole parameter 'include_inactive' is adequate in the schema. The tool description adds no further meaning beyond what the schema provides.

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

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

The description clearly states the verb 'List' and the resource 'subscriptions', and specifies the exact fields returned. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing existing 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?

Explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear context, though it doesn't explicitly list when not to use it.

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

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

The description discloses rate limits ('5 per identifier per day') and cost ('doesn't count against your tool-call quota, free'). It explains the outcome ('team reads digests daily, signal affects roadmap'). Annotations are all false, so no contradiction; the description adds valuable 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 a single well-structured paragraph. It front-loads the core purpose, then covers use cases, behavioral details, and constraints. Every sentence is informative and necessary; 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 feedback tool with no output schema, the description covers all necessary aspects: input semantics, usage guidelines, rate limits, cost, and impact. It is complete 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%, but the description adds semantic meaning: it clarifies enum values (e.g., 'bug = something broke or returned wrong data'), provides guidance on the message field ('be specific, which tool, what error'), and explains optional context fields. This adds significant value for 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 explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature/data_gap, praise) and distinguishes this feedback tool from other siblings which are data retrieval or analysis 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?

The description provides clear when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes what to avoid: 'don't paste the end-user's prompt.' Plus it mentions rate limits and cost.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching interval (5min-1h), going 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 very concise, using three sentences and a bullet list. Every sentence adds value with no redundancy or fluff.

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

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

For a tool with no output schema, the description sufficiently describes the return (top tools, top packs, total call volume). It could mention format or pagination, but annotations cover safety aspects. Overall, it is complete enough for a trending endpoint.

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 well-described parameter. The description adds usage guidance on window choices (shorter for hot items, longer for steady-state), enhancing the schema's description.

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

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

The description explicitly states it returns top tools, top packs, and total call volume over a window. It lists three concrete use cases, differentiating it from siblings like 'discover_tools' or 'search_datasets' which serve different needs.

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 with three 'useful for' scenarios, indicating when to use the tool. It does not explicitly mention alternatives or when not to use, but sibling tools are listed separately.

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 indicating read-only and idempotent behavior, the description details internal mechanisms (monotonicity violations, partition-sum checks, semantic anchor with Jaccard similarity, partition filter, fill check) and clearly states conditions like skipped_low_similarity and null arb signals. No contradiction with annotations.

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

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

The description is somewhat lengthy but every sentence contributes useful information. It is well-structured with clear sections and front-loaded purpose. A minor deduction for length, but it remains efficient for the tool's complexity.

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

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

With no output schema, the description fully documents the response structure including opportunities array and partition_check details. It also covers fill_check results and edge cases like placeholders filtered, making it complete for a complex tool with multiple modes.

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

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

Schema coverage is 100%, but the description adds substantial value by explaining parameter usage (event slug or full URL, topic seed question), providing examples, and detailing how each parameter affects the scan mode. This goes well beyond the schema description.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between trending_scan, event, and topic modes, and is clearly differentiated from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It also advises using event as recommended and mentions custom sizing via polymarket_fill_risk, providing clear context for when to use alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds extensive behavioral context: it explains the three model families, edge computation, slippage, Kelly sizing, tradeable-edge knobs, response structure including diagnostics, and caching behavior. No contradiction with annotations.

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

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

The description is long but well-organized with clear sections (segments, knobs, response structure). Every sentence adds value, though it could be slightly more concise without losing detail. Front-loaded with purpose.

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

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

Given the complexity (9 parameters, no output schema, nested response structure), the description covers all necessary aspects: what the tool does, how segments work, parameter definitions, response details including diagnostics, and caching. It is fully complete for an AI 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%, so baseline is 3. The description adds significant meaning beyond the schema: it explains the purpose and effect of each parameter in practical terms (e.g., min_kelly 'skips opportunities too small to bet sensibly', min_partition_leg_kelly explains why partition arbs are filtered differently). This exceeds the baseline.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with specific detail on the three segments. It distinguishes from siblings like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by its purpose and methodology.

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 the tool for 'what should I bet on today' and states it discovers opportunities without paging. It also discusses caching and knobs for filtering. However, it does not explicitly state when not to use it or contrast with alternative 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: history depth bounded by 60-day TTL, decay computed from daily closes of `edge_pp_net` (net of default slippage, not intraday), and response structure details (tracked, expired, snapshot_dates). This goes beyond annotations.

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

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

The description is front-loaded with the core purpose in the first sentence. It uses a structured RESPONSE section with bullet points (tracked[], expired[], snapshot_dates[]), making it easy to parse. While a bit lengthy, every sentence adds value. Could be slightly more concise 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?

Given no output schema, the description compensates by detailing the response structure and explaining each field (tracked with trend and decay, expired with lifespan, snapshot dates). It also covers limitations (TTL, snapshot start) and data sources. It does not define `edge_pp_net` in detail but that may be understood from sibling tools. Overall very 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 descriptions for both parameters (days and window). The description repeats these with default values and max for days, which is already in the schema. It adds minimal extra meaning beyond the schema, such as clarifying window options. 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 provides edge persistence and decay telemetry from daily snapshots. It distinguishes itself from the sibling polymarket_edges (raw edges) by focusing on historical persistence and decay. The specific question 'how long has this edge existed and is it shrinking?' precisely defines its utility.

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: when assessing edge persistence and decay. It contrasts a fresh wide edge with a 3-week-old one, implying that for current raw edges one should use polymarket_edges. While alternatives are not explicitly named, the context is clear. No explicit 'when not to use' but the purpose implies it.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint, so description adds value by detailing the risk-check behavior: walking the ladder, returning verdicts, and warning about partial fill dangers. 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 around 150 words but efficiently uses all-caps keywords (REQUIRES, SINGLE-MARKET, BASKET) and structured lists. All sentences contribute meaningful information. Could be slightly more scannable but earns its length.

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

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

No output schema, but description comprehensively lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict; theoretical_sum, capture_ratio, forced_directional_risk). Includes warnings about thin legs and directional risk.

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 context beyond schema: explains side defaults per mode, size_usd interpretation difference (spend vs proceeds), and clamp range. This compensates for the lack of enum values.

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 performs a realizable-vs-theoretical edge check against live CLOB order-book depth, with distinct single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a prerequisite check.

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

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

Provides explicit when-to-use guidance: before acting on polymarket_arbitrage signals or trades above ~$500. Explains why (theoretical overround not capturable on thin books, partial fills create directional risk). Implicitly suggests small trades or thick books may not need 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 richly discloses the tool's behavior: it has two operational modes, provides compatibility warnings for non-equivalent bet shapes or misaligned events, explains temporal alignment, and details skipped cross-type/subtype counters. Annotations already indicate read-only and non-destructive behavior, and the description adds complementary context without contradiction.

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

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

The description is long but well-organized with clear sections (modes, response, safety fields). Every sentence adds important detail, and the use of bold headings improves scanability. However, it is somewhat dense and could be slightly tightened for even better 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?

Given the tool's complexity (3 parameters, no output schema), the description covers all necessary aspects: input modes, response structure (leg-by-leg prices, top spreads), safety fields (compatibility, temporal alignment, skipped counters), and edge cases. It provides a complete mental model for correct 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?

The schema provides 100% coverage with descriptions for each parameter. The description adds value by explaining the topic list, how explicit tickers override topics, and the role of each parameter in different modes. It enriches the schema with usage context.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket, specifying two modes (topic shortcuts and explicit tickers) and the output (spreads in percentage points). It distinguishes itself from similar tools by focusing on matched outcomes across venues.

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 each mode (topic for common macros, explicit for custom pairs) and warns that most pre-mapped topics yield compatibility warnings, setting proper expectations. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or advise when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond annotations: default limit of 50, max 2000, pagination via offset, and that it returns both attribute rows and geometry. This enriches the agent's understanding of the tool's 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?

Two sentences efficiently cover purpose, URL source, key parameters, and a practical example. No wasted words; the description is front-loaded with the main action.

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, but the description mentions it returns attribute rows and geometry, sufficient for a query tool. It also notes the limit cap and pagination. While error handling is omitted, the tool is straightforward, making the description adequately 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 parameters are already well-documented in the schema. The description adds marginal value by explaining defaults (e.g., where='1=1') and usage patterns (SQL-like, comma-separated), but does not fundamentally change 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 queries ArcGIS Feature/Map Service layers, specifying the URL format from search_datasets. It distinguishes itself from siblings like layer_info (metadata) and search_datasets (finding datasets) by focusing on data retrieval with SQL-like syntax.

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 usage guidance with examples like using where='1=1' and out_fields='*' for sampling. While it doesn't explicitly say when not to use it, the examples and default values offer clear context for appropriate use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the list-all behavior when key is omitted. No contradictions, and the description enhances transparency beyond annotations.

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

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

The description is concise at about 60 words, front-loading the primary purpose ('Retrieve a value') then elaborating on usage and scoping. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description covers usage well but does not specify the return format for key retrieval (e.g., value type) or what happens on missing key. However, for a simple lookup tool, the description is largely 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 one optional key parameter described. The tool description adds context by connecting the key to 'previously saved via remember' and provides examples (user_research_topic). 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 retrieves a value saved via remember, or lists all keys if key omitted. The verb 'retrieve' and resource 'saved keys' are specific, and it distinguishes from siblings like forget and remember.

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: 'look up context the agent stored earlier' and gives concrete examples (ticker, address, research notes). It also implies alternatives (re-deriving from scratch). Scoping and pairing with remember/forget are covered.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: mark_read modifies read status (idempotent), the feed is persisted, and it explains the effect on subsequent calls. This goes 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?

Four sentences, each adding important info: purpose, return fields, filtering/mark_read, and polling/alternative. Front-loaded with purpose, 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 read-only polling tool with 5 optional params and no output schema, the description covers key aspects: what is returned, filtering, mark_read side effect, polling suitability, and alternative access. It could mention error handling or rate limits, but overall 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?

With 100% schema coverage, baseline is 3. The description adds meaning by explaining typical usage (filtering by type like 'sec_8k', using ISO timestamps) and the effect of mark_read and unread_only. It does not repeat schema descriptions but provides operational 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 pulls fired events from the subscription feed, with specific return fields (source, citation_uri, raw payload). It distinguishes itself by mentioning an alternative access method (direct URL) and implicitly differentiates from sibling tools like list_subscriptions by focusing on recent alerts.

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

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

The description provides clear guidance on when to use this tool: for polling alerts, with optional filters (type, since), and mark_read to control read state. It mentions that 'Polls work fine' and offers an alternative for scripts/dashboards, though it does not explicitly exclude other 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, idempotentHint true, destructiveHint false. The description adds valuable context: fan-out to multiple sources, fallback logic, soft-fail for USPTO, and return format (structured changes grouped by source, total_changes count, 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 compact yet comprehensive, starting with usage examples, explaining the multi-source behavior, parameter details, and ending with a clear alternative (entity_profile). Every sentence is meaningful 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 tool with 3 required parameters and no output schema, the description covers all essential aspects: sources, fallback, return structure, and differentiation from sibling. It is self-contained and sufficient 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 the description adds practical details: `type` only supports 'company', `since` accepts ISO dates or relative shorthand with examples ('30d', '1m'), and `value` accepts ticker or CIK. This 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 tool provides a change feed for a company, fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from sibling tool 'entity_profile' by noting that entity_profile should be used for static profiles regardless of window.

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 query examples ('What's new with X', 'latest on Y') and tells when not to use this tool ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews) and USPTO limitations.

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 write (readOnlyHint=false) and idempotentHint=true. The description adds useful behavioral context: data is scoped by identifier, persists 24h for anonymous users, and is stored as key-value pairs. 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, well-structured, and front-loaded with purpose. Every sentence adds value—usage guidance, technical details, and sibling references—without 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?

For a simple 2-param tool without output schema, the description covers purpose, usage, persistence, and sibling relationships. It lacks explicit mention of overwrite behavior on duplicate keys, but idempotent hint implies this.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds examples ('subject_property', 'target_ticker') and explains the scoping, going beyond the schema's basic 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 clearly states the action (save data), the resource (key-value memory), and differentiates from sibling tools (recall, forget). It provides specific examples of what to store (ticker, address, etc.), 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 explicitly tells when to use the tool ('when you discover something worth carrying forward') and pairs it with recall and forget, providing clear alternatives. It also distinguishes between authenticated and anonymous sessions, offering concrete guidance on persistence behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations, noting that calls cascade through multiple lookup endpoints internally and replace 2-3 manual lookups, as well as mentioning auto-disambiguation. This provides useful behavioral insight.

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

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

The description is front-loaded with usage examples and clear structure. While slightly verbose with repeated type details, it remains focused and each sentence adds value. Could be trimmed 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 the tool's moderate complexity and no output schema, the description covers key aspects: supported types, return values, internal behavior, and usage positioning. Minor gaps exist, such as handling of ambiguous inputs or error scenarios, but the description is sufficient for tool selection.

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 100% of parameters. The description adds substantial meaning by providing example inputs per type and detailing the outputs (e.g., for company: ticker, CIK, company_name, citation URI). This goes beyond the schema's concise 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 examples like 'What's the ticker for…'. It distinguishes from sibling tools by positioning itself as the first step ('Use FIRST whenever you have a name but need an ID'), differentiating it from entity_profile or compare_entities.

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

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

The description includes a direct usage instruction ('Use FIRST whenever you have a name but need an ID') and lists supported types with their outputs. However, it does not explicitly state when not to use it (e.g., if you already have an ID or need detailed profiles), leaving some implicit context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a structured result (score, confidence, signal density). It also discloses API key requirement for the 'anthropic' model. 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 two well-crafted sentences plus a parenthetical example. It is front-loaded with the core purpose and includes all essential details without redundancy. Every sentence adds value.

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

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

Given no output schema exists, the description adequately describes the return value as a 'ranked list with score, confidence, signal density per entity.' It also covers input semantics and usage context. It lacks explicit error handling or rate limits, but annotations (read-only, idempotent) mitigate some completeness gaps.

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

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

Schema description coverage is 100%, baseline is 3. The description adds meaning beyond schema by stating that the first entity is treated as the 'subject' for narrative and others as competitors, which aids understanding of the 'entities' parameter. It also implies that 'context' disambiguates common names, enhancing 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?

The description clearly states that the tool 'Compare AI visibility across multiple entities side-by-side' and explains it uses ai_visibility_check internally and ranks results. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and an example question. However, it does not explicitly state when not to use the tool or mention alternatives like ai_visibility_check for single-entity queries, though the sibling context implies this differentiation.

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

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

Discloses behavioral traits beyond annotations: fans out across multiple services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed listed. Annotations already indicate safe read operation, and description adds performance and failure context.

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

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

Description is long but well-structured and front-loaded with purpose. Every sentence provides essential information: use case, data sources, return structure, limitations, and failure handling. No wasted words.

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

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

Despite lacking an output schema, the description fully explains the return structure (summary block fields, per-advisory detail, links, alternative versions) and failure behavior. Complete for a composite tool of this complexity.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minor context about scoped packages and default behavior for version, but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it performs a composite check for npm packages, combining deps.dev and bundlephobia. It distinguishes from siblings by specifying NPM ecosystem only and mentions that other ecosystems fall under a different 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?

Explicit usage guidelines: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by specifying the exact return fields, record count, and the Feature Service URL, which helps the agent understand the tool's output and subsequent steps.

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 efficiently conveys purpose, return fields, and usage guidance. It is front-loaded, with no superfluous words.

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

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

For a search tool with three well-documented parameters, good annotations, and no output schema, the description is complete. It covers what the tool does, what it returns, and how to use the results, which is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'keyword' mapping to 'query' but does not add significant new meaning beyond the schema for 'limit' and 'org_id'. The default org (San Joaquin County) is implied but not explicit.

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 'Search', the resource 'San Joaquin County GIS open geospatial datasets', the scope ('by keyword'), and the return fields including the Feature Service URL. It also hints at differentiation from siblings 'query_layer' and 'layer_info' by noting the URL 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?

The description explains the search action and explicitly tells the agent to pass the returned URL to 'query_layer' or 'layer_info', providing a clear workflow. However, it does not explicitly state when not to use this tool or alternative tools for similar searches.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent with description. Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation and flagging – beyond annotation coverage.

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 and usage. Each sentence adds unique value (what it does, when to use, technical details). No redundancy.

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

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

Covers purpose, use case, pairing with sibling, technical internals, limits, and return format (offsets, scores). No output schema, but description sufficiently explains what the agent receives. Complete given annotations and 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 covers 100% of parameters with descriptions. Description reinforces parameter constraints (max ~200K chars for text, default 5 limit, natural-language query) and adds context about embedder and return fields (offsets, scores), beyond schema.

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

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

Clearly states verb 'search', resource 'inside a fetched record', and specifies returning top-N passages with offsets and scores. Distinguishes from sibling tools like ask_pipeworx_grounded by emphasizing internal search vs. grounded generation.

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

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

Explicitly advises use when the record is too large for the prompt, explains context-saving benefit, and pairs with ask_pipeworx_grounded as an alternative workflow. Provides clear when-to-use guidance.

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

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

The description expands beyond annotations: it discloses that the subscription is persistent, returns a new subscription id, and details delivery channel behaviors (e.g., SMS cap of 10/day, webhook auto-disable after 10 consecutive failures, phone verification requirement). This adds value beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false).

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: it starts with the core purpose, then requirements, then supported types with examples, then delivery channels. Every sentence adds value. It is slightly long due to the complexity of the tool, but it stays focused and front-loaded.

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

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

Given the tool’s complexity (3 parameters, nested objects, 5 enum types, multiple delivery channels), the description covers all aspects: type-specific params, delivery options with constraints, and return value ('Returns the new subscription id'). No output schema exists, but the description provides sufficient information for the agent to 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?

With 100% schema description coverage, the schema already describes each parameter. The description adds significant meaning: it provides concrete examples for each type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}) and elaborates on delivery channel details, including webhook HMAC signing and secret handling, which go 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 starts with a clear verb-resource pair: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (create subscription) and the resource (live-data event stream), distinguishing it from sibling tools like list_subscriptions (list) and unsubscribe (remove).

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

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

The description explicitly states a requirement: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It provides detailed guidance on supported types and their specific parameters, helping the agent decide when to use this tool. However, it does not directly compare to sibling tools or state when not to use it, leaving some implicit 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, covering safety. The description adds value by detailing the output structure (category-bucketed examples with tool+argument shapes) and that it's drawn from a live catalog, but does not mention any additional behavioral nuances.

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 serves a purpose, from alternative phrasings to usage instructions. Front-loaded with the tool's core value and structured logically, no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully explains its role, output, and usage. It also connects to meta-tools, making it complete for an onboarding tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the schema's parameter list and adds 'betting' as an example, but provides no additional semantics beyond what the schema already communicates.

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 'category-bucketed example questions' with exact tool+argument shapes. It differentiates from siblings by positioning itself 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes when to pass a topic vs. calling with no arguments, providing clear decision points.

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

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

Discloses key behaviors: ownership enforcement and deactivation instead of deletion. Adds context beyond annotations by explaining historical events remain available via recent_alerts. No contradiction with annotations.

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

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

Two sentences, no unnecessary words. Front-loaded with the core action and then adds important details. 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 simplicity (1 param, no output schema), the description covers purpose, constraints, side effects, and relationship to other tools (recent_alerts). No gaps.

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

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

Schema covers parameter fully, and description adds value by specifying the id is from subscribe. Provides additional 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 the action 'Cancel a subscription by id' and distinguishes from sibling tools like subscribe and list_subscriptions. It specifies the resource and the operation.

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

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

Provides clear context for when to use (ownership enforcement) and implies when not to use (e.g., not for listing). Does not explicitly mention alternatives but sufficiently guides 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 behavioral context beyond annotations: it details the return types (verdict, structured form, actual value with citation, percent delta) and notes that the tool replaces 4-6 sequential calls. This enriches the readOnlyHint, openWorldHint, and idempotentHint 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, starting with trigger phrases, then purpose, domain, and output details. Every sentence adds information, 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?

For a tool with only one parameter and no output schema, the description fully covers purpose, usage, domain, and output details. It is complete and sufficient for an AI agent to understand when and how 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?

The input schema has 100% description coverage for the single 'claim' parameter, but the description adds value by providing example claims and clarifying the natural-language format, which helps in constructing appropriate inputs.

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

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

The description uses clear trigger phrases and states 'natural-language claim verification against authoritative sources,' specifying the verb (verify) and resource (claims). It also notes it replaces 4-6 sequential calls, distinguishing it from sibling tools by highlighting its efficiency and specialization.

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 explicitly limits domain to company-financial claims via SEC EDGAR+XBRL. It implicitly advises against using for non-financial claims but doesn't mention alternative sibling tools like deep_research for broader fact-checking.

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