Arcgis Delawareco

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe, reversible operation. The description adds valuable context beyond annotations: the default model is free, probing Anthropic requires a user-provided API key and direct payment, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. It stops short of discussing rate limits or potential accuracy caveats, but the added cost and configuration transparency earn a 4.

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

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

Three sentences: the first states the core purpose and output score, the second explains model options and cost, and the third lists return format and use cases. Every sentence contributes essential information, is front-loaded, and contains no fluff or redundancy.

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

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

For a tool with no output schema, the description appropriately includes the return shape (per-model fields + combined view). It also covers the key configuration details (default free model, optional paid Anthropic key), the target entity, and typical use cases. Combined with a comprehensive schema and strong annotations, the description fully equips an agent to decide when and how to invoke the 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?

All four parameters are fully described in the schema (100% coverage), so the description is not required to compensate. The description does reinforce the relationship between _apiKey and the 'models' parameter ('pass _apiKey to also probe Anthropic') and mentions the free default model, but it doesn't provide meaningful semantics beyond what the schema already explains. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes one or more LLMs for knowledge about an entity and produces a visibility score (0-100) per model. The verb 'probe' is specific, the resource is explicit, and the scope (business/brand/product/topic) is well-defined. It also distinguishes itself from sibling tools like 'ask_pipeworx' (which likely addresses the platform's own knowledge) and 'scan_competitor_ai_presence' (which focuses on competitors) by targeting any arbitrary entity.

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

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

The description gives clear use contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and practical configuration guidance (default free model, optional Anthropic via _apiKey). However, it does not explicitly state when not to use this tool or name alternative tools for different scenarios, so it falls short of a 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it 'fills arguments', returns stable pipeworx:// citation URIs, works on every tier, and is 'one fast call'. It does not contradict annotations and provides useful depth for a complex routing 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 longer than average but every sentence contributes: it front-loads the key directive, lists scopes, gives examples, and lays out alternatives. It is well-structured and dense with actionable guidance, though slightly verbose with repeated emphasis (e.g., 'START HERE' and 'default entry point' could be consolidated).

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

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

For a tool with no output schema and high complexity, the description is remarkably complete. It covers scope, routing mechanism, citation URIs, performance characteristics, tier compatibility, and clear escalation paths to sibling tools. The examples cover diverse domains, and the description even preempts the 'breaking-news' use case.

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 6 properties described), so the baseline is 3. The description adds no new parameter-level semantics beyond giving examples of valid questions, but the schema already fully documents 'question' and its aliases. The description's examples reinforce usage but do not compensate for a schema gap since there is none.

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 5,521 tools across 1,452 verified sources and returns structured answers with citation URIs. It uses specific verbs ('routes', 'returns') and enumerates covered domains (SEC filings, FDA, FRED/BLS, etc.), distinguishing it from general web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance is abundant: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', trigger phrases ('what is', 'look up', 'find'), and concrete exclusions ('Step up only when needed' for grounded or deep_research). It also clarifies that breaking-news is already handled by ask_pipeworx, preventing unnecessary escalation.

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 annotations, the description discloses that candidate routing improvements are enabled live during tests, that no candidate is currently active, and that it is a full working router rather than a thin wrapper. This adds substantial context about the experimental nature and current behavior, complementing the readOnly, idempotent, and openWorld annotations.

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

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

The description is concise and front-loaded, with each sentence providing essential information: beta status, identity, current state, usage guidance, and reassurance of full functionality. No wasted words.

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

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

Given the rich annotations and complete schema, the description effectively covers the tool's role, usage, and experimental status. It references ask_pipeworx for response shape, but since no output schema is provided, a brief explicit statement of the return format would make it fully self-contained. Still, this is a minor gap.

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 with descriptions for all six parameters, all aliases for 'question'. The description only refers to 'same arguments' without adding new parameter details, so it does not meaningfully go beyond the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,521 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by positioning it as the experimental edge for testing candidate routing improvements.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide what merges, and clarifies that with no active candidate it currently matches ask_pipeworx exactly, guiding selection among siblings.

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

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

The description adds significant behavioral context beyond the annotations: the extra LLM call cost, the guarantee to extract only from tool results, and the full set of refusal reasons. This goes well beyond the readOnly and idempotent hints provided.

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 every sentence earns its place: purpose, mechanism, response structure, usage policy, and cost. It is front-loaded with the key differentiator and avoids 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?

With no output schema, the description fully specifies both success and refusal response shapes, including all refusal reason enum values. Combined with annotations and schema, it provides complete contextual coverage for proper selection and invocation.

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

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

Schema coverage is 100% and all six parameters are aliases for the question, each described in the schema. The description adds no additional parameter-specific meaning, but the baseline of 3 applies because the schema carries the full explanatory burden.

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' with a specific verb+resource, and explains its routing and extraction flow. It differentiates from sibling ask_pipeworx by emphasizing evidence-quoted answers and explicit refusal behavior.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on...') and when not to ('prefer ask_pipeworx for casual lookups'). Also discloses the extra LLM call cost, giving the agent clear decision 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description goes far beyond: it discloses parallel fan-out, classifier output, resolver confidence levels, parent-event extraction, news fallback behavior, low-confidence short-circuit statuses, closed-market handling, and cancellation-rule risk. This is a model of behavioral transparency.

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

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

