Arcgis Mckinney

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: default model is free, passing `_apiKey` enables Anthropic calls with direct cost to the user, and the return structure is disclosed. This goes beyond the bare minimum for a read-only 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 compact—three sentences—and front-loaded with the core action and purpose. It includes the essential details (default model, optional key, return format, use cases) without redundancy or fluff. Every sentence contributes useful information.

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

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

Given the tool's moderate complexity (4 params, 1 required, no output schema), the description covers the key aspects: what it does, how to scale models, output shape, and typical applications. It doesn't mention error handling or rate limits, but those are not critical for a read-only probe with clear schema and annotations. Overall, it is sufficiently complete for an agent to select and call it correctly.

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

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

Schema coverage is 100% (all parameters have descriptions), setting a baseline of 3. The description adds extra meaning by explaining the free default vs paid Anthropic option and the significance of `_apiKey` (BYO key, pay directly), which is not in the schema. It also clarifies the `models` parameter's behavior implicitly. This adds value beyond the structured fields.

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 ('Probe') and resource ('one or more LLMs') and clarifies the scope (business/brand/product/topic). It clearly distinguishes itself from siblings like ask_pipeworx by focusing on scoring visibility rather than answering questions. The output format (score 0-100) is explicit.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to invoke it. It does not explicitly mention alternatives or when not to use it, but the use cases are sufficient guidance. Sibling tools like scan_competitor_ai_presence could overlap, but the description's focus on probing and scoring is distinct enough.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about routing to 5,462 tools, filling arguments, returning citation URIs, and being a fast default entry point. It doesn't mention potential failure modes or coverage gaps, but given the strong annotation coverage, this is acceptable.

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-loaded with the most critical instruction ('PREFER OVER WEB SEARCH'), then domain list, examples, and differentiation from alternatives. Every sentence earns its place, though it could be slightly condensed without losing meaning.

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 simple schema (one question parameter), no output schema, and the tool's role as a default entry point, the description is exceptionally complete. It explains the tool's purpose, usage, alternatives, examples, and even behavior for news queries, enabling an agent to select and invoke it correctly in a wide range of scenarios.

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 only meaningful parameter (question) and all its aliases, so schema coverage is 100%. The description adds examples and guidance on what kinds of questions to submit, but doesn't independently explain the parameters. Baseline of 3 is appropriate.

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

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

The description clearly defines ask_pipeworx as a routing tool that answers factual questions by dispatching to specialized tools and returning structured answers with citations. It explicitly distinguishes itself from 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH' for factual queries, 'Use whenever the user asks...' with examples, and 'START HERE for most questions.' It also tells when to step up to ask_pipeworx_grounded or deep_research, and clarifies behavior for breaking-news queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: no candidate is currently active, so it matches ask_pipeworx exactly, and it is a full working router with no fallback. This provides useful experimental transparency beyond the annotations.

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

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

The description is a single paragraph of 3 sentences, front-loaded with the beta distinction and current status. While slightly verbose, every sentence carries useful information about behavior, usage, and current state. It could be tightened but is effectively structured.

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

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

Given the tool's complexity and lack of output schema, the description covers purpose, usage, current routing state, and safety profile well. It references 'same response shape' as ask_pipeworx, indirectly specifying return format, but does not explicitly describe the response structure, leaving 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 covers all 6 parameters with descriptions (100% coverage), so baseline is 3. The description says 'same arguments' as ask_pipeworx but adds no additional semantics about parameter usage, aliases, or formats beyond what the schema already provides.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with identical routing capabilities, which distinguishes it from the stable sibling. It uses a specific verb+resource structure: 'Ask Pipeworx Beta' with the universal router context.

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 to use it exactly like ask_pipeworx when you want the newest routing, and mentions that results are compared against the stable router, providing clear guidance on when to choose the beta over the stable version.

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

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

Annotations already declare readOnlyHint, but the description adds significant behavioral detail: it routes through other tools, extracts answers only from tool results, returns a structured response with refusal reasons, and costs an extra LLM call. It also details failure modes (not_in_source, no_tool_match, etc.), which is valuable beyond annotations.

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

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

The description is information-dense and well-structured: it states the core value, explains the mechanism, lists output format and refusal reasons, then gives usage guidance and cost tradeoff. Every sentence contributes distinct information without redundancy.

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

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

Despite no output schema, the description fully specifies the return object on success and refusal, covers failure modes, and explains the cost/usage tradeoff relative to sibling. It is complete for an agent to decide when and how to invoke the tool, even considering the routing complexity.

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

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

Schema coverage is 100%, with all aliases documented. The description does not add new parameter-level details beyond the schema, but it does imply the question is the sole input and explains the tool's internal argument-filling behavior, which marginally compensates. 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 identifies a specific verb ('ask') with a distinct resource ('Pipeworx — Grounded') and differentiates from sibling 'ask_pipeworx' by emphasizing hallucination resistance, verbatim evidence, and explicit refusal behavior. It states the scope (high-stakes reads) and the unique value proposition.

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 the agent must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). Mentions cost tradeoff, providing clear decision 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 far beyond the annotations by disclosing detailed behavioral traits: the resolver contract (market_match_confidence, alternatives), safety short-circuiting for low-confidence matches, handling of closed markets, parent-event extraction, news fallback mechanisms, and cancellation-rule risk. No contradiction with the readOnly/openWorld/idempotent annotations.

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

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

