Arcgis Irvine

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

Even with annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: the default model is free, passing _apiKey enables Anthropic probing with direct payment, and the return structure is disclosed. There is no contradiction with the annotations, and the cost and model selection details go 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 three focused sentences: function, model/cost behavior, and return format/use cases. It is front-loaded with the core purpose and every sentence adds unique information without waste. This is a model of 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?

With no output schema, the description adequately compensates by describing the per-model result structure and combined view. All 4 parameters are documented in the schema, and the description covers key behavioral aspects. It stops short of a 5 because it does not mention potential errors, rate limits, or how the confidence/signals are derived, but for a read-only analysis tool it 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 description coverage is 100%, so the schema already documents all parameters. The description briefly mentions `_apiKey` and the default model, but this adds little beyond the schema's own descriptions of the models parameter. It does not explain syntax or edge cases, keeping this at the baseline 3.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model, which is a specific verb+resource. However, it does not explicitly distinguish itself from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence,' so it lacks the sibling differentiation needed for a 5.

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

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

The description provides clear use-case context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the tool. It does not mention alternative tools or exclusion criteria, so it meets the 'clear context, no exclusions' bar but not the full 5.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: it explains that the tool routes to sub-tools, fills arguments, returns structured answer with persistent pipeworx:// citation URIs, works on every tier, and is a fast single call. No contradictions.

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

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

Though longer than typical descriptions, every sentence serves a purpose: it front-loads the primary directive, explains the mechanism, lists trigger use cases, gives concrete examples, and differentiates alternatives without redundancy. It is well-organized and 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?

For a complex meta-tool with no output schema, the description covers what it does, when to use it, how it behaves at a high level, what results look like (structured answer with citations), and when to prefer alternatives. It is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the same 'question' field, so the schema already carries the parameter meaning. The description itself adds no additional parameter-level details beyond examples of valid questions, making baseline 3 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 routes questions to the right one of 5,462 tools across 1,419 verified sources and returns a structured answer with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its 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?

Explicitly instructs to prefer over web search for a long list of data domains, provides trigger phrases like 'what is', 'look up', 'find', and 'current', and names specific alternatives with conditions to step up ('Step up only when needed'). This is exemplary usage 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, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these by stating it is a full working router (no fallback), that behavior may change when routing candidates are under test, and that it currently matches ask_pipeworx exactly. This clarifies the experimental, dynamic nature of the tool.

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 concept but is wordy. Phrases like 'identical universal router' and 'exactly like ask_pipeworx' are redundant, and the specific retirement date (2026-07-26) adds little value for tool usage. It could be condensed to a tighter, more focused description without losing important information.

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

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

Given the absence of an output schema, the description does mention 'same response shape' as ask_pipeworx, which provides a useful reference point for agents familiar with the sibling tool. Combined with annotations covering safety and the description covering functionality and current status, it is sufficiently complete for a routing tool, though more self-contained response details would be ideal.

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 with all aliases (q, text, input, query, prompt, question) described, so the schema carries the parameter documentation. The description adds 'same arguments' as ask_pipeworx but does not enrich parameter meaning further, aligning with the baseline score of 3 for high schema coverage.

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

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

Description clearly states it is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape, and explicitly frames it as the experimental edge. It distinguishes itself from the stable ask_pipeworx sibling by highlighting candidate routing improvements, making the purpose specific and well-scoped.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. While it does not explicitly state when NOT to use it, the beta context and the reference to the stable alternative implies a preference for ask_pipeworx in stable 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?

The description discloses important behaviors beyond annotations: it extracts answers only from tool results, returns a structured refusal with five specific refusal_reason values, and costs an extra LLM call. It also details the exact response format. This adds significant transparency about the tool's honesty and failure modes, complementing readOnlyHint and idempotentHint.

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

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

The description is dense yet efficiently structured: it opens with a purpose statement, explains routing and extraction, lists return/refusal formats, provides usage cases, and concludes with cost tradeoff. Every sentence contributes meaningful information without fluff.

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

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

Given the complexity of the tool and the absence of an output schema, the description is remarkably complete. It covers the operational flow, response structure, refusal reasons, cost implications, and guidance on when to choose an alternative. No critical gaps remain.

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

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

The input schema already covers all parameters with 100% description coverage, all as aliases for `question`. The tool description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with specific mechanics (picks tool, fetches data, extracts answer) and distinguishes it from sibling ask_pipeworx by stating it uses ONLY the tool result. It also lists concrete use cases, making the purpose unambiguous.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' It names the alternative and provides clear when-to-use/when-not-to-use criteria.

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

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

The description goes far beyond the readOnlyHint/openWorldHint annotations. It details the resolver contract (market_match_confidence, suggestions), parent_event extraction, news fallback behavior, safety short-circuit statuses, spread warnings, and resolution-rule risk (e.g., refund_50_50). No contradictions with annotations.

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

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