The description is long, but it is meticulously structured with bolded section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each section contains dense, non-redundant information that earns its place. While not front-loaded in a traditional sense, the first sentence clearly states the core purpose. The length is justifiable given 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 having no output schema, the description leaves almost nothing undocumented. It fully explains the resolver contract (match confidence, alternative matches, suggestions), parent-event extraction, news fallback, safety statuses, and resolution-rule risk. An agent can use this tool correctly and set expectations about edge cases without additional documentation.

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 explains all three parameters. The description adds valuable context beyond the schema: concrete examples of valid market inputs, the canonical slug/URL/question forms, and the trade-offs of depth ('quick' vs 'thorough') and include_raw (response size and use cases). This exceeds the baseline for full 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?

The description opens with a specific verb-plus-resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then details the resolution, classification, fan-out, and comparison behavior. This clearly distinguishes it from siblings like polymarket_arbitrage or polymarket_edges, which focus on different aspects of Polymarket analysis.

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 context is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also gives fan-out examples for specific bet types, which helps an agent understand when the tool is appropriate. It doesn't explicitly name sibling tools as alternatives, but the extensive examples and safety notes imply when the tool is and isn't trustworthy.

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

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

The description adds rich behavioral context beyond the annotations: it discloses data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled, handling of off-calendar fiscal years, result sorting by primary metric, and citation URIs. This complements the readOnlyHint/idempotentHint annotations without contradiction.

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

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

The description is dense but well-structured: front-loaded with user-intent examples, then scoping statement, then per-type details, then result behavior. Every sentence adds value with no redundancy or fluff.

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

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

For a tool with only two parameters and no output schema, the description covers input constraints, data sources, output format (paired data + citation URIs), sorting behavior, and scope (2–5 entities). It is fully complete for an agent to select and invoke correctly.

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

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

Schema already provides 100% coverage with descriptions for both parameters. The description adds extra meaning by explaining what data each type='company' vs 'drug' pulls (10-K financials vs adverse-event counts), which is not in the schema. For values, it reinforces the ticker/CIK and drug-name formats. This is a meaningful extension beyond schema.

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

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

The description explicitly states a side-by-side comparison of 2–5 companies or drugs in one parallel call, with example phrasings ('X vs Y', 'which is bigger'). It distinguishes from 'sequential single-pack lookups', making the tool's purpose unmistakable and differentiating it from siblings like entity_profile.

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

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

Provides direct usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists trigger queries and clarifies the two entity types (company/drug), making it clear when to use this tool versus alternatives.

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

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

Annotations only say readOnly/openWorld/idempotent, but the description adds rich behavioral context: account/paywall requirements, parallelism across 5,521 tools, 'never invented' gap handling, citation_uri fetchability guarantees, contradiction[] scans, semantic excerpting (not head-truncated), and latency expectations. It also explains the 'hop' field and depth-specific iteration behavior—far beyond what structured annotations express. No contradictions exist.

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

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

The description is long, but every sentence carries meaningful operational information: prerequisites first, then core purpose, alternatives, depth semantics, citation behavior, and performance. It is front-loaded with the most critical constraint (account required, use ask_pipeworx otherwise). It loses one point for being dense enough that an agent might need multiple parses to extract all rules, but nothing is 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?