The description is very long but well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and starts with the core purpose. Some redundancy exists (e.g., the anecdote about 'audited arb-bot ledgers') and the length could be trimmed, but the density of useful information and the front-loaded structure earn it a strong score.

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 explains return shapes (result.market, result.analysis, result.evidence), resolver metadata, parent-event data, news fields, and status codes for edge cases. It covers even niche scenarios like cancellation rules and illiquid wide spreads, making it highly complete for a complex tool.

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

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

Schema coverage is 100%, and the schema already describes each parameter. The description adds substantial context, such as input formats for 'market' (slug, URL, question text), fan-out examples that clarify 'depth', and the response-size implications of 'include_raw'. This extra meaning justifies a score above the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on comprehensive research and evidence gathering.

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

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

Explicit usage guidance is provided: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' Additional behavioral guidance like 'ALWAYS inspect these before trusting the analysis block' is given. However, it does not explicitly mention when not to use or name alternative sibling tools, so it falls short of a 5.

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

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

While annotations already indicate read-only, open-world, idempotent, non-destructive behavior, the description adds rich context: parallel call behavior, data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, and sorting by primary metric. This goes well beyond annotations and no contradiction exists.

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 two sentences but efficiently packs in trigger phrases, usage guidance, data sources, fiscal-year nuance, sorting, output format, and performance benefit. It is front-loaded with the core purpose and every sentence contributes value, though it could be slightly tightened.

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

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

Given no output schema, the description covers the main return elements (paired data, citation URIs) and the behavior (sorted by primary metric). It also addresses potential user confusion about fiscal year handling and justifies why this tool is superior to sequential lookups, making it a complete description for a complex tool with two entity types.

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 type-specific semantics: type='company' pulls revenue/net income/cash/debt, while type='drug' pulls adverse-event counts, approvals, and trials. It also clarifies that values are tickers/CIKs for companies and drug names for drugs, enriching the already-present schema descriptions.

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

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

The description states a specific verb (compare, rank) and resource (companies/drugs) with clear scope (2–5 entities in one parallel call). It includes trigger phrases and explicitly distinguishes from sequential lookups, making it distinct 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?

Gives explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides example queries and type-specific usage (company vs drug), making it clear when to invoke 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?

Despite annotations already marking readOnly/openWorld/idempotent, the description adds substantial behavior: account and paid-tier requirements, gaps[] for unanswered facets, contradictions[] scan, semantic excerpting, expected latency, and a guarantee that citations are always resolvable. These details go far beyond the annotation hints and explain what the agent should expect from 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 dense and front-loaded with the critical account requirement, but it is a single long paragraph rather than structured sections. Every sentence earns its place, yet the wall-of-text format could be improved with bullets or breaks for easier parsing. Still, for a complex research tool the length is justified.

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 takes full responsibility for explaining return values: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers error-case behavior (empty gaps[]) and multi-hop logic. Combined with rich annotations, the description is complete for this 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?

The schema already thoroughly describes both parameters (100% coverage), but the description adds practical context not in the schema: the paid requirement for 'thorough', latency expectations per depth, and confirmation that broad/multi-part questions are acceptable. It doesn't radically expand on the schema but enriches the decision-relevant meaning of the depth parameter.

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 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and explicitly contrasts with 'open-web search,' giving a specific verb+resource+scope. It also differentiates from siblings by naming ask_pipeworx for single lookups and breaking news, making the tool's 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 when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also covers account-tier constraints and depth-level tradeoffs, so the agent knows exactly when to select 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it returns top-N results with names, descriptions, and full input schemas, and states that results are 'ready to call directly, no second schema lookup needed.' This gives the agent clear expectations for the output and immediate usability.

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

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

The description is four sentences, each earning its position: purpose, use cases, return format, and call-first guidance. The domain list is long but directly informs the agent of the tool's coverage. No fluff or repetition.

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

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

For a meta-tool with no output schema, the description is remarkably complete. It explains what the tool returns (names, descriptions, schemas with examples), that results are directly callable, and when to invoke it. This, combined with the annotations, leaves no critical gaps for an agent selecting this tool.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters and aliases. The description does not add additional parameter semantics beyond reinforcing that the query is a natural language description of the task. This matches the baseline of 3 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 'Find tools by describing the data or task,' which clearly states the tool's purpose as a meta-search over available tools. The list of supported domains (SEC filings, FDA drugs, etc.) distinguishes it from sibling tools like search_datasets or search_within, which operate on data rather than 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 explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available.' It also implies a when-not by saying 'not just one answer,' but it does not name specific alternative tools, so it falls short of a 5.

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

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description goes well beyond them by disclosing the parallel fan-out across sources, the exact return fields, the USPTO API sunset soft-fail, the GDELT→GNews fallback, and the input format (ticker/CIK). This provides substantial operational context 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 a single dense paragraph, but each segment conveys necessary information: example queries, alternative tool guidance, source list, return fields, and failure behavior. It is front-loaded with user-intent phrasing. However, it is slightly long and could benefit from bullet-style structuring, so it is not a perfect 5.

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

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