The description is long but well-organized with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the purpose and use case, then dives into needed details. Some redundancy exists (e.g., explaining low-confidence and closed-market paths separately), but generally every section earns its place for a complex tool.

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 thoroughly explains return shapes (result.market, analysis, evidence), resolver confidence fields, parent_event data, news fallback fields, and safety statuses. It covers edge cases like wide spreads, closed markets, and resolution-rule risk, providing a complete picture of 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 description coverage is 100% for all 3 parameters. The description adds no parameter-specific details beyond what the schema already provides (e.g., it does not explain depth or include_raw behavior beyond the schema's descriptions). Baselines at 3 when schema coverage is high and description adds little.

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 begins with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb+resource+scope. It clearly distinguishes this tool from siblings by focusing on single-bet research with data fan-out, and provides explicit use cases ('should I bet on X', etc.).

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly name alternative tools or state when not to use it, so it lacks the exclusion guidance that would merit a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true. The description adds substantial context beyond these: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled (revenue, net income, adverse-event counts), off-calendar fiscal year handling, sorting by primary metric, and citation URIs in the response. This is valuable behavioral disclosure not present in structured fields.

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 about 120 words, which is long but every sentence contributes distinct information: trigger phrases, scope, priority rule, data sources, special handling, sorting, output format, and efficiency. It is front-loaded with the core purpose and example triggers, making it scannable despite the length.

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

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

Given the tool's complexity (two entity types, multiple metrics, sorting, citations) and lack of output schema, the description covers all essential aspects: what it does, when to use it, what data it fetches, how results are sorted, and what the return includes. It also highlights edge cases like off-calendar fiscal years. The description is self-sufficient for an agent to select and invoke the tool correctly.

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

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

The schema describes both parameters with 100% coverage, so baseline is 3. The description adds meaningful semantics by explaining what each type retrieves (company pulls 10-K financials, drug pulls FAERS counts, FDA approvals, trial counts), which goes beyond the schematic enum values. It also clarifies the input format for values (tickers vs drug names).

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 does side-by-side comparison of 2–5 companies or drugs in one parallel call, with trigger phrases like "compare X and Y" and "which is bigger." It clearly distinguishes itself from sequential lookups by saying ALWAYS PREFER over sequential single-pack lookups, a specific alternative.

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

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

It provides a clear when-to-use instruction: ALWAYS PREFER over sequential single-pack lookups when comparing entities, and it explains the distinction between company and drug types. It does not explicitly name a sibling tool (e.g., entity_profile) as an alternative, but the reference to sequential single-pack lookups is a clear alternative use case.

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 read-only, open-world, idempotent, and non-destructive behavior, and the description adds substantial context: parallel decomposition into facets, routing to 5,462 tools, return structure with gaps[], contradictions[], citations, and latency expectations. It also explains the 'not open-web search' nature and citation fetchability, which goes well beyond annotations. No contradiction found.

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 every clause provides functional detail that aids selection and use, such as account requirements, expected latency, and return packet semantics. It is front-loaded with the critical account/access caveat and maintains a logical flow from purpose to alternatives to behavioral details. It earns a 4 rather than 5 for being slightly dense, though not bloated.

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

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

Given the tool's complexity, no output schema, and the need to understand non-obvious behaviors, the description covers the performance envelope, output structure (evidence, confidence, source, gaps, contradictions), citation semantics, and latency. It also addresses edge cases like breaking news and second-hop iteration, making it effectively complete for an agent.

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

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

With 100% schema coverage, the baseline is 3, but the description adds value by explaining the depth parameter's behavioral consequences (gap recovery, lead-chasing) and providing concrete question examples for the question parameter. It also notes the paid plan requirement for 'thorough', which is not in 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 'grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, with a specific verb and resource scope. It explicitly distinguishes itself from sibling tools by noting 'this is NOT open-web search' and referencing ask_pipeworx as the alternative for single lookups.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly contrasts with siblings for single lookups and current-news topics ('prefer ask_pipeworx'). Also gives account/plan prerequisites that affect usability, making the decision boundary clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it returns top-N results with full input schemas and curated examples, directly callable without a second lookup. No contradictions.

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

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

The description is front-loaded with the core action, then includes a compact list of domains, the return value, and a usage directive. It is slightly long but every sentence carries useful information; 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 discovery tool with no output schema, the description sufficiently explains the return value (top-N tools with names, descriptions, and full schemas) and the direct-invocation behavior. It is complete enough for an agent to know when and how to use it.

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

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

The input schema covers 100% of parameters, including aliases and descriptions for query, q, task, limit, search, and description. The description only restates that a natural-language task description is expected, adding no new semantics beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It enumerates concrete domains (SEC filings, FDA drugs, FRED, Census, etc.) making it distinct from sibling data-retrieval tools like search_datasets or search_within.

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

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

The description gives explicit when-to-use: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies when not to use by contrasting with having a single answer, offering clear 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 readOnly/idempotent hints, and the description adds meaningful behavioral context beyond that: the patent source 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', the GDELT→GNews fallback for news, and the parallel fan-out nature of the call. No contradiction with annotations.

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

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

The description is dense and front-loaded with example queries and the core function. While lengthy, each sentence adds value (sources, returns, constraints, fallbacks). Slightly overlong, but justified by the tool's complexity; no filler.

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

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

No output schema exists, so the description covers return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and even provides URI examples. It also notes the soft-fail for patents. Missing error behavior for invalid tickers, but overall sufficient for successful invocations.

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 concrete examples ('AAPL', '0000320193'), explicitly states that names are not supported, and explains the value format ('ticker or zero-padded CIK'). This enriches the schema's descriptions with practical usage guidance.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call' and enumerates the specific data sources and return fields. It distinguishes itself from siblings by explicitly recommending against 'chaining single-pack SEC/XBRL/news lookups' and referencing 'resolve_entity' for name-based lookups.

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

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

Provides explicit when-to-use triggers with example queries ('Tell me about X', 'research Acme') and a clear alternative when not to use: 'names not supported (use resolve_entity first if you only have a name)'. Also includes 'ALWAYS PREFER over chaining...' for holistic requests.

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 destructive and idempotent behavior. The description adds context about the type of data affected ('previously stored memory', 'sensitive data') and the triggering conditions, which goes beyond the structured hints 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 two sentences, front-loaded with the core action, and every clause adds value—no filler or redundant restatement of the name.

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 single-parameter destructive tool, the description covers what it does, when to use it, and related tools. Annotations already communicate safety profile, so nothing critical is missing.

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 parameter is fully documented in the schema. The description reinforces 'by key' but adds no additional semantic detail about the key's format or behavior 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 starts with a specific verb+resource: 'Delete a previously stored memory by key.' It clearly distinguishes the tool from its siblings (remember, recall) by focusing on deletion, and the scope ('by key') adds precision.

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 contexts are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions companion tools ('Pair with remember and recall'), though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds useful behavioral context beyond these flags: it fetches the page, extracts title/description/key links, and emits a text blob in standard llms.txt markdown. This gives the agent a clear picture of the tool's side-effect-free but network-dependent operation.

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 appropriately sized and front-loaded, starting with the main purpose, then the method, then the output, and finally use cases. Each sentence adds value—there is no repetition or filler, and the structured 'Useful for' section is a compact way to convey usage scenarios.

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 an output schema, the description states the output is a 'single text blob ready to drop at site-root/llms.txt' and describes the extraction and formatting steps. Combined with the full parameter schema and readOnly/idempotent annotations, the agent has enough information to select and invoke the tool correctly.

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

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

Schema coverage is 100%: the url parameter is described as 'Full URL of the site to summarize' and max_links has its default and max defined. The description adds no additional parameter-level semantics beyond saying 'for any URL', so it does not exceed the baseline expected from complete schema documentation.

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 opens with a specific action and object: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes the tool from siblings like ai_visibility_check and scan_competitor_ai_presence by emphasizing the standard markdown output and extraction process, not just visibility or presence checks.

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 concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving the agent clear guidance on when to apply the tool. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it is one step below full exclusionary 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by specifying exactly what schema components are returned (fields + type, geometry type, record count, capabilities), which helps the agent anticipate the tool's output and confirm it is a metadata operation rather than a data query.

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 sentence that leads with the action and resource, then lists the return fields. It contains no filler or redundancy, making it highly efficient for an agent to parse.

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

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

Given the low complexity (one parameter), strong annotations (read-only, open-world, idempotent), and explicit listing of all return values in the description, the tool is fully specified. No output schema is needed because the description enumerates the expected information, and the operation is straightforward and safe.

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

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

The input schema already provides 100% coverage for the single 'url' parameter with a clear description and example. The tool description adds minimal extra semantic value beyond restating that the URL points to a Feature/Map Service layer. With full schema coverage, a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and identifies the exact resource ('ArcGIS Feature/Map Service layer's schema') plus the key outputs (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like query_layer or search_within, which likely focus on data retrieval rather than schema metadata.

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

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

The description implies when to use this tool by stating it retrieves schema information, but it does not explicitly compare to alternatives or mention exclusions. While the sibling tool names suggest distinctions (e.g., query_layer for data), the description provides no direct guidance on choosing between them.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds the exact fields returned (id, type, params, etc.), which is useful context. It doesn't mention the include_inactive parameter, but the schema covers that.

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

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

Two concise sentences with the main verb front-loaded. No filler, 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 adequately explains what the tool does, what it returns, and when to use it. The tool is simple with one optional parameter, and the description covers the essential context for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% for the single optional parameter, so the baseline is 3. The description says 'active subscriptions' which implies the default behavior but adds no extra syntax or format details 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 'List the caller's active subscriptions' with a specific verb and resource. It also lists the returned fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Explicit usage guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives concrete scenarios and implicitly contrasts with subscribe/unsubscribe.

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

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

Beyond the all-false annotations, the description discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and the team's daily review process. This is rich behavioral context with no contradiction 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?

Every sentence earns its place. The description front-loads the core purpose, then flows logically through when-to-use, exclusions, claim_token usage, and operational details. It is longer than typical but each clause adds essential information without redundancy.

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

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

Given the tool's moderate complexity (4 params, one nested object, no output schema), the description is exceptionally complete. It explains the full feedback lifecycle, identifies what falls outside scope, and sets clear expectations about rate limits and roadmap impact. The agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds value with usage tips like 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and explains the claim_token round-trip, which slightly exceeds schema guidance. No parameter info is repeated unnecessarily.

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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx and deep_research, and even narrows scope with 'ONLY for tools served by this Pipeworx connection.' This is a precise, unambiguous purpose.

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

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

The description gives explicit 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 provides a when-not-to-use with a concrete alternative: 'if the tool came from a different MCP server... file it with that server instead.' This fully covers decision-making.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it states the data comes from 'CF analytics-engine', explicitly notes 'no PII', describes the output as '(pack, tool, count)', and discloses caching behavior ('Cached 5min-1h depending on window'). No contradictions with annotations.

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

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

The description is front-loaded with a clear, evocative opening line ('What other AI agents are calling on Pipeworx right now') followed by concrete output details. The 'Useful for' list is structured and relevant, and the final sentence adds technical transparency. It is slightly long but every sentence contributes value, so it earns a 4 rather than a 5.

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

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

The tool is simple with one optional parameter and no output schema, so the description carries the burden of explaining return values. It clearly specifies the output ('top tools, top packs, and total call volume' and 'just (pack, tool, count)') and covers operational details like caching and data source. Nothing essential is missing for a tool of this complexity.

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

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

Schema coverage is 100% with the 'window' parameter fully described (enum values and semantics: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description adds extra nuance by explaining how caching varies with the window ('Cached 5min-1h depending on window') and reinforces the trade-off between windows, going slightly 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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. It specifies the resource (Pipeworx trending data) and scope (what other AI agents are calling right now), distinguishing it from sibling tools like discover_tools or search_datasets by focusing on aggregate popularity rather than general discovery.

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

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

The description provides explicit usage scenarios under 'Useful for:', including discovering hot data sources, confirming canonical tools, and assessing alignment with agent needs. It does not explicitly name alternatives or state when not to use this tool, but the use cases give 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?

Annotations already declare read-only, non-destructive, and idempotent behavior. The description adds substantial behavioral context: it explains the fill-check caveat ('realizable_edge_pp ≤ 0 means... do not trade it'), the semantic anchor threshold (≥0.30 Jaccard), and the partition placeholder filter, which an agent cannot infer from annotations alone.

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 densely informative, with clear section divisions: main purpose, event mode, topic mode, semantic anchor, partition filter, response shape, fill check, and cross-reference. Every sentence adds operational detail needed to invoke the tool correctly, and the structure front-loads the core verb and default call.

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 compensates by describing return fields (`opportunities[]`, `gap_pp`, `suggested_trade`, `partition_check`, `realizable_edge_pp`). It also documents edge-case behaviors like placeholder filtering and poor similarity rejection, making the tool fully comprehensible for an agent despite its algorithmic 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?

Although schema coverage is 100%, the description massively extends parameter meaning. It details what `event` and `topic` accept (slugs, URLs, seed questions), how they differ, and what specialized checks each mode triggers (date-axis ordering, partition_check, cross-event flattening). It also documents the no-argument default behavior, which the schema omits.

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 opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edge_tracker and polymarket_fill_risk by focusing on arbitrage detection across event and topic modes.

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 usage guidance: call with no args for trending_scan, pass `event` for single-event analysis, or pass `topic` for cross-event scans. It recommends the `event` mode for specific markets and directs users to polymarket_fill_risk for custom sizing, which qualifies as explicit alternatives.

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

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

The description goes well beyond annotations, disclosing caching ('Cached 1h at the KV level'), edge calculations ('after slippage'), Kelly caps ('capped at 0.25'), placeholder-slug filters, and diagnostics. It also explains why results may be empty (stale, gates, knobs), providing transparency into the tool's behavior. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is dense but well-organized with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence provides substantive information, and the purpose is front-loaded. Despite its length, it does not waste 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 complexity (9 parameters, no output schema) and the absence of structured return info, the description fully compensates by detailing response segments, fields like edge_pp_net, kelly_fraction, diagnostics, and the Fed-note exclusion. It leaves no ambiguity about what the tool returns and why.

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?

Although the schema already has 100% parameter descriptions, the tool description enriches the semantics by explaining interactions: e.g., 'min_kelly never filters them' for partitions, 'Edge is evaluated NET of slippage,' and the purpose of min_partition_leg_kelly. This contextual guidance is critical for correctly using the knobs.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the intended use case ('what should I bet on today') and the tool's output structure, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description gives strong usage context: 'agents discover opportunities without paging hundreds of markets' and explains tradeable-edge knobs to filter opportunities. It does not explicitly name alternative tools for when not to use it, but the specific use case and 'Built for' phrasing make the intended usage clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds significant behavioral context beyond those: snapshot write timing on cache-miss, meaning of gaps, 60-day TTL limits, and that decay metrics are based on daily closes net of default slippage, not intraday. This fully discloses operational behavior.

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

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

The description is long but information-dense and extremely well structured: purpose first, then args, then a clearly labeled RESPONSE section, then LIMITS. Every sentence adds value, and the use of uppercase labels makes it easy to scan.

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

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

Given there is no output schema, the description thoroughly explains the response shape with sub-fields for tracked, expired, and snapshot_dates, including derived metrics like trend and decay_pp_per_day. It also covers limitations (TTL, snapshot availability), making it complete for agent use.

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

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

Schema description coverage is 100% and the description reiterates the parameters with extra context: days has a default of 14 and max of 30 (schema says clamp 2-30), and window has a default of '1wk'. This adds clarity about defaults and intended usage beyond the schema alone.

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

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

The description clearly identifies the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering a specific actionable question about edge age and trend. This differentiates it from siblings like polymarket_edges (which presumably shows current edges) and other market 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 conveys when to use the tool by emphasizing that edge age changes trade interpretation ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies usage for historical edge context but does not explicitly state when to prefer an alternative tool, so it lacks a clear exclusion or alternative pointer.

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 non-destructive, but the description adds substantial behavioral context: it walks the order book ladder, computes VWAP, identifies thin_legs, and warns about partial basket fills converting an arb into unhedged directional position. This goes far 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 long and dense, but it earns its length by packing essential operational detail for a complex tool. The use of SINGLE-MARKET and BASKET headers helps structure the content, though it could benefit from more whitespace and bullet points. It is not tautological or padded; every sentence contributes.

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 compensates by enumerating return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) for both modes, covering failure modes (thin_legs, cannot_fill, forced_directional_risk) and the dominant risk scenario. It is complete enough to set accurate expectations for a complex tool.

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

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

Although schema coverage is 100% (baseline 3), the description adds meaningful semantics: it explains how size_usd is interpreted differently in single-market (spend vs proceeds) vs basket (settlement notional per leg), explains the default and clamp range, and explicitly maps market vs event side choices to mode-specific behavior. This is valuable beyond the schema descriptions.

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

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

The description uses a specific verb ('check') against a specific resource ('live CLOB order-book depth') and explicitly names the mode distinction: single-market vs basket. It clearly differentiates itself from siblings by naming polymarket_arbitrage and polymarket_edges as the tools it complements.

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 this tool: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also details the two distinct usage modes (market vs event) and provides triggering conditions, which is exceptionally clear 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?

Beyond the readOnly/idempotent annotations, the description discloses detailed behavioral traits: compatibility_warning conditions (two distinct cases), temporal_alignment semantics, skipped_cross_type/subtype counters, and the response structure. It even explains how to interpret failed matches (non-equivalent bet shapes vs unrelated events), providing substantial 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 long but well-structured with section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence carries information, though it is quite extensive; conciseness is slightly sacrificed for completeness, but the structure keeps it navigable.

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

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

Given no output schema, the description fully specifies the response format (leg-by-leg prices, spread[].top_spreads_pp), safety fields, and alignment logic. It covers edge cases such as skipped_cross_type and temporal misalignment, making it self-sufficient for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, with each parameter already having a description (including override semantics). The description adds the two-mode abstraction and usage examples, but mostly restates schema content; it does not introduce significant new parameter-level meaning beyond the mode concept.

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 states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' with a specific verb+resource and clearly differentiates two modes (topic shortcuts vs explicit ticker/slug pairing). It distinguishes itself from sibling tools by focusing on cross-venue comparison, not single-venue arbitrage or other tasks.

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

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

It explains when to use topic mode vs explicit mode, and warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool in favor of another, so the guidance is contextual but not fully exclusive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, providing a safety profile. The description adds value by stating 'Returns attribute rows (and geometry)' and noting the SQL-like nature of the where clause, which informs the agent about potential dialect limitations. This goes beyond what annotations provide, though it does not detail error behavior or pagination edge cases.

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

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

The description is three sentences: the first states the core purpose, the second lists key parameters, and the third provides a usage tip. It is front-loaded with the most important information, has zero fluff, and every sentence earns its place.

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

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

Given the tool's simplicity, the absence of an output schema is compensated by the description's mention of returning attribute rows and geometry. The parameter schema fully documents all inputs with defaults and examples. The description also integrates with the sibling workflow (from search_datasets). No critical information is missing for an agent to invoke this 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 already covers all parameters at 100% coverage, so the baseline is 3. The description adds value by explicitly highlighting recommended parameter combinations (where=1=1 + out_fields=*) and clarifying that out_fields is comma-separated, which reinforces and extends the schema's individual descriptions. This adds a practical usage layer 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 function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. The verb 'Query' and the specific resource type distinguish it from sibling tools like layer_info (metadata) and search_within (spatial search). It also mentions returning attribute rows and geometry, further clarifying its purpose.

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

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

The description provides context by referencing search_datasets as the source of the URL, implying a workflow. It also gives a specific sampling tip ('Use where="1=1" + out_fields="*" to sample'), which is practical guidance. However, it does not explicitly state when not to use this tool or mention alternatives like layer_info, so it falls slightly short of explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value beyond these by disclosing that the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys. This provides useful behavioral context not present in the annotations.

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

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

The description is three sentences long and front-loaded with the core function. Every sentence adds value: function, usage context, and scoping/companion tools. No redundant or vague wording.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, scoping, and relationship to sibling tools. It gives complete guidance for an agent to select and invoke the tool correctly.

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

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

The schema already provides a description for the key parameter (100% coverage), so the baseline is 3. The description adds meaningful examples of what keys might contain ('user's target ticker, an address, prior research notes'), going beyond the schema by illustrating usage. This justifies a 4 rather than a 3.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys, using specific verbs like 'Retrieve' and 'list'. It distinguishes itself from sibling tools remember and forget by explicitly pairing with them, and provides concrete use-case examples (target ticker, address, research notes).

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

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

It explicitly says when to use this tool: to look up context stored earlier without re-deriving it. It also names the companion tools (remember to save, forget to delete) and explains the scoping behavior, giving clear guidance on when to use it 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?

Discloses return payload details (source, citation_uri, raw event payload) and explains the side effect of mark_read:true, which affects subsequent calls. This goes beyond the annotations which only state read-only, idempotent, and non-destructive hints.

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

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

Concise and front-loaded; the first sentence states the purpose, and subsequent sentences each add useful detail 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 read-only tool with no output schema, the description covers input parameters, return value structure, side effects, and even alternative access. It is fully self-contained.

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

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

Schema already covers all 5 parameters, so the baseline is 3. The description adds value by giving a concrete example for type ("sec_8k") and clarifying the role of mark_read, though it doesn't mention limit or unread_only.

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 the tool pulls fired events from the subscription feed, with a specific verb and resource. It distinguishes itself from siblings by focusing on alerts from the evaluator's persisted feed.

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

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

Provides clear usage context: filtering by type/since, using mark_read to control which events are returned, and noting that polling works. It also explicitly offers an alternative for scripts/dashboards via a URL, which helps the agent decide when 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 read-only and non-destructive behavior. The description goes further by disclosing the multi-source fan-out, the GDELT→GNews fallback on rate limits/5xx, and the USPTO soft-fail due to API sunset. This gives the agent a clear picture of expected behavior and external dependencies.

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

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

The description is dense but well-structured. It opens with user intent examples, defines the function, then details sources, parameters, return shape, and alternatives. Every sentence contributes useful information without filler.

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

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

Despite having no output schema, the description specifies the return structure (changes[] grouped by source, total_changes, citation URIs). It covers source behavior, fallback logic, and parameter formats, making it complete enough for reliable 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%, so parameters are already well-documented. The description restates the `since` format and the `value`/`type` meanings without adding significant new semantic info. The context of how sources use `since` adds slight value but doesn't go beyond the schema's 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 what the tool does: it's a change feed for a company over a date window, fanning out to SEC, news, and patent sources. It uses concrete user-intent examples and explicitly distinguishes itself from the sibling entity_profile tool, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with example queries and gives an alternative: 'Use entity_profile instead when you want the static profile...'. It also offers parameter recommendations like 'Use "30d" or "1m" for typical monitoring.'

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

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

Annotations already convey read/write and idempotency hints. The description adds valuable behavioral context: key-value scoping by identifier, persistence differences (authenticated vs anonymous 24-hour retention), and the relationship to related tools. It does not contradict annotations.

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

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

The description is four sentences long, front-loaded with the primary purpose, followed by usage guidance and behavioral details. Every sentence earns its place without redundancy or vague phrasing.

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

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

For a simple two-parameter write tool without an output schema, the description covers what it does, when to use it, persistence behavior, and how it relates to siblings. The only minor gap is the absence of an explicit statement about the return value, but this is not critical for this straightforward operation.

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 schema already defines key and value with examples. The description adds no further parameter-specific semantics beyond restating that it stores a key-value pair, so it does not exceed the baseline for well-documented 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 a specific verb ('Save data') and identifies the resource (data for later reuse). It clearly distinguishes from sibling tools by explicitly pairing with recall and forget, and provides concrete examples of what to store.

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

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

It states 'Use when you discover something worth carrying forward' and gives a clear trigger condition. It names the alternatives ('Pair with recall to retrieve later, forget to delete') and explains persistence differences based on authentication, giving explicit context on when and how to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower. The description adds valuable context: it queries SEC EDGAR and RxNorm, auto-disambiguates input, cascades through internal endpoints, and returns citation URIs. This goes beyond the 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 front-loaded with natural-language query examples, followed by a crisp usage directive and organized type breakdown. It is a bit long, but every sentence adds functional value and none are wasted.

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 with no output schema, the description thoroughly explains what each supported type returns, including field names and citation URI format, making the tool's behavior clear enough for an agent to invoke correctly. No critical information is missing.

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 adds concrete examples (AAPL, 0000320193, ozempic) and specifies the return payload for each type, which enriches the parameter semantics beyond the schema's simple field 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/official identifiers needed by other tools, with specific example queries like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes from siblings by framing this as the prerequisite lookup step that other tools rely on.

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

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

It explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' giving a clear condition for use. However, it does not mention when not to use it or name any alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations by disclosing that it probes each entity (implying multiple external calls), ranks by score, and returns a ranked list with specific fields (score, confidence, signal density). This transparency about the multi-probe aggregation and output structure goes 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 efficient, using two sentences to convey purpose, operation, use case, and return format. Each sentence earns its place, and the most critical information (comparison action) is front-loaded. There is no redundant or filler content.

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

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

Despite lacking an output schema, the description fully explains the return value ('ranked list with score, confidence, signal density per entity'). It also explains the tool's workflow (probes with ai_visibility_check, ranks, surfaces most/least recognized) and provides a concrete use case. With annotations and schema covering safety and inputs, this description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with each parameter (models, _apiKey, context, entities) already described in the input schema. The description does not add significant new meaning about the parameters; it only mentions 'your brand + N competitors' for entities, which is already in the schema. The baseline of 3 for high schema coverage is appropriate, as the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities), and distinguishes from sibling tools like ai_visibility_check by emphasizing side-by-side comparison, ranking, and surfacing most/least recognized. The example use case ('does Claude know about us as well as our competitors?') further clarifies the purpose.

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

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

The description provides a clear context for when to use the tool: 'Useful for competitive AI-marketing audits.' It also implies an alternative by mentioning it probes each entity with ai_visibility_check, but it does not explicitly state when NOT to use it or when to use a sibling alternative instead. This falls short of a 5 because exclusions are not stated.

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 and idempotent, but the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists the timeout. This goes beyond the annotations and contradicts nothing.

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 ~120 words but every clause adds critical information: use case, data sources, return fields, ecosystem limits, and latency/failure behavior. It is front-loaded with the main purpose and structured logically 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 composite tool with no output schema, the description is remarkably complete. It lists exact summary fields, per-advisory detail, links, alternative versions, ecosystem constraints, and partial-failure behavior. No critical gaps exist for an agent to select and invoke the tool correctly.

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

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

The input schema already has 100% coverage for both parameters, including scoped package support and default version behavior. The description reinforces the purpose of each parameter in the context of the composite check but doesn't add significant syntax-level detail beyond what the schema provides, aligning with the baseline of 3.

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

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

The description clearly states the tool performs a composite npm package health check using deps.dev and bundlephobia, with a specific verb ('scan') and resource ('dependency'). It explicitly distinguishes itself from siblings by describing its one-call aggregation for questions like 'is X safe / popular / small'.

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

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

It explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear when-to-use and when-not-to-use guidance, plus an alternative path.

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/non-destructive behavior. The description adds valuable details beyond annotations: it returns dataset metadata (name, summary, record_count, owner/org, URL) and specifies the downstream use of the URL. It also notes the default scope (City of Irvine GIS) and that org_id can override. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the action and resource, includes examples of dataset types (parcels, zoning, parks), enumerates return fields, and gives clear downstream instruction. Every sentence is purposeful and 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?

The tool is a read-only search with 3 optional params and no output schema. The description covers what it does, what it returns, and how to use the results, making it self-contained. The schema provides parameter details and examples, so no significant missing context exists.

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 descriptions cover all three parameters (query, limit, org_id) with meanings, examples, and defaults. The description adds context that 'query' is a keyword and that the default org is City of Irvine GIS, which aligns with org_id. However, it doesn't elaborate on each parameter, and the schema already does the heavy lifting, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool searches City of Irvine GIS open geospatial datasets by keyword, using a specific verb and resource. It distinguishes from siblings like query_layer/layer_info by explaining that returned URLs should be passed to those tools, indicating this is a discovery tool, not a data querying tool.

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

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

The description provides clear context on when to use this tool: to find datasets by keyword, then pass the returned URL to query_layer or layer_info. It doesn't explicitly list exclusions, but the workflow is implied through the downstream usage guidance, giving better direction than many 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 read-only, open world, idempotent, and non-destructive. The description adds meaningful behavior not in annotations: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, the 200K char cap with truncation and flagging, and return details (offsets, similarity scores). No contradictions with annotations.

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

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

Four dense sentences, each adding distinct value: core function, use case, pairing, and technical constraints. No filler; front-loaded with the primary purpose and scoped immediately with 'inside a fetched record.'

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 3-parameter tool with no output schema, the description fully explains inputs (text, query, limit), outputs (passages with offsets and scores), limitations (200K cap, truncation flag), and how it relates to sibling tools (ask_pipeworx_grounded). The agent has enough to invoke correctly.

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

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

Schema coverage is 100%—all three parameters have descriptions. The description reinforces the text cap and query examples but adds no new parameter-specific semantics beyond what the schema already provides. 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 states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It gives concrete examples (SEC 10-K body, article, long tool result) and scopes itself distinctly from general search tools by emphasizing 'inside a fetched record.' The title and description are well aligned.

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

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

Explicitly provides when-to-use guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, offering a clear workflow and an alternative. This gives the agent actionable context for tool selection.

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

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

Annotations provide idempotency and non-destructive hints, but the description adds substantial context: OAuth requirement, feed always on, phone verification prerequisite, 10/day SMS cap, and the return of a subscription id. These details go beyond the structured fields and do not contradict any 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 purpose and return value, then organized into auth, types, and delivery sections. It is longer than necessary but every segment adds useful detail. The structure is coherent, though the parenthetical examples could be trimmed without losing core guidance.

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 5 type enums and 3 delivery channels, the description only lists 3 types and 2 channels, omitting patent_grant, clinical_trial, and webhook. While the schema compensates, the description uses the phrase 'Supported types:' which misleadingly implies exhaustiveness. It also does not mention the webhook channel's existence in the description body.

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 enriches this by giving concrete examples like items:['5.02'] = officer change, topic:'fed' for polymarket_edge, and series_id:'UNRATE' for fred_series, adding semantic meaning beyond the schema. It omits the other two enum types, but the schema already documents them.

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 opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts. The return value is also stated upfront.

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

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

The description explicitly states the OAuth account requirement and that anonymous/BYO users cannot persist subscriptions, serving as an exclusion. It also mentions the always-on feed and pull mechanism via recent_alerts, implying when to use that alternative. However, it does not explicitly name alternatives like list_subscriptions or unsubscribe, so it stops short of full 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 readOnly, idempotent, and openWorld hints. The description adds valuable behavioral context: it returns categorized example questions, includes the exact tool+argument shape, draws from the live catalog, and supports narrowing via 'topic'. No contradictions with annotations.

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

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

The description is long but well-organized and front-loaded with example queries that frame the tool's purpose. The categories list and invocation details are useful. Every sentence contributes value, and the length is justified for an onboarding tool.

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

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

Given no output schema, the description fully explains the return value (category-bucketed example questions with tool+argument shapes). It covers invocation, parameter behavior, and when to use, making it complete for an agent to select and call 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 already fully documents the 'topic' parameter with a list of valid values and the omit-for-spread behavior (100% coverage). The description reinforces this with examples ('finance', 'pharma', 'betting') but adds no new semantic information beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description precisely states the tool's purpose: it returns category-bucketed example questions with exact tool+argument shapes from the live catalog, positioning it as 'the onboarding entry point' and saying 'Use this FIRST'. This specific verb+resource+scope clearly distinguishes it from siblings like discover_tools or ask_pipeworx.

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

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

The description gives explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'), plus invocation guidance for the optional 'topic' parameter. It doesn't explicitly say when not to use it or name alternatives, but the 'FIRST' phrasing implies it's for initial orientation.

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

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

Annotations indicate a non-read-only, non-destructive, idempotent operation. The description adds key behavioral context: the row is deactivated, not deleted, and historical events remain available via recent_alerts. This goes 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 three concise sentences, front-loaded with the main action. Each sentence adds valuable information without redundancy or unnecessary detail.

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

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

For a simple one-parameter tool with no output schema, the description is highly complete: it covers purpose, ownership, side effects, and where related data remains available. It thoroughly supports an agent's decision to invoke this 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% and the id parameter is well-described as 'returned by subscribe.' The description adds the ownership constraint, clarifying that the id must belong to the caller, which is not in 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 'Cancel a subscription by id,' using a specific verb and resource. It also distinguishes itself from sibling tools like subscribe and list_subscriptions by clarifying that it deactivates rather than deletes, which is a unique behavior.

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

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

The description provides clear context: it is for canceling a subscription, with an explicit ownership constraint. It does not explicitly state when not to use it or mention alternatives like list_subscriptions for finding the id, but the deactivation note suggests how it differs from deletion.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context beyond that: the dual-path processing (structured financial vs. grounded fallback), the exact percent-delta math, the use of verbatim evidence, and the list of possible verdict outcomes. This substantially exceeds what annotations alone provide, though it does not detail potential error cases or latency.

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 longer than average but every sentence earns its place: it starts with recognizable query phrasings, states the primary use case, details the two execution paths, and summarizes the return payload. It is dense but not redundant. Slightly cluttered by the long list of example verbs, but overall 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?

Despite lacking an output schema, the description enumerates the return values (verdict, actual value with pipeworx:// citation, and reasoning). It explains the two routing paths and the tolerance mechanism, giving the agent enough context to invoke the tool correctly and interpret results. It does not specify error cases or timeouts, but for a read-only, idempotent query tool, the provided information is sufficiently 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 both parameters are already documented. The description reinforces claim semantics with examples ('Apple's FY2024 revenue was $400 billion') and adds meaning to tolerance_pct by explaining it overrides the wording-implied tolerance, with range (0.5–50) and a concrete use case (1–2 for hallucination detection). This goes beyond the schema's raw descriptions.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources. It uses specific verbs like 'verify', 'confirm or refute', and provides example phrasings ('Is it true that…', 'fact check'), making the purpose unmistakable. It also distinguishes itself from siblings by noting it replaces 4–6 sequential calls and covering both financial and non-financial claims.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides categorical guidance by differentiating the SEC EDGAR + XBRL fast path for company-financial claims from the grounded pipeline for any other factual claim, giving the agent clear routing logic.

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