With no output schema and high tool complexity, the description must explain the return contract—and it does: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers failure modes (empty gaps for current news), latency ranges, and depth-specific behaviors. This is as complete as a tool description can be.

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 both parameters are already well-described in the schema. The description adds value by explaining that 'question' can be broad/multi-part with concrete examples, and it clarifies the real-world trade-offs of depth (paid plan for 'thorough', gap-recovery and contradiction scans for 'standard'). This goes beyond the schema's enum descriptions, though the schema already 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 opens with a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' in ONE call. It explicitly distinguishes from open-web search and names the sibling alternative (ask_pipeworx) with concrete use cases ('compare X and Y's regulatory + financial exposure'). This leaves no ambiguity about what the tool does or when it is appropriate.

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 and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains how depth levels map to use cases (standard vs thorough) and what happens when the topic isn't in the structured catalog (gaps[]). This is textbook alternative-naming 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 non-destructive. The description adds valuable behavioral context: it returns ready-to-call tools with full input schemas and curated examples, eliminating the need for a second schema lookup. This goes beyond the annotation hints and clarifies the operational behavior 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 three sentences long, front-loaded with the core purpose and usage. The list of domains is long but serves to illustrate the breadth of searchable tools, and each sentence earns its place. Slightly verbose due to the domain enumeration, but still efficient.

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

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

For a discovery tool with no output schema, the description adequately covers what the tool does, when to use it, and what it returns. It explains the result shape (names, descriptions, schemas) and the 'ready to call' property. It lacks explicit mention of pagination or sorting details, but these are not critical given the tool's purpose.

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

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

Schema coverage is 100% and the schema already explains aliases and examples. The description adds no new parameter semantics beyond what the schema provides, so a baseline of 3 is appropriate. It does not confuse or mislead about parameters.

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

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

The description starts with 'Find tools by describing the data or task,' which is a specific verb+resource (find tools) and clearly differentiates this tool from the many data-query siblings. It explicitly states it returns top-N relevant tools with schemas, positioning it as a discovery/meta-tool rather than a direct data access 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 explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implicitly excludes direct answer-seeking by saying 'not just one answer,' which aligns with the tool's discovery purpose.

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 open-world. The description adds valuable behavioral details beyond these: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields with ordering (fundamentals sorted by period_end DESC), includes a soft-fail condition for the patents API ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and a fallback for news (GDELT→GNews). This significantly enriches the agent's understanding of how the tool behaves.

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

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

The description is a single dense paragraph, but it is front-loaded with example queries and a clear purpose statement. While it is long, every sentence contributes useful information: what it does, when to prefer it, what it returns, and input constraints. The structure is effective for its complexity, though it could benefit from slight formatting improvements (e.g., bullet points for return fields).

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 multi-source complexity and the absence of an output schema, the description is remarkably complete. It enumerates the exact return fields (cik, company_name, recent_filings with URIs, fundamentals fields, patents, news, LEI), explains fallback and failure behaviors, and provides input constraints. This gives an AI agent all the information needed to invoke the tool appropriately and interpret its results.

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

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

The input schema already has 100% description coverage for both parameters (type and value), including examples and constraints. The description adds redundant but useful context by restating the accepted formats ('Ticker "AAPL" or zero-padded CIK "0000320193"') and the exclusion of names. Since the schema is already rich, the description adds marginal value but does reinforce the key constraint, warranting a score above the 3 baseline.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific example queries ('Tell me about X', 'research Acme', etc.) and a detailed list of what it returns (cik, company_name, recent_filings, fundamentals, patents, news, LEI). This distinguishes it from sibling tools like compare_entities or single-source lookups by emphasizing the holistic, cross-source nature.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states what is not supported: 'names not supported (use resolve_entity first if you only have a name).' This provides clear alternatives and exclusion conditions, going beyond a simple purpose statement.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. However, it adds valuable context beyond annotations by specifying what is deleted ('previously stored memory') and the purpose ('clear sensitive data'), which helps the agent understand the nature of the 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 concise and front-loaded with the primary action in the first sentence. It then provides usage guidance in a compact, efficient manner. Every sentence contributes value with no redundancy or 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?

For a simple tool with one required parameter, no output schema, and strong annotations, the description fully covers the necessary context: what it does, when to use it, and how it relates to sibling tools. Nothing important 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% with a clear parameter description ('Memory key to delete') and example. The description only references 'by key' without adding new semantic detail, so it neither improves nor diminishes what the schema already provides.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Delete a previously stored memory by key.' This distinguishes it from siblings like remember and recall, which handle storage and retrieval respectively.

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: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), offering clear context for when this tool is appropriate 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?

The description explains the internal process (fetches the page, extracts title/description/key links, emits standard markdown) and output format, adding value beyond the readOnlyHint/idempotent annotations. It doesn't cover error handling, but the annotations already establish safety, so this is sufficient.

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: purpose, process/output, and use cases. Every sentence adds value, and the most important information is front-loaded. No redundant or verbose 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 tool with two well-described parameters, no output schema, and strong annotations, the description fully covers what, how, and when. It gives enough behavioral detail to invoke correctly without over-explaining.

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 both parameters with full descriptions (url and max_links with default/max), so the description doesn't need to add much. It implicitly clarifies the output is a text blob but doesn't elaborate on parameter formats beyond the schema, matching the baseline 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?

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb ('Generate'), resource ('llms.txt file'), and scope ('for any URL'). It also defines the output as a single text blob, making its purpose unambiguous and distinct from sibling 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 includes explicit use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's AI visibility. While it doesn't mention alternatives or exclusions, the context is clear enough to guide 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 affirm read-only, idempotent, and non-destructive behavior. The description adds value by detailing the specific return fields (fields, geometry, record count, capabilities), which is beyond the annotations. No contradictions were 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 a single, tightly written sentence that leads with the primary action and enumerates return content. Every phrase earns its place, with 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?

For a simple one-parameter metadata tool, the description fully covers the purpose, the input source, and the output components. The safety profile is provided by annotations, so no additional context is needed.

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 'url' parameter with a clear description and example. The tool description only repeats 'by url' and adds no semantic detail beyond the schema. Since schema coverage is 100%, the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and lists exact outputs (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling query_layer, which likely retrieves data instead of 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 provides clear context: it is for retrieving layer schema, not querying features. However, it does not explicitly name alternatives or state when not to use it, such as 'use query_layer for actual features'. Without an explicit comparison, it earns a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are returned by default. This goes beyond the annotation safety profile without contradicting it.

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 exactly two sentences: the first states purpose and returned fields, the second gives usage context. It's front-loaded, concise, and every word earns its place with no redundancy or fluff.

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

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

Given no output schema, the description compensates by listing all returned fields. It also covers the key use cases, user scoping, and the distinction between active and inactive subscriptions. This is complete for a list tool with a single optional parameter and rich annotations.

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 description for include_inactive is fully self-explanatory (100% coverage), so the description doesn't need to repeat it. The description does reinforce that active subscriptions are the default, which aligns with the parameter's default false. This is adequate but not additive 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: 'List the caller's active subscriptions.' It specifies the resource (subscriptions), the scope (caller's), and the action (list). It also distinguishes from siblings by explicitly mentioning use cases to review before adding more (subscribe) or to find an id to cancel (unsubscribe).

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

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