Despite having no output schema, the description fully enumerates the expected return structure: cik, company_name, recent_filings with URIs, fundamentals with specific metrics, patents, news, and LEI. It also covers edge cases like API sunset and fallback behavior, leaving the agent with a complete picture of what to expect.

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

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

Schema description coverage is 100%, so both parameters (type and value) are fully documented in the schema. The description reinforces the ticker/CIK format and the unsupported-name restriction, but does not add new semantic meaning beyond what the schema already provides. Baseline 3 is therefore 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 that the tool produces a 'full cross-source profile of a US public company in ONE parallel call', using specific verbs and resources. It distinguishes itself from sibling tools by indicating it should be preferred over chaining single-pack lookups and by clarifying that it does not handle names, which is explicitly delegated to resolve_entity.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing a direct when-to-use rule. It also gives a when-not-to-use condition (names not supported) and names the alternative tool (resolve_entity), making the decision boundary very 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 destructiveHint=true and idempotentHint=true, and the description consistently describes deletion. The description adds context about clearing 'sensitive data' and clarifies the scope ('previously stored memory'), going slightly beyond the annotations. However, it doesn't specify behavior for non-existent keys or return values, so a perfect score is not warranted.

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 short, purposeful sentences: action, usage scenarios, and sibling relationships. No redundant filler; every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential action and usage guidance. It could mention irreversibility or error handling, but the annotations already communicate the destructive and idempotent nature, making this adequately complete.

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

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

Schema description coverage is 100% ('Memory key to delete'), so the schema fully documents the only parameter. The description merely repeats 'by key' without adding new semantic details, meeting the baseline but not exceeding 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 clearly states the action: 'Delete a previously stored memory by key.' This is a specific verb (delete), resource (memory), and scope (by key). It distinguishes the tool from siblings like 'remember' and 'recall' by focusing on the deletion operation.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also directly references sibling tools: 'Pair with remember and recall,' giving clear context on when this tool fits within the memory workflow.

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 behavioral context: it fetches the page, extracts content, and emits a standard markdown blob. It does not contradict annotations and provides process details 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 four focused sentences: purpose, process, output, and use cases. Every sentence earns its place, no filler or repetition, and key information is front-loaded in the first sentence.

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

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

For a simple two-parameter tool with strong annotations, the description covers the essential contexts: what it does, how it behaves, output format, and when to use it. It lacks explicit mention of potential fetch failures or network dependencies, but given the schema and annotations, the description is largely complete.

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

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

Schema coverage is 100%, with both 'url' and 'max_links' already described in the input schema. The description mentions key links and the standard llms.txt format but adds no new meaning for either parameter beyond what the schema provides, so 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 ('Generate') and clearly identifies the resource ('a production-ready llms.txt file for any URL'). It explains the process (fetches page, extracts title/description/key links) and the output format, fully distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It clearly implies when to use this tool but does not explicitly describe when not to use it or 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 this as a safe, read-only, idempotent operation. The description adds context about what information will be returned and the scope (schema by URL), going beyond the annotations by specifying the output contents (fields, geometry type, count, capabilities). No contradictions with annotations are present.

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

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

The description is a single, well-structured sentence that front-loads the core action ('Get an ArcGIS Feature/Map Service layer's schema') and immediately lists the key output elements. Every word is informative, 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?

Given a single parameter and no output schema, the description sufficiently explains the return content by listing the four main pieces of information. It could mention potential edge cases (e.g., invalid URL) or explicitly note that it does not return features, but the current scope is adequate for a straightforward metadata 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 fully documents the 'url' parameter with a clear description and example. The tool description only says 'by url,' which adds no new semantic meaning beyond the schema. The baseline of 3 applies due to 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 ('Get') with a clear resource ('ArcGIS Feature/Map Service layer's schema') and enumerates the exact information returned (fields, geometry type, record count, capabilities). This clearly differentiates it from sibling tools like query_layer, which would focus on data retrieval rather than schema metadata.

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

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

The description implies when to use the tool (when you need schema information from a layer URL), but it does not explicitly mention alternatives or exclusions. It would benefit from a note like 'use query_layer for actual feature data,' but the implied usage is clear enough for a minimally viable 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 declare this as read-only, idempotent, and non-destructive. The description adds useful context by specifying the return fields, the caller-specific scope, and the default 'active' filter, going beyond what annotations provide. It does not mention potential pitfalls like pagination or ordering, but these are minor for a simple list.

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 verb and resource, and every sentence earns its place. It states purpose, return format, and usage context without any redundant or filler content.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete: it explains what it does, what fields it returns, and when to use it. The annotations handle safety, and the description provides all necessary behavioral details.

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

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

The schema covers the single parameter (include_inactive) with a clear description, so schema coverage is 100%. The description does not add additional meaning about the parameter beyond the schema, but it does align by emphasizing 'active subscriptions,' which the parameter modifies. 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes it from sibling tools like subscribe and unsubscribe. It also lists the exact fields returned, making the purpose unmistakable.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This implies usage relative to subscribe/unsubscribe, but it does not explicitly state when not to use it or name alternative tools, 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?

The annotations are all false (readOnly, openWorld, idempotent, destructive), but the description goes far beyond them. It discloses rate limits (5 per identifier per day), free usage, no quota impact, daily digest review, the return of a claim_token when no account is present, and how to use it later to check resolution status. This is rich behavioral context that annotations alone cannot convey, and it does not contradict any annotation.

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 earns its place. It is front-loaded with the core purpose, then moves to usage guidance, exclusions, claim_token mechanics, and expectations. There is no fluff or repetition; each sentence adds a new piece of essential operational information for an agent to use the tool correctly.

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 complex semantics: multiple feedback types, a claim_token round-trip, exclusions for other MCP servers, and rate limiting. The description covers all of these in enough detail for an agent to know exactly when, how, and why to call it. Even without an output schema, the description explains what the tool returns (claim_token, or status) and what happens with the feedback. It 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%, so the baseline is 3. The description adds significant value beyond the schema: it explains that claim_token must be used alone with no other arguments, details how to phrase the message (1-2 sentences, specific tool/error, max 2000 chars), and instructs users to describe issues in terms of Pipeworx tools/packs, not user prompts. This goes well beyond the schema's field labels.

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 and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling research/tool tools by framing it as feedback to the vendor, not a data operation. It also enumerates the exact use cases (bug, feature/data_gap, praise), making the purpose unambiguous.

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

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

Explicitly states when to use: on wrong/stale data, missing tools, or praise. It gives an explicit exclusion: tools from other MCP servers should not be reported here, telling the user to file with that server instead. It also explains the claim_token workflow for follow-up, leaving no doubt about how and when to invoke the 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 provide read-only, idempotent, and non-destructive hints. The description adds meaningful context: data is derived from CF analytics-engine, contains no PII, returns a specific shape (pack, tool, count), and is cached for 5min-1h. This goes beyond what annotations cover.

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: first states the core function, second lists use cases, third covers technical details (source, PII, caching). Each sentence adds value, no redundancy, well-structured for quick parsing.

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 and no output schema, this description is complete: it covers purpose, when to use, data source, privacy, output shape, and freshness. It gives an agent all essential context for selection and invocation.

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

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

The schema fully describes the single 'window' parameter with enum values and their semantics (short vs. long windows). The description restates the window options but does not add semantic meaning beyond the schema, so 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 clearly states a specific verb ('Returns') and resource ('top tools, top packs, and total call volume') aggregated from AI agent usage. It distinguishes itself from sibling tools like discover_tools by focusing on real-time agent call trends rather than general discovery.

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

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

Explicitly lists three concrete use cases: identifying hot data sources, confirming canonical tool choices, and aligning with agent needs. However, it does not mention alternative tools or state when not to use it, so it has clear context but lacks explicit exclusions.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing detailed behavioral traits: the partition filter with placeholder thresholds, the semantic anchor requiring ≥0.30 Jaccard similarity, the fill check that prices against live CLOB depth, and the condition that realizable_edge_pp ≤ 0 means the edge is not real. This is exceptionally transparent about how the tool behaves and when it returns null signals.

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

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

The description is long but densely packed with useful information. It is front-loaded with the core purpose, and uses internal capitals (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure details. However, it could be slightly more streamlined; some details like the exact threshold values are repeated in a way that feels slightly sprawling, but no sentence 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?

Given the tool's complexity (multiple modes, custom logic, output details), the description is remarkably complete. It explains return values (opportunities[], partition_check fields), the no-arg default behavior, and the use of sibling tools. The absence of an output schema is compensated by the description's detailed explanation of what the tool returns.

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

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

Although the schema already has 100% coverage with descriptions for event and topic, the description adds substantial meaning: concrete examples of event slugs and topic queries, the exact logic in each mode, and the role of each parameter in triggering different checks. It enriches the parameter semantics well beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource+mechanism: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It clearly distinguishes the two modes (event and topic) and the no-arg trending scan, making it easy to understand what the tool does and how it differs from similar 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 gives explicit guidance on when to use each mode: "Call with NO args for a trending_scan," "event (recommended for a specific market)," and "topic (for cross-event scanning)." It also references an alternative tool: "For custom sizing use polymarket_fill_risk." This is clear, actionable usage guidance with no ambiguity.

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, but the description adds substantial behavioral detail: caching at 1h, model family specifics, response diagnostics for empty segments, a 24h-move warning, and the rationale for excluding Fed candidates. These details go far beyond annotation basics and help the agent anticipate 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 a dense, single paragraph with extensive details on model families, thresholds, and response structure. While every sentence carries information, the lack of clear sectioning and the sheer length make it difficult to scan and parse quickly, which undermines conciseness and structure.

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

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

Given there is no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the fields carried by each opportunity, and the behavior of filter knobs. It also covers edge cases like empty segments and stale top-N, making it a complete guide for invoking and interpreting 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 descriptions cover 100% of parameters, so the baseline is 3. The description enriches this by explaining the interplay between knobs (e.g., min_partition_leg_kelly and why min_kelly does not apply to partition arbs) and framing parameters within the 'TRADEABLE-EDGE KNOBS' concept, adding value beyond the schema.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' clearly stating the tool's verb, resource, and purpose. The added 'Built for "what should I bet on today"' context further distinguishes it from generic search or data retrieval 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 explicitly frames the tool as a discovery mechanism for agents seeking betting opportunities without paging through hundreds of markets. It also explains when certain segments are excluded (e.g., Fed bets are surfaced but ranked out due to unreliable signals), giving practical invocation context. However, it does not explicitly mention alternative sibling tools or when not to use this tool.

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

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

Adds substantial behavioral detail beyond annotations: snapshots written on cache-miss, gaps meaning no scan that day, response semantics (tracked/expired/snapshot_dates), sign convention (negative = SELL YES), and history depth bounded by 60-day TTL. No contradiction with readOnly/idempotent 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?

Long but well-structured with distinct sections (Args, RESPONSE, LIMITS) and front-loaded with the core question. Every sentence adds value: business rationale, parameter explanation, response fields, and data caveats. No filler or repetition.

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

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

No output schema exists, so the description fully covers return structure: tracked[] with time-series and trend, expired[] with lifespan, and snapshot_dates[]. It also explains data availability caveats and provides interpretation guidance ('median lifespan is your competition clock').

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 defaults and clamps already documented. Description adds minor context (lookback meaning, 'snapshot family') and mentions max 30 for days, but largely restates schema information. The slight inconsistency between 'max 30' and schema 'clamp 2-30' prevents a higher score.

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 specific purpose: edge persistence and decay telemetry from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges by emphasizing temporal tracking rather than current edge retrieval.

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

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

Provides clear context for when to use the tool: comparing fresh vs. old wide edges as different trades, and explains snapshot write conditions and TTL limitations. It does not explicitly name alternatives, but the context strongly implies it complements polymarket_edges for persistence/decay questions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, but the description adds crucial context beyond that: it's an analysis/simulation that walks the order book ladder, returns verdicts and risk warnings, and warns about forced_directional_risk. This gives the agent a clear picture of side effects (none) and decision-relevant outputs (risk assessment).

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 functional weight—it defines modes, parameter defaults, return fields, and usage warnings. It is structured with clear uppercase labels for modes and returns, and the critical usage guidance is front-loaded in the first sentence. No fluff.

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

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

There is no output schema, so the description must explain return values; it does so exhaustively, listing all key fields (top_of_book, vwap_fill_price, slippage_pp, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers edge cases like partial fills and thin books, making the tool's behavior fully transparent.

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

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

Schema already covers all four parameters, but the description adds significant extra meaning: mode-specific interpretations (max spend vs target proceeds), basket notional as shares per leg, default values and clamps, and the distinction between single-market side vs basket side. This goes beyond the schema's descriptions and helps the agent invoke the tool correctly.

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 ('checks') and resource ('live CLOB order-book depth'), and clearly distinguishes the tool from siblings by its focus on fill risk and realizable-vs-theoretical capture. It names the exact modes (single-market vs basket) and the specific metrics returned.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming sibling tools and giving a clear threshold. It also explains why (theoretical overround not capturable on thin books, partial basket fills cause unhedged directional risk), which is exemplary 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 annotations already declare read-only, open-world, and idempotent behavior, but the description adds substantial behavioral context: the two modes, compatibility_warning firing conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped ≠ tradeable. This goes far beyond what annotations provide, 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?

The description is long but well-structured: it front-loads the purpose, clearly labels TWO MODES, and organizes fields in a readable way. There is some redundancy (bet-shape equivalence is explained twice) and the caveat sentence is wordy, but given the tool's complexity and lack of output schema, the length is mostly justified.

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 must explain return values and edge cases, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning with two specific cases, temporal_alignment, and skipped counters. It also covers both input modes and the practical caveat about pre-mapped topics, making it highly complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description deepens parameter understanding by explaining the topic shortcuts, the explicit pairing semantics, and how parameter choices affect matching and response fields. It adds mode-level meaning rather than merely restating 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, naming both venues and the resource being compared. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing specifically on Kalshi–Polymarket cross-venue spread and by describing the two input modes.

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

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

The description clearly explains when to use the topic mode versus explicit ticker/slug mode and warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. It does not explicitly contrast this tool with sibling alternatives or state when not to use it, so it stops 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns attribute rows and geometry, which is useful behavioral context beyond the annotations.

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

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

Two sentences convey the entire purpose without waste. The first sentence is dense and factual, the second is a helpful tip. No redundant words or 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?

Given the tool's moderate complexity (6 params, no output schema), the description covers the essential behavior, return type, and a recommended usage pattern. It also connects to search_datasets for context. Minor gaps like error handling or pagination behavior are not critical here.

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 goes beyond restating schema by explaining the SQL-like nature of `where`, the comma-separated format of `out_fields`, and by providing a practical sampling pattern. This adds value for correct parameter usage.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, which is a specific verb+resource. It distinguishes from siblings by referencing search_datasets as the source and focusing on data retrieval rather than metadata or discovery.

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

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

The description implies usage after search_datasets and provides a concrete sampling tip (where="1=1" + out_fields="*"). It lacks explicit exclusions or named alternatives, but the context is clear enough for an agent to understand 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?

While annotations already declare readOnlyHint and idempotentHint, the description adds useful behavior beyond those flags: it can list all keys when the key argument is omitted, and it is scoped to an identifier (anonymous IP, BYO key hash, or account ID). This context is not present in the annotations.

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

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

The description is three sentences long, each earning its place: the first defines the action, the second gives the use case, the third covers scoping and sibling tools. There is no waste or repetition.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description adequately covers purpose, usage, scoping, and relationships. It does not mention error handling (e.g., key not found), but that is not critical for a basic memory lookup tool with strong annotation support.

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 100% coverage of the single 'key' parameter, so the baseline is 3. The description improves this by giving concrete examples of what keys represent (user's target ticker, address, research notes) and clarifying that omitting the key lists all saved keys, adding semantic value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by referencing what remember does and naming forget as the delete counterpart.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also directs alternative usage with 'Pair with remember to save, forget to delete,' providing clear use-case boundaries 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 meaningfully supplements annotations by detailing return fields (source, citation_uri, raw payload), the side effect of mark_read ('so the next call only shows newer ones'), and an alternative access method. This goes beyond the readOnlyHint and idempotentHint annotations without contradicting them.

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

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

The description is three focused sentences, each earning its place: first states purpose, second details return payload, third covers filtering, mark_read, and alternative endpoint. 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?

Despite having no output schema, the description explains the return shape (source, citation_uri, payload) and covers polling behavior, filtering, and state changes. Together with rich annotations and 100% parameter schema coverage, this is complete 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?

While schema coverage is 100%, the description adds valuable semantics: a concrete type example ('sec_8k'), clarifies 'since' as ISO timestamp, and explains the downstream effect of mark_read. This extra context helps the AI agent use parameters correctly beyond the schema definitions.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It identifies the specific resource (subscription feed alerts) and distinguishes from siblings like list_subscriptions or recent_changes by focusing on fired events with payload 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?

It gives practical usage context: filtering by type and since, mark_read behavior, and explicitly notes 'Polls work fine' while providing an alternative REST endpoint for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools or specify when not to use it.

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

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

Beyond the read-only/idempotent annotations, the description discloses fallback behavior (GDELT→GNews on rate-limit/5xx), soft-failure for USPTO due to PatentsView API sunset, parallel fan-out across sources, and the structured return format. This is rich, non-obvious behavioral 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 detailed yet every sentence adds value: examples, sources, fallbacks, date syntax, return shape, and an alternative tool. It is well-structured, front-loaded with core purpose, and not verbose 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?

For a multi-source aggregator with fallback logic, the description covers sources, fallback behavior, date parsing, return structure, and the boundary with entity_profile. Combined with annotations, there are no critical gaps for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% and the schema already documents all parameters with examples and guidance (e.g., 'Use 30d or 1m for typical monitoring'). The description adds no significant parameter-level semantics beyond the schema, so the baseline score 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 clearly states the tool is a change feed for a company over a time window, enumerating specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with entity_profile. This distinguishes it from sibling tools and gives a specific verb+resource+scope.

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 natural-language user intents ('What's new with X', 'updates on Acme') and explicitly names an alternative tool: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context about persistence (authenticated users vs. 24-hour anonymous retention) and scoping (by identifier), which goes beyond the raw annotation 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?

Three sentences, front-loaded with purpose, then usage context, then persistence details. No wasted words; every sentence adds distinct 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?

For a simple 2-parameter tool with no output schema, the description is complete. It covers when to use, how it behaves, and how it relates to sibling tools, leaving no obvious gaps.

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

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

Schema description coverage is 100% with examples for both key and value. The description reinforces the key-value concept but doesn't add significant semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Save data') and the resource ('data the agent will need to reuse later'), with concrete examples of what to save. It also distinguishes from siblings by mentioning 'recall' and 'forget' as companion tools for retrieval and deletion.

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

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

Explicitly says 'Use when you discover something worth carrying forward... so you don't have to look it up again' and names alternatives via 'Pair with recall to retrieve later, forget to delete.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it cascades through several internal endpoints, auto-disambiguates company inputs, and discloses return payloads (ticker, CIK, RxCUI, citation URIs). This goes beyond what annotations provide.

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

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

The description is information-dense but well-structured, starting with query examples and then enumerating supported types with their return details. It is slightly long due to the inline examples, but every sentence contributes meaningful information. No filler 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?

Despite no output schema, the description fully specifies what each entity type returns (company: ticker, CIK, company_name; drug: RxCUI, ingredient, brand), includes citation URIs, and notes internal cascading behavior. This covers the key behavioral aspects an agent needs, making the tool complete for selection and invocation.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds significant meaning beyond the schema: it provides concrete value formats (e.g., 'AAPL', '0000320193'), clarifies accepted synonyms (brand vs generic), and gives examples for both types. This greatly enhances the agent's ability to fill parameters correctly.

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 ('resolve') and resource (names to official identifiers), with explicit examples of user queries and supported types (company, drug). It clearly distinguishes from sibling tools like entity_profile by focusing on ID lookup rather than profile data.

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

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

Contains an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This clearly states when to use it. It also mentions it replaces 2-3 manual lookups, giving context. However, it does not explicitly state when NOT to use it or name alternatives, 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 declare read-only, idempotent, non-destructive. The description adds valuable context: it internally calls another tool (ai_visibility_check) per entity, ranks results, and returns a structured list. It also notes that using 'anthropic' requires an API key passed per probe. No contradictions.

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

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

Three concise sentences that front-load the core function, then explain the mechanism and use case. Every sentence earns its place; no filler or 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 specifies the return format (ranked list with score, confidence, signal density) and the overall purpose. Combined with full schema coverage and robust annotations, it provides complete context 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% and each parameter has a description. The description reinforces the meaning of entities as 'your brand + N competitors' and the first-entry-as-subject rule, but this is already present in the schema. Minimal additional semantic enrichment beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. This specific verb+resource+scope distinguishes it from siblings like ai_visibility_check or compare_entities.

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

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

Explicitly frames the tool for competitive AI-marketing audits with a concrete example question. It implies multi-entity comparison as the use case, and by referencing ai_visibility_check as the per-entity probe, suggests that tool is for single-entity checks. This provides clear when/when-not guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's additional disclosure of latency (bundlephobia's first measurement can take 5-30s), graceful degradation, and the sources_failed field adds meaningful context beyond the annotations. No contradiction exists.

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 five sentences, each adding essential information: purpose, data sources, when to use, return fields, ecosystem scope, and failure behavior. It is not wasteful, though it is dense; the front-loaded purpose and logical ordering earn it a 4.

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 explains the return structure (summary block field names, per-advisory detail, links, alternative versions). It also covers ecosystem boundaries, latency, and partial failure behavior, making the tool's behavior predictable and complete.

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

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

The schema description coverage is 100%, so the schema already documents both parameters. The description mentions version defaults to latest when omitted, which echoes the schema's default note but adds no new semantic detail, so a 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 identifies the tool as a composite npm package evaluation check that fans out to deps.dev and bundlephobia. It explicitly states the resource and the question it answers ('should I add this npm package'), and differentiates it from siblings which are unrelated tools like validate_claim or polymarket_edges.

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

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

The description gives explicit use cases ('whenever an agent asks "is X safe / popular / small"') and an explicit exclusion with an alternative ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This tells the agent when to use this tool and when not to.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing exactly what the tool returns (name, summary, record_count, owner/org, Feature Service url) and how to use the result, which goes beyond the structured annotations. No contradiction exists.

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, followed by return details and a clear next-step instruction. Every sentence earns its place; no filler 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?

Given the rich schema and annotations, the description is complete for a search tool. It covers purpose, return fields, and downstream usage (passing the URL to query_layer/layer_info), and no output schema exists to explain. There are no significant gaps.

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

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

Schema description coverage is 100%, so the input schema fully documents all three parameters. The description adds no additional parameter-level meaning beyond the schema, as it doesn't elaborate on `query`, `limit`, or `org_id` specifics. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Search'), a clear resource ('City of McKinney GIS open geospatial datasets'), and a scope ('by keyword'). It distinguishes itself from sibling tools by explicitly mentioning that the returned Feature Service `url` is meant to be passed to query_layer / layer_info, positioning search_datasets as the discovery step.

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 clearly indicates when to use the tool (to find datasets by keyword) and provides a follow-up workflow ('pass that url to query_layer / layer_info'). However, it does not explicitly state when not to use it or name alternative discovery tools, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the embedding model (BGE-base-en), the windowing strategy (500-char overlapping windows), the 200K char cap, and truncation behavior (truncated and flagged). It also clarifies the return payload (passages with character offsets and similarity scores), giving agents a full behavioral picture.

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

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

The description is a single paragraph but tightly packed with actionable information: purpose, use case, output, technical details, and pairing. No word is wasted, and the key action is front-loaded. The technical caveats are placed at the end, preserving readability.

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

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

For a tool with no output schema, the description adequately explains what is returned (passages with offsets and similarity scores), the limits (200K chars), and the use case (context saving). Given the complex behavior (embeddings, windows, truncation), this description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage for the 3 params is 100%, but the description adds real value by explaining the 'text' parameter as 'already pulled' content with concrete examples (SEC 10-K body, article), and by giving example queries for the 'query' parameter. This enriches the schema's terse field descriptions.

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

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

The description clearly states the verb ('Semantic search') and the specific resource ('INSIDE a fetched record'), and distinguishes itself from siblings by emphasizing it works on already-fetched text, not external data. It even names a complementary tool (ask_pipeworx_grounded), making its unique role explicit.

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

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

Provides explicit when-to-use guidance ('Use when the record is too big to cram into the prompt') and explains the benefit (saves context, returns only relevant passages). It also names an alternative workflow (fetch with gateway, ground over relevant passages), giving clear usage boundaries.

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

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

Annotations alone (readOnlyHint false, idempotentHint true) provide minimal safety context, but the description goes far beyond: it discloses the side effect of creating a subscription, the requirement for a verified phone, the 10/day SMS cap, and auto-disabling of webhooks after failures. This adds substantial behavioral nuance beyond structured 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 well-organized, front-loading the core purpose and then systematically covering types, delivery channels, and requirements. Every sentence conveys necessary details, and the use of colons and examples makes it scannable despite 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?

Given the tool's complexity (multiple subscription types, nested params, delivery options, webhook signing) and the absence of an output schema, the description is remarkably complete. It covers prerequisites, return value, optional channels, and caveats like phone verification and webhook auto-disable, leaving no major gaps for an agent to invoke it correctly.

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

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

Although the input schema covers 100% of parameters, the description enriches the semantics with concrete examples for each type (e.g., sec_8k items like '5.02' for officer changes), delivery channel formats, and webhook verification details. It clarifies how the params and delivery objects should be structured, adding meaning beyond the raw schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' a specific verb+resource pair that clearly states the action. It also lists supported subscription types and returns the new subscription id, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool, including prerequisites (Pipeworx OAuth account), supported types, and delivery channels. It does not explicitly mention alternatives like 'use list_subscriptions to view existing subscriptions,' but it offers sufficient context for an agent to decide, leaving out exclusions only.

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 hints. The description adds meaningful behavioral detail: it fully describes the output structure (category-bucketed example questions with exact tool+argument shape) and explains how behavior changes when called with no arguments vs passing a topic. This goes beyond the safety 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 moderately long but front-loaded with purpose and includes a useful list of example user phrases. Every sentence contributes to understanding the tool's role and behavior, with no redundancy. It is dense but justifiably so for an onboarding meta-tool.

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

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

Given there is no output schema, the description sufficiently explains what the tool returns (category-bucketed examples with tool+argument shapes) and the optional topic behavior. It is complete for its intended onboarding/discovery function, though it could mention how results are delivered or any limits.

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 covers the single `topic` parameter with a description and allowed values, so coverage is 100%. The description adds context: omitting it returns a cross-category spread, and provides concrete example values like 'finance', 'pharma', 'betting'. This adds nuance beyond the schema 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 identifies the tool as 'the onboarding entry point' for discovering what to ask Pipeworx, with a specific verb ('returns category-bucketed example questions') and resource. It distinguishes itself from siblings by explicitly positioning it as the first stop and referencing meta-tools like ask_pipeworx and 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?

It gives an explicit when-to-use directive: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also mentions an alternative purpose (learning to call meta-tools), but does not explicitly state when not to use it. The strong directive and context make the guidance 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?

The description goes beyond annotations by revealing the soft-delete behavior: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' It also discloses ownership enforcement, which is critical safety-relevant behavior. This adds significant context not present in the readOnlyHint or destructiveHint 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 short sentences, each earning its place. It front-loads the action, immediately states the ownership constraint, and explains the persistence behavior. There is no redundant or filler content.

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

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

For a simple one-parameter operation, the description covers the action, the ownership restriction, and the post-effect on history. The lack of an output schema is not a gap here because the operation is straightforward and the outcome is implied. The context signals (annotations, parameter count) are adequately complemented.

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 provides 100% coverage for the single parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description only repeats 'by id' without adding new semantics. Since schema coverage is complete, a baseline of 3 is appropriate.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb+resource statement. It clearly distinguishes this from sibling tools like subscribe (opposite action) and list_subscriptions (listing), making the purpose unambiguous.

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

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

The description provides context by stating 'Ownership is enforced — you can only cancel your own subscriptions,' which clarifies a usage constraint. It also explains the consequence of deactivation (not deletion) via recent_alerts, giving guidance on the effect. However, it does not explicitly list alternatives or when-not-to-use conditions, so it's one point below the top.

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 non-destructive; the description adds the dual-routing behavior (structured EDGAR vs grounded pipeline), the percent-delta tolerance logic, and the specific verdict vocabulary returned. This enriches the agent's understanding without contradicting annotations.

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

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

The description is long but information-dense, using concrete query examples and a structured explanation of routing and output. It could be tightened, but every sentence contributes meaningful guidance.

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

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

Given there's no output schema, the description fully covers the return format (verdict enum, citation, reasoning), the two execution paths, and the tolerance parameter's behavior. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema covers both parameters with descriptions, but the description adds practical guidance for `tolerance_pct` (override for hallucination detection) and gives claim examples. This helps the agent set parameter values appropriately.

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 concrete natural-language triggers and clearly states the tool's function: fact-checking a claim against authoritative sources. It differentiates from siblings by mentioning the EDGAR fast path and grounded pipeline, and notes it replaces multiple sequential calls, making its scope 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also distinguishes between company-financial claims and other claims, routing each appropriately, but doesn't name sibling alternatives or state when not to use it, so not a 5.

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