The description provides explicit guidance on when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly points to sibling tools (subscribe/unsubscribe) for the actual mutating actions, making the alternative 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?

Beyond the annotations, the description discloses rate limiting (5 per identifier per day), quota-free operation, the claim_token lifecycle for later status checks, and the team's daily digest behavior. These are meaningful behavioral traits that the annotations alone do not convey, and there is no contradiction.

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

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

Although the description is longer than typical, every sentence earns its place: purpose, when-to-use, when-not-to-use, token mechanics, rate limits, and impact. It is front-loaded with the primary purpose and remains dense 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?

With no output schema, the description adequately explains the return value and follow-up behavior via claim_token. It also covers prerequisites (no account needed), constraints (rate limit), and guidance for using nested context parameters, making it complete for a feedback 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%, so the baseline is 3. The description adds useful parameter-level guidance: passing claim_token with no other arguments, avoiding pasted user prompts, and framing feedback in terms of Pipeworx tools/packs. This enriches the schema's descriptions enough to warrant a 4.

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

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

The description opens with a specific verb and resource ('Tell the Pipeworx team') and clearly enumerates the feedback categories (broken, missing, needs to exist, praise). This distinguishes it from sibling tools like ask_pipeworx or deep_research, which are for querying rather than reporting feedback to the team.

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 lists when to use the tool (bug, feature/data_gap, praise) and when not to (tools from a different MCP server), even directing the agent to file elsewhere. It also clarifies how to handle uncertainty by referring to Pipeworx tool names, making usage boundaries unambiguous.

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 annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: it discloses the data source (CF analytics-engine), privacy (no PII), output shape (pack, tool, count), and caching (5min-1h depending on window). This goes well beyond the structured 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?

The description is compact and well-structured: a topic sentence, return summary, numbered use cases, and behavioral notes. Every sentence earns its place, and the most important information is front-loaded.

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

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

With one optional parameter, no output schema, and strong annotations, the description is sufficient. It explains the return content (top tools, top packs, total call volume), the data shape, caching behavior, and appropriate use cases. 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?

The schema already fully documents the window parameter with enums and trade-offs, so the baseline is 3. The description adds extra meaning by relating cache duration to the window choice ('Cached 5min-1h depending on window'), which is not in the schema. This additional detail justifies a 4.

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

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

The description clearly states what the tool does: it shows what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume over configurable time windows. This distinguishes it from siblings like discover_tools and search_datasets by focusing on aggregated agent usage.

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

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

The 'Useful for' list provides three explicit use cases: discovering hot data sources, confirming a canonical tool, and checking alignment with other agents' needs. However, it does not explicitly state when not to use the tool or mention alternatives, so it falls short of full 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?

Beyond the read-only/idempotent annotations, the description discloses critical behaviors: Jaccard similarity threshold, placeholder filtering (>20% returns null), the response structure, and the FILL CHECK caveat with realizable_edge_pp ≤ 0 — explicitly warning not to trade. This is substantial non-obvious context.

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

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

The description is long but front-loads purpose and usage in the first two sentences, then organizes supplemental details into labeled blocks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It earns its length given the tool's complexity, though tighter formatting would improve scanability.

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

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

For a tool with no output schema and rich behavior, the description covers modes, outputs, filtering rules, fill-check caveats, and a pointer to a sibling for sizing. It fully equips the agent to decide 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?

Although the schema already covers both parameters, the description adds meaning beyond the schema: `event` walks child markets and runs partition_check; `topic` searches related events and flattens markets; it gives concrete slug/seed examples and explains output differences between modes. This far exceeds the high-coverage 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 opens with a specific verb-resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates itself from siblings like polymarket_fill_risk and polymarket_edges by naming its distinct modes and explicitly pointing to another tool for custom sizing.

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 states when to call with no args for trending_scan, when to use `event` vs `topic`, and recommends `event` for specific markets. It also notes that cross-event mode catches date-boundary patterns single-event misses, giving clear selection 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?

Beyond the annotations (readOnly, idempotent), the description discloses extensive behavioral details: caching ('Cached 1h at the KV level'), slippage assumptions, Kelly capping at 0.25, response structure (by_segment, diagnostics), and why segments may be empty ('top-N stale, all candidates failed gates, knob dropped them'). It even explains the unreliability of Fed bets. This is exemplary transparency that 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 but every sentence carries substantive information, and it uses structural cues (ALL-CAPS segment names, parentheses, section headers like 'RESPONSE TOP-LEVEL') to organize the density. It is front-loaded with purpose and use case. A slight deduction because the sheer volume of detail can overwhelm, but it is not wasteful; each clause 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 complexity (9 parameters, no output schema, multiple model families and response segments), the description is exceptionally complete. It explains the response structure, the three segments with their underlying models and gates, the diagnostics for empty results, and the reason for excluding Fed bets. A caller can predict tool behavior and debug outcomes without additional documentation.

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, but the description adds meaningful context beyond the schema: for example, it explains that min_partition_leg_kelly exists because partition arbs return kelly_fraction_half=0 at the parent level (which the schema does not mention), and describes how min_liquidity/max_spread_pp are 'tradeable-edge filters' that drop unrealizable edges. This enriches the parameter's purpose and interactions.

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 opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings by focusing on Pipeworx disagreement and top-market scanning, and even names the intended use case ('what should I bet on today'). Purpose is unmistakable and distinct.

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

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

The description explicitly states when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides implicit guidance about exclusions (Fed bets are excluded from ranking due to unreliability) and when knobs like min_liquidity/max_spread_pp are needed. However, it does not explicitly name alternative sibling tools or state 'use X instead', which would fully clarify boundaries.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it details response structure (tracked/expired/snapshot_dates), explains snapshot-gap semantics, TTL limits, and that decay is computed from daily closes. This is rich, non-obvious information that materially affects interpretation.

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

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

The description is long but well-structured with clear sections (Args, RESPONSE, LIMITS) and is front-loaded with the purpose. Every sentence adds functional value, though the 'nobody is willing to take' phrase is illustrative rather than strictly necessary.

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 carries full responsibility for explaining return values and constraints—it does so thoroughly, covering every field in tracked/expired/snapshot_dates, trend semantics, decay calculation, and data availability boundaries. This is complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters, and the description essentially repeats the schema's definitions (defaults, window values). It adds no new semantic detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('Edge persistence and decay telemetry') and immediately distinguishes from siblings by focusing on historical persistence rather than listing current edges. It even explains the core question it answers ('how long has this edge existed and is it shrinking?').

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 clearly implies when to use the tool—when edge age/decay matters—by contrasting fresh vs. old edges. However, it does not explicitly name alternative tools or state when not to use it, leaving sibling differentiation implicit rather than direct.

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?

While annotations already declare read-only and non-destructive behavior, the description adds substantial operational detail: it walks the order-book ladder, returns specific fields like slippage_pp and max_fillable_usd, explains the meaning of size_usd differently for single-market vs basket modes, and notes the 'REQUIRES one of market or event' constraint. No contradiction with annotations.

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

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

The description is long but deliberately structured with labeled sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and every sentence carries necessary information. The opening one-liner is a compact summary, and the details are dense but not repetitive. Slightly more than minimal, but appropriate for a tool with two distinct modes and multiple return fields.

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

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

Given no output schema, the description compensates by enumerating return values for both single-market and basket modes, including edge cases like thin_legs[] and forced_directional_risk. It also sets expectations with default sizes and mode-specific behavior. The description is fully self-contained for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful layer: it clarifies that market and event are mutually exclusive, defines side defaults (single-market default buy_yes; basket auto based on partition sum), and gives the clamp range for size_usd (10–1,000,000) plus mode-dependent interpretation. This goes beyond the schema's basic 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 opens with a precise summary: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly names the verb (check) and resource (fill risk/edge against order-book depth). It explicitly differentiates from siblings by stating when to use this tool over polymarket_arbitrage or polymarket_edges, making its unique role unmistakable.

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

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

The description gives explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequence of not using it (partial basket fills convert an arb into an unhedged directional position), providing clear when-to-use context and excluding 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 the read-only annotation by detailing behavioral nuances: safety fields, compatibility_warning triggers, temporal alignment, skipped cross-type/subtype counters, and a caution that pre-mapped ≠ tradeable. This provides a thorough model of the tool's behavior.

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

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

The description is long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, etc.). Each segment adds necessary detail, though the topic list in the description duplicates the schema's enum, adding minor 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?

With no output schema, the description thoroughly explains the response structure, safety signals, and limitations, making it self-sufficient for an agent to understand expected behavior and edge cases.

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 describes all parameters with 100% coverage, including override semantics. The description reiterates these and adds the notion of two usage modes, but does not significantly extend parameter meaning beyond the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling Polymarket-only tools by focusing on the cross-venue comparison, and the two modes and response summary make the purpose unmistakable.

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

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

The description explicitly describes two modes (topic shortcuts vs. explicit ticker/slug), clarifying when to use each. It also warns that most pre-mapped topics return compatibility_warning, signaling when the tool may not yield tradeable spreads, though it does not name alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds beyond annotations by stating that the tool returns attribute rows and geometry, and provides a sampling tip. This enriches the agent's understanding of behavior without contradicting 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 two sentences, front-loaded with the core purpose and syntax, and concludes with a practical tip. Every sentence adds value, with no filler or repetition of schema details. It is efficiently structured for quick comprehension.

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 lack of an output schema, the description appropriately mentions that the tool returns attribute rows and geometry. It also links to search_datasets for obtaining the url, covers the key parameters, and gives a sampling pattern. With rich annotations and full schema coverage, this is 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?

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining the SQL-like nature of the 'where' parameter and by suggesting a specific combination (where="1=1" + out_fields="*") for sampling. This goes beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. The specific verb 'query' and the resource type distinguish it from sibling tools like search_datasets (for finding datasets) and layer_info (for metadata). It also mentions returning attribute rows and geometry, which 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 implies a workflow by saying 'from search_datasets', indicating the url should come from that tool. It also gives a concrete usage tip for sampling (where="1=1" + out_fields="*"). However, it does not explicitly state when not to use this tool or name alternatives, 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, destructiveHint, and idempotentHint, so safety is covered. The description adds meaningful behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and explains listing behavior when key is omitted. This goes beyond annotations and clarifies privacy scoping, which is valuable for an agent.

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

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

The description is compact and front-loaded. It starts with the primary action, then provides usage context, scoping, and tool pairing. Each sentence contributes distinct information with no filler or repetition of annotations.

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 one optional parameter, no output schema, and safe annotations (readOnly, idempotent, non-destructive), the description covers the purpose, usage context, scoping, and relates to sibling tools. It is complete for an agent to invoke correctly without needing further clarification.

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 key parameter is described as 'Memory key to retrieve (omit to list all keys)'). The description adds semantic context by giving examples of what keys represent (user's target ticker, address, prior research notes), helping the agent understand the nature of stored values. This enhances 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 the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the resource (memory keys) and distinguishes itself from sibling tools by explicitly mentioning remember and forget, making its role in the save/recall/delete trio 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 clear guidance on when to use the tool: 'Use to look up context the agent stored earlier' and gives concrete examples (target ticker, address, research notes). It also mentions pairing with remember and forget to save or delete, implying the appropriate alternatives. It does not explicitly state exclusions, but the context is strong.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description states that setting mark_read:true will 'flag returned events read so the next call only shows newer ones,' which mutates state and makes the tool non-idempotent across calls. This directly contradicts the readOnly and idempotent annotations, so the score is 1.

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 and front-loaded with the core purpose. Each sentence adds useful information: what the tool returns, how to filter, and the availability of an HTTP endpoint alternative. It is concise without sacrificing key details, though the HTTP endpoint sentence is somewhat tangential.

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 lack of an output schema, the description adequately explains the return value structure (source, citation_uri, raw payload). It explains mark_read behavior and mentions polling suitability. It could have described limit behavior or unread_only, but the schema covers those, so the description is sufficiently complete for a simple retrieval tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra context: it provides a concrete example for type ('sec_8k'), clarifies since as an ISO timestamp, and explains the effect of mark_read:true on subsequent calls. It does not cover limit or unread_only, but those are adequately described in the schema, so the description adds enough to warrant a 4.

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

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

The description starts with a specific verb 'Pull' and clearly identifies the resource: 'fired events from your subscription feed.' It also explains the return contents (source, citation_uri, raw payload) and distinguishes itself from siblings like list_subscriptions by focusing on alerts rather than subscription management.

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

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

The description provides clear context for when to use the tool: filtering by type and since, using mark_read to control subsequent calls, and noting that polling works fine. It also mentions an alternative HTTP endpoint for scripts/dashboards, giving explicit guidance on alternative access. However, it doesn't explicitly contrast with sibling tools beyond that.

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 substantial behavioral detail: fan-out to SEC EDGAR, GDELT→GNews fallback logic (GDELT preferred, GNews on rate-limit/5xx), USPTO soft-fail due to PatentsView API sunset, and return structure (changes[] grouped by source + total_changes + citation URIs). 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 but purposeful. Every sentence adds value: example intents aid pattern-matching, then the core functionality, data sources, fallback behavior, date format, output structure, and alternative tool. The structure is logical and front-loaded with the most important use-case info, and while long, it 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?

This tool has no output schema, but the description compensates by detailing the return shape (changes[] grouped by source, total_changes count, pipeworx:// URIs). It also covers input formats, data source behaviors, and an explicit alternative for static profiles. An agent has enough context to select and invoke this tool correctly without additional documentation.

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

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

Schema covers all 3 parameters, but the description enriches them significantly: explains `since` accepts ISO or relative shorthand with examples ('7d','30d','3m','1y') and recommends '30d' or '1m' for monitoring; clarifies `value` as ticker or zero-padded CIK; notes `type` only supports 'company'. This goes beyond the schema's simple 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 opens with natural-language intents ('What's new with X', 'latest on Y') then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the resource (company change feed) and the action (get changes), and explicitly distinguishes from entity_profile, naming it as the alternative for static profiles. This clearly differentiates from siblings.

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

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

Provides explicit usage context through example queries and states when to use the tool. It also gives a clear exclusion: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' The 'ONE parallel call' phrasing signals that this tool replaces separate calls to SEC/GDELT/USPTO, giving practical guidance on when to invoke it.

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

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

Beyond the annotations (which mark the operation as non-read-only, idempotent, and non-destructive), the description adds meaningful behavioral context: data is stored as a key-value pair scoped by user identifier, with persistence differences between authenticated (persistent) and anonymous (24-hour) sessions. This clarifies scope and retention without contradicting annotations.

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

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

The description is concise and well-structured: it delivers the core purpose first, then usage guidance, then storage details, and finally complementary tool references. Each sentence adds value without unnecessary fluff or redundant restating of the title.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers all essential aspects: purpose, when to use, storage scoping, persistence behavior, and relationships to sibling tools. No significant gaps remain for an agent to correctly select and invoke the tool.

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

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

The schema already provides full coverage (100%) for both parameters with clear descriptions. The tool description adds practical examples of values (resolved ticker, target address, etc.) that enrich semantic understanding of what should be stored, going beyond the schema's basic 'key' and 'value' definitions.

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

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

The description clearly states the tool's purpose: to save data for later reuse across conversations or sessions. It uses a specific verb ('Save'), identifies the resource ('data the agent will need to reuse later'), and distinguishes itself from sibling tools by explicitly naming 'recall' and 'forget' as retrieval and deletion counterparts.

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: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' It also mentions pairing with 'recall' for retrieval and 'forget' for deletion, offering clear alternatives and context.

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

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

Beyond the readOnly annotation, the description discloses internal cascading through multiple endpoints, auto-disambiguation, and specific return fields (ticker, CIK, RxCUI, citation URIs). This adds meaningful behavioral context without contradicting annotations.

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

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

The description is well-structured, front-loaded with examples and usage directive, and every section (supported types, input flexibility, internal behavior) earns its place. It is informative without being verbose.

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

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

With no output schema, the description compensates by detailing the exact return values and citation URIs for both entity types. It also clarifies the internal lookup cascade, making the tool's behavior and expectations fully understandably for an agent.

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

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

Schema coverage is 100% and already describes the value parameter thoroughly. The description adds 'auto-disambiguated' and specifies which identifiers are accepted, providing a small enhancement beyond the schema, but largely repeats schema content.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific verbs ('resolve'), resource types ('company', 'drug'), and example queries. It distinguishes from sibling tools like entity_profile by focusing on ID lookup rather than profile details.

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 instruction 'Use FIRST whenever you have a name but need an ID' provides clear direction, and supported types with examples cover when to use. The note about replacing 2-3 manual lookups reinforces the intended 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?

The description discloses that the tool probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density—behavior beyond the readOnly/idempotent hints. It clarifies the composite nature without contradicting annotations.

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

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

The description is three sentences, front-loaded with the primary action, then the mechanism, use case, and return value. Every sentence adds unique value with no redundancy or fluff.

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

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

Given the tool's moderate complexity (multi-entity comparison, optional models/API key), the description covers the essential what, how, when, and expected output. The rich schema covers parameter details, and annotations cover safety, so no critical context 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% for all four parameters, so the schema already documents each parameter thoroughly. The description adds minimal extra meaning (e.g., 'your brand + N competitors' for entities), but this is also present in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by specifying the mechanism 'Probes each entity ... with ai_visibility_check' and the ranking 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 a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example question. It implies when to use this tool versus ai_visibility_check for a single entity, though it does not explicitly state exclusions or alternative tools for comprehensive coverage.

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/openWorld/idempotent annotations, the description discloses key behavioral traits: it fans out across two sources, returns a structured summary block, handles partial failures gracefully, lists sources_failed on timeout, and warns that the first bundlephobia measurement may take 5-30s. This is rich context.

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

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

The description is longer than typical but each sentence adds value: purpose, usage, return fields, limitations, and failure behavior. It is well-structured and front-loaded with the main purpose, though slightly dense.

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

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

Given there is no output schema, the description fully covers return values (summary block fields, advisories, links, alternative versions), ecosystem scope, and degradation behavior. This is complete for a composite tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema; it mentions npm-only scope and default version behavior, both already stated in the schema. No extra examples or constraints are provided.

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

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

The description explicitly states the tool's purpose: a composite 'should I add this npm package' check that aggregates data from deps.dev and bundlephobia. It clearly identifies the resource (npm package) and the specific data sources, distinguishing it from any sibling 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?

It provides explicit usage triggers ('Use whenever an agent asks...') and names an alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This fully covers when to use and when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value beyond these by specifying the exact returned fields (name, summary, record_count, owner/org, url) and the intended downstream action. 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 two sentences, front-loaded with the primary action and scope, followed by the return value and usage. Every word contributes, with no redundancy or irrelevant details.

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

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

Given the tool has no output schema, the description fully compensates by enumerating the return fields. It also explains how to chain with sibling tools (query_layer/layer_info) and notes the optional org_id override, making the tool self-contained 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?

The input schema already provides 100% coverage for all three parameters (query, limit, org_id) with clear descriptions. The tool description adds minor context by mentioning the default Delaware County GIS scope and the workflow, but it does not substantially enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool searches Delaware County GIS open geospatial datasets by keyword and returns each dataset's metadata. It distinguishes itself from related tools by explicitly mentioning the Feature Service URL is passed to query_layer/layer_info, which are sibling tools.

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

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

The description provides a clear workflow by instructing the agent to pass the returned URL to query_layer/layer_info, implying usage for dataset discovery. However, it does not explicitly state when not to use this tool or contrast it with other search-focused siblings like search_within, so it is slightly incomplete.

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, so the safety profile is known. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation flagging, and return fields (passages, 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?

The description is compact but information-dense. It front-loads the core purpose, then gives usage context, then technical mechanics. Every sentence earns its place—no fluff, no repetition of schema details.

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

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

Even without an output schema, the description fully covers what the agent needs: return format (top-N passages with offsets and similarity scores), edge behavior (truncation for >200K chars), and the underlying retrieval approach for comprehension. It is complete for a tool of this complexity and safety profile.

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 (text, limit, query) have clear descriptions in the schema. The description enriches this with example queries and reiterates the 200K char cap, but the schema already does the heavy lifting. This meets the baseline 3 for high schema coverage; it does not significantly exceed it.

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 is specific and actionable: 'Semantic search INSIDE a fetched record' with a clear verb ('search'), resource ('source'), and scope ('inside a fetched record'). It also distinguishes itself from siblings by explaining its role versus ask_pipeworx_grounded, making it easy for an agent to know when to choose this tool.

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

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

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and how-it-fits-with-alternatives guidance.

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

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

The description goes well beyond the annotations by disclosing authentication needs (Pipeworx OAuth account), delivery constraints (SMS 10/day cap, phone verification), webhook signing and auto-disable behavior, and the fact that the feed is always on. This enriches the safety profile (readOnlyHint=false) with concrete operational details.

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

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

The description is dense but well-structured, opening with the core purpose, then covering requirements, types, and delivery channels in a logical flow. Every sentence provides necessary information, and the length is justified by 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?

The description covers the main functionality thoroughly, but it lists only three of the five subscription types (sec_8k, polymarket_edge, fred_series) and omits webhook from the top-level delivery summary (though it appears in the schema). Since patent_grant and clinical_trial are absent from the description, an agent might underestimate the tool's full range despite schema coverage. No output schema exists, so return value clarity is limited to stating the subscription id.

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

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

Even though the input schema already has high coverage, the description adds valuable semantics: it gives specific examples for sec_8k, polymarket_edge, and fred_series, and details delivery channel parameter formats (email, sms, webhook) with constraints like phone verification and HMAC signing. This goes beyond the schema's property descriptions.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes the tool from siblings like list_subscriptions and unsubscribe by focusing on creation and returning a new subscription id. The variety of supported types and delivery channels further clarifies its role.

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 clear context on when to use the tool: to create a persistent monitoring subscription with optional delivery channels. It states prerequisites (OAuth account, verified phone for SMS) and mentions the always-on feed with alternative retrieval methods (recent_alerts or GET registry.pipeworx.io/alerts.json). However, it does not explicitly name sibling tools as alternatives or exclusions, so it falls short of a 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 the operation read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context: it explains the output structure (category-bucketed examples, each with tool and argument shape), that results come from a 'live catalog of thousands of tools,' and how the topic parameter affects the response. This exceeds what annotations alone 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 a single, information-dense paragraph that front-loads the purpose with example queries and later covers output, parameter behavior, and usage timing. It is arguably slightly longer than needed, but every sentence contributes meaningful context and the structure is logical.

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?

There is no output schema, so the description must explain return values on its own. It does so comprehensively: it lists the exact categories returned, states the format (tool + argument shape), and explains the optional parameter's effect. Combined with the strong annotations, this makes the tool's behavior fully predictable.

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% since the topic field has a description listing allowed values. The description supplements this with concrete examples ('finance', 'pharma', 'betting') and clarifies that omitting the parameter returns a cross-category spread, adding practical guidance beyond the schema.

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

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

The description clearly states the tool's purpose: it 'Returns category-bucketed example questions ... each with the exact tool + argument shape that answers it.' It is an onboarding entry point, distinct from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists tools). The opening example queries reinforce the function.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' This provides a clear when-to-use context, but it does not explicitly state when not to use it, so it stops short of a perfect score.

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 non-readonly, idempotent, and non-destructive behavior. The description adds crucial behavioral context: ownership restriction, deactivation instead of deletion, and that historical events remain available via recent_alerts. These details go beyond the annotations and provide a complete picture without contradiction.

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

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

Three short sentences, each adding distinct value: what it does, who can do it, and what happens afterward. No filler or repetition; the most important information is front-loaded.

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

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

Given the tool's simplicity (one required param, no output schema) and the presence of annotations covering idempotency and destructiveness, the description covers all necessary operational details: ownership, deactivation semantics, and follow-up availability. The agent can confidently invoke and interpret the result.

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 fully describes the single parameter (id as subscription uuid from subscribe). The description reinforces this by saying 'by id' and 'returned by subscribe' (which is in the schema), but it doesn't add new semantic meaning beyond the schema, so it meets the baseline 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?

The description uses a specific verb ('Cancel') and resource ('subscription'), clearly distinguishing this from sibling tools like subscribe and list_subscriptions. It also clarifies the subtle behavior of deactivation rather than deletion, making the tool's exact 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 states the action and the key prerequisite (ownership enforcement), which helps the agent know who can use it. It doesn't explicitly mention when to prefer this over alternatives, but the context (subscribe, list_subscriptions) makes 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description goes well beyond this by disclosing the dual-pipeline behavior (SEC EDGAR fast path vs. grounded pipeline), the verdict categories, citation inclusion, and the efficiency gain. This gives substantial context about how the tool behaves.

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 carries unique information: trigger phrases, routing logic, return values, and efficiency rationale. It is front-loaded with examples and ends with a powerful summary. Slight verbosity is justified, but it could be tightened without losing 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?

Despite having no output schema, the description explicitly lists the return types (verdict, value with citation, reasoning) and explains the two execution paths. It covers when to use, parameter behavior, and limitations of the tolerance via schema. Given the tool's complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful nuance for tolerance_pct (explains default derivation, cap of 5, and the hallucination-detection use case), and provides examples for claim. This goes beyond the schema's basic description, adding practical 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 opens with natural-language triggers ('Is it true that…' / 'fact check'), then states a specific verb+resource: 'natural-language claim verification against authoritative sources'. It clearly distinguishes itself from siblings by claiming to replace 4–6 sequential calls, making its scope unique.

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 states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for company-financial vs. other claims. However, it doesn't name alternative sibling tools or give explicit when-not scenarios, so it lacks the full exclusions seen in the high example.

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