Arcgis Lakecountyil

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond that: the default model is free (Workers AI Llama-3.3-70b), passing _apiKey incurs direct Anthropic costs, and the per-model response structure is outlined. No contradictions found.

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

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

Two dense sentences carry all necessary information with no fluff. The first sentence front-loads the core function and output, the second adds use cases and cost caveats. Every phrase 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 tool with 4 parameters and no output schema, the description covers all essentials: default model options, key handling, return format, and typical use cases. It gives an agent enough to invoke the tool correctly and interpret results. 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% (all 4 params documented), so baseline is 3. The description adds extra semantic value by clarifying the default model, explaining that _apiKey is a BYO key with direct payment implications, and that context helps disambiguate. These details go 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 clearly states the tool's function: probing LLMs for knowledge and scoring visibility (0-100). The verb 'probe' and resource 'LLMs' are specific, and the output format is defined. However, it does not explicitly distinguish itself from the sibling tool 'scan_competitor_ai_presence', which could serve a similar purpose, so it misses the full mark for sibling differentiation.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives context for when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context: routes across thousands of tools, fills arguments, returns stable pipeworx:// citations, and is a 'one fast call' default. No contradiction with annotations.

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

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

The description is dense but well-structured: starts with the key preference warning, lists domains, explains behavior, gives triggers/examples, then escalations. Every sentence adds either selection or invocation guidance, with no filler.

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

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

For a default entry point that must cover a huge scope, the description fully explains what it does, when to use it, examples of questions, how it differs from related tools, and what the return format includes (structured answer with citation URIs). The absence of an output schema is compensated by mentioning citations.

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

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

The input schema has 100% coverage: all parameters are aliases for 'question' and are fully documented. The description adds examples and internal behavior ('fills arguments') but no extra parameter syntax or format. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: routes questions to the right one of 5,462 tools across 1,419 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part fan-out).

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 'PREFER OVER WEB SEARCH' and enumerates many use-case domains. Provides query triggers ('what is', 'look up', 'get the latest') and concrete examples. Then gives escalation paths: use ask_pipeworx_grounded for grounded single answers, deep_research for broad 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?

The description adds valuable behavioral context beyond the annotations: it states no candidate is currently active, so it matches ask_pipeworx exactly, and it emphasizes it is a full working router ('falls back to nothing'). This complements the readOnlyHint/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 concise (4 sentences) and front-loaded with the key fact that this is a beta version. Each sentence adds essential information: identity, current state, usage, and reassurance that it is fully functional. No wasted words.

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

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

Given the absence of an output schema, the description provides sufficient context by noting 'same response shape' as ask_pipeworx. It covers the beta nature, current status, and usage, making the tool well-understood 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 input schema already describes all 6 parameters as aliases for 'question' with 100% coverage, so the description adds no extra parameter meaning. Per the rubric, a baseline of 3 is appropriate when schema coverage is high.

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

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

The description clearly states it is the 'Beta version of ask_pipeworx' and defines it as a 'universal router' with the same tools and behavior as its sibling, distinguishing it as the experimental edge. This makes its purpose specific and distinct from the other sibling tools.

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

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

It explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared to the stable router. This gives clear usage context, though it does not mention when not to use it or name alternatives like ask_pipeworx_grounded.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description goes beyond by detailing the exact return structure (answer, evidence, confidence, source, fetched_at) and explicit refusal reasons, including 'not_in_source' and 'no_tool_match.' This provides rich behavioral context without contradicting annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence earns its place: purpose, routing mechanism, return format, usage guidance, and cost comparison. No filler or redundant text.

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 completely explains the return payload, refusal behavior, and the extra LLM call cost. It gives all necessary context for an agent to decide when to use this tool and what to expect, making it contextually complete.

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

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

The input schema covers all 6 parameters with 100% coverage, explaining that all are aliases for 'question.' The description adds no additional parameter semantics, but the schema fully documents the only meaningful parameter, so the 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?

Clearly identifies itself as a 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but extracts answers strictly from tool results. This distinguishes it from the sibling ask_pipeworx and other query 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' Also notes the extra LLM call cost, giving a clear cost-benefit tradeoff for selection.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses extensive behavioral details: parallel fan-out, the resolver contract with statuses like low_confidence_match, closed/inactive market handling, wide-spread illiquidity flags, cancellation-rule parsing, and GDELT fallback behavior. It even warns about EV-material cancellation losses. No contradiction with annotations.

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

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

The description is extremely long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and the core purpose is front-loaded. Most sentences add unique behavioral details, though some sections (e.g., the extensive fan-out list) could be trimmed without losing essential guidance. It earns a high score for organization and density of useful 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?

With no output schema, the description carries the full burden of explaining return shapes and edge cases. It thoroughly covers result.market, result.analysis, result.evidence, resolver match confidence, parent-event partitioning, news fallback fields, and resolution-rule risk. It also documents blocking conditions like low_confidence_match and market_closed_or_inactive with explicit guidance. This is comprehensive 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?

The input schema covers all three parameters with 100% description coverage, giving a baseline of 3. The description adds value by enumerating classifiers and providing fan-out examples (e.g., BTC bet → coingecko + fred + gdelt+gnews), which clarifies how the market parameter is interpreted. It also confirms accepted input forms (slug, URL, question text), though these are already in the schema.

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

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

The opening sentence states a specific verb and resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes this from sibling Polymarket tools like polymarket_edges or polymarket_arbitrage by focusing on evidence-gathering for a single bet. The description also includes concrete usage examples, 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: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also gives fan-out examples for different bet types, clarifying when it applies. However, it does not explicitly contrast with sibling tools or state when not to use it, so it stops short of full exclusion 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output format with pipeworx:// citation URIs. This goes well beyond annotations and enriches understanding of tool 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 dense but every sentence provides unique value. It front-loads common query phrasing, then states core function, then provides type-specific details, output behavior, and benefits. No fluff, well-structured, and appropriately sized for a tool with two entity types.

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

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

Given no output schema, the description adequately explains what the tool returns: paired data, sorted by primary metric, with citation URIs. It covers scope, data sources, edge cases (off-calendar fiscal years), and performance (replaces 8-15 lookups). Completely sufficient for an agent to select and invoke correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning to parameters. It explains what 'type' specifies in terms of data pulled (10-K financials for company, adverse events/approvals/trials for drug), and what 'values' accepts (tickers/CIKs vs names). It also notes max of 5 and min of 2 implicitly. This goes beyond schema descriptions.

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

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

Clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. The description is specific with verb 'compare' and resource 'entities', and it distinguishes itself from sequential single-pack 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also gives trigger phrases and example queries, and differentiates between company and drug types, which informs the user on appropriate invocation.

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

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

The description discloses far more than the annotations: account/payment requirements, latency (15-60s, up to ~90s), the 'never invented' gap behavior, second-hop iteration, contradictions[] scan, semantic excerpting, and the resolvable citation_uri guarantee. Annotations already convey read-only/idempotent/open-world, and the description adds substantial operational context 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 dense and front-loaded, starting with the account requirement and key alternatives. While lengthy, nearly every sentence earns its place by explaining output format, gaps, latency, and depth behavior. Some redundancy exists with depth details already present in the schema, but it remains organized and purposeful.

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

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

The description is highly complete for a complex tool with no output schema: it covers prerequisites, use cases, limitations, output structure (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap semantics, contradictions, depth variants, and timing. The lack of an output schema is fully compensated by describing the returned packet in detail.

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 baseline is 3. The description adds meaningful context for the question parameter ('Broad/multi-part is fine — decomposition is the point') and clarifies depth's paid boundary, but most depth details are already in the schema's enum description.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, with parallel decomposition across 5,462 tools. It clearly distinguishes itself from siblings like ask_pipeworx by saying 'this is NOT open-web search' and by specifying its scope ('best for broad/multi-part questions').

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 when-to-use and when-not-to-use guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also covers prerequisites and fallback: 'ACCOUNT REQUIRED ... If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies the output format and direct callability, going beyond the safety 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: purpose, usage context, and return behavior. It is front-loaded and every sentence adds value. The domain list is long but relevant, providing concrete examples without fluff.

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

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

With no output schema, the description fully explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' Combined with strong annotations and full schema coverage, it gives 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%: all parameters (query, limit, and aliases q, task, search, description) have descriptive schema text. The description's 'top-N' maps to the limit parameter and 'describing the data or task' maps to query, but it does not add new semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It enumerates supported domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes itself from sibling tools by positioning it as a meta-discovery tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It also implies a when-not via 'not just one answer' (i.e., use a specific tool for a single answer), but it does not name alternative tools explicitly.

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

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

Annotations already mark it as read-only and idempotent, but the description adds richer behavioral details: it fans out across multiple sources, performs parallel calls, describes the patents API sunset and soft-fail behavior, and documents fallback logic like GDELT→GNews. No contradictions with annotations.

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

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

The description is long but every sentence carries useful information: example queries, output fields, source list, limitations, and fallback behavior. It is densely packed with 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?

Given the absence of an output schema, the description thoroughly documents what will be returned (CIK, recent filings with URIs, fundamentals, patents, news, LEI). It covers edge cases like API sunset and name resolution, making it sufficiently complete for correct invocation.

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

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

Schema coverage is 100% and both parameters are fully documented there. The description's parameter guidance mostly repeats the schema (ticker 'AAPL' or zero-padded CIK, names not supported), adding little beyond concrete examples already present in the schema.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' and lists concrete example queries. It differentiates itself from single-purpose lookups and sibling tools by emphasizing the holistic, one-call nature.

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

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

Explicit guidance says to ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups for holistic views, and it directs name-only queries to resolve_entity first. This gives clear when-to-use and when-not-to-use direction.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds context beyond that: why you would forget (stale, done, sensitive data) and the pairing with remember/recall. It does not cover failure behaviors (e.g., missing key), but the annotation already covers the main safety profile.

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 short sentences deliver the core action, usage guidance, and relationship to related tools. No filler or redundancy, and the action verb appears 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 single-parameter delete tool, the description covers the action, when to use it, and how it relates to sibling tools. Annotations disclose destructive/idempotent nature, and the schema documents the parameter, leaving no critical 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?

The schema describes the single parameter 'key' as 'Memory key to delete' with 100% coverage. The description adds minimal extra semantics ('previously stored', 'by key'), so it stays at the baseline 3 without enriching the parameter meaning further.

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 'Delete' and identifies the resource as 'a previously stored memory by key', making the action unambiguous. It also distinguishes itself from sibling tools by explicitly naming 'remember and recall' as related tools.

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

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

The description provides explicit when-to-use conditions ('Use when context is stale, the task is done, or you want to clear sensitive data') and references alternatives by mentioning 'Pair with remember and recall'. This gives clear guidance on when this tool is appropriate.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable process context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', and states the output is 'a single text blob ready to drop at site-root/llms.txt'. This exceeds the baseline set by 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 compact yet information-dense: it states the purpose, explains the process, defines the output location, and lists use cases—all in four sentences. No filler words; 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 read-only tool with two parameters and no output schema, the description fully covers what it does, how it behaves, and what the result looks like. The annotations handle safety semantics, and the use cases round out the context. No critical gaps remain.

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

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

The schema provides 100% coverage for both parameters ('url' and 'max_links') with clear descriptions. The tool description does not add meaningful parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL', specifying the exact verb, resource, and scope. It clearly distinguishes this from sibling tools like 'scan_competitor_ai_presence' by focusing on producing the standard llms.txt format rather than just visibility analysis.

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

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

The 'Useful for' list provides clear contexts such as 'getting a client's site indexed by AI' and 'auditing how an AI crawler would see a competitor'. It does not explicitly name alternative tools or when not to use it, but the scenarios are specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context about the return payload (schema fields, geometry type, record count, capabilities) without contradicting annotations. It lacks details on network dependencies or failure modes, but annotations lower the burden.

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, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose and output format, earning a top score for conciseness.

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

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

With one simple parameter, no output schema, and strong annotations, the description is largely complete. It details the return items, which is essential since no output schema exists. Minor gaps include not explaining what 'capabilities' encompasses or error behavior, but for a simple getter tool this is acceptable.

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% (url parameter has a clear description). The description repeats 'by url' but adds no new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate when schema fully covers the 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 clearly states the tool's function with a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and lists the exact returned items (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like query_layer, which is likely for data 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?

The description implies usage when schema information is needed, but does not explicitly state when to use this tool over alternatives or provide exclusions. For example, it does not mention that query_layer should be used for actual data queries, so guidance is only implied.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns specific fields (id, type, params, etc.) and filters to active subscriptions by default, which is useful beyond annotations. 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 two sentences, front-loaded with the key action, then lists return fields and usage context. No wasted words 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 read-only list tool with no output schema, the description fully covers purpose, return fields, and usage scenarios. It is complete and self-contained for the caller's needs.

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 only parameter include_inactive has a clear schema description. The tool description mentions 'active subscriptions' but doesn't add new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on listing rather than creating or removing.

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.' However, it doesn't explicitly name alternatives or state when not to use, though the context implies before subscribe/unsubscribe.

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

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

Annotations provide no useful signals (all false), so the description carries the full burden. It discloses the claim_token workflow, rate limit ('Rate-limited to 5 per identifier per day'), quota exemption, and readership ('team reads digests daily and signal directly affects roadmap'). This goes well beyond the 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 long but dense with useful guidance—purpose, usage, exclusions, token flow, rate limit, and quota note. It is front-loaded with the core purpose and every sentence contributes a distinct operational detail. 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?

For a tool with 4 parameters, nested objects, no output schema, and no helpful annotations, the description fully compensates. It explains how to file, what to include/avoid, how to check status later, and what to expect (daily digest). This is enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by showing how claim_token is used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), warning not to paste the end-user's prompt, and clarifying context fields should reference Pipeworx tools/packs. This elevates it above the schema-only 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 states a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and enumerates exact feedback categories (bug, feature, data_gap, praise). It also distinguishes this tool from sibling tools by explicitly limiting it to 'tools served by this Pipeworx connection' and contrasting it with other MCP servers.

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?

Usage is explicitly tied to concrete scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It even provides an exclusion rule for tools from different MCP servers and tells the agent to file those elsewhere, which is exactly the when-not-to-use guidance needed.

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 readOnlyHint/idempotentHint annotations, the description discloses the data source (CF analytics-engine), confirms no PII, specifies the return structure (pack, tool, count), and reveals caching (5min-1h). This gives a complete 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 front-loaded with the core purpose, followed by a succinct numbered list of use cases. Every sentence carries substantive information without fluff; the length is justified by the rich context.

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 only one optional parameter fully covered by the schema, comprehensive annotations, and a description that covers return values, caching, and use cases, the tool is fully specified for an agent to invoke correctly. No output schema is needed given the simple return structure.

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 documents the 'window' parameter with an enum and interpretation of shorter vs. longer windows. The description merely lists the values (24h, 7d, 30d) in passing and adds no new semantic meaning beyond the schema, so it stays at the baseline for high schema coverage.

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

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

The description clearly states the verb ('Returns') and the resource (top tools, top packs, total call volume over a recent window). The opening 'What other AI agents are calling...' differentiates it from sibling tools like discover_tools by focusing on aggregated usage trends rather than 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?

It explicitly lists three practical use cases (hot data sources, confirming canonical tools, checking alignment), providing clear context for when to use. However, it does not mention when-not-to-use or explicitly contrast with sibling alternatives, falling 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?

Even with annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral context: threshold details (>3pp), placeholder filters (>20%), Jaccard similarity (≥0.30), and the fill check explanation with realizable_edge_pp ≤ 0 meaning 'do not trade it.' It also describes exactly what the response contains. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. It contains many specific numbers and examples, all relevant. It could be slightly tightened, but no sentence feels 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?

For a complex tool with two modes and many behavioral details, the description is remarkably complete. It explains input modes, underlying checks, filters, response structure, and even the interpretation of the fill_check output. The absence of an output schema is compensated by the detailed response description.

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 both parameters (event and topic) with descriptions, but the tool description goes far beyond: it explains exactly when to use each, gives concrete examples ('fed-decision-may-2026'), and describes the behavioral differences (single-event vs cross-event). This adds deep meaning beyond the schema 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools by explaining its unique approach and modes. The distinction between event, topic, and no-arg trending_scan further clarifies its 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 gives explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also names an alternative tool for related use: 'For custom sizing use polymarket_fill_risk.' This effectively tells the agent when to use this tool versus alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses rich behavioral traits: response segmentation (by_segment), diagnostic funnel counters, caching ('Cached 1h at the KV level'), the 24h-move warning for edges already priced in, and the rare-by-design nature of concentrated_longshot. It also explains why Fed signals are unreliable at meeting-month horizons.

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

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

The description is long but well-structured, with semantic labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and a front-loaded first sentence that states the core purpose. Every paragraph earns its place, though the density could overwhelm some agents; a bit more whitespace would improve scannability.

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

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

Given the tool's complexity (9 params, no output schema), the description is remarkably complete. It details response top-level structure, nested diagnostic fields, knob effects, caching behavior, placeholder-slug filters, and segment-specific edge cases. An agent has all necessary information to invoke the tool correctly and interpret results.

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

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

Even with 100% schema description coverage, the description adds significant meaning: it explains why min_partition_leg_kelly exists (parent-level kelly_fraction_half is 0 by design), gives context for slippage_pp (zero trading fees but 20–50bp typical slippage), and clarifies that min_kelly uses half-Kelly. This enriches the schema and helps agents choose sensible values.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings like polymarket_arbitrage by focusing on comprehensive discovery across three model families and explicitly states the use case ('what should I bet on today').

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 ('without paging hundreds of markets') and gives concrete knob recommendations ('Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It also flags exclusions (e.g., Fed bets 'excluded from ranking') but does not explicitly name alternative sibling tools, leaving some comparison to the agent.

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 non-destructive, but description adds rich behavioral detail: response structure (tracked[], expired[], snapshot_dates[]), how snapshots are written (on cache-miss, meaning gaps are informative), 60-day TTL bound, and that decay numbers are based on daily closes not intraday. No contradiction with annotations.

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

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

Well-structured with explicit Args, RESPONSE, and LIMITS sections. Front-loaded with a clear purpose and the key question. Though lengthy, every sentence contributes operational detail and there is no filler.

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

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

No output schema exists, so the description fully specifies the return shape: tracked[] with all fields, expired[] with lifespan_days, and snapshot_dates[]. It also covers limitations (TTL, daily closes, gap meaning), making it complete for correct invocation and interpretation.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. Description adds a little: days is 'lookback, default 14, max 30' and window is 'snapshot family', reinforcing defaults and clarifying the 'window' concept. It also explains edge_pp_net sign convention in the response, which helps interpret parameter effects indirectly.

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?

Clear verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly states the question it answers ('how long has this edge existed and is it shrinking?') and differentiates from siblings like polymarket_edges by focusing on historical persistence/decay.

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 implies when to use it: when you need to distinguish fresh versus stale wide edges. It references the parent data source (polymarket_edges) and explains the response including expired opportunities, giving context for choosing this tool over a current-edges view. Does not explicitly name alternatives, but provides sufficient 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds rich behavioral context: mode-specific behavior (single vs basket), parameter interpretation (size_usd as spend vs notional), return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and risk disclosure (partial basket fills convert an arb into an unhedged directional position). No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and then systematically covers mode details, return values, and usage warnings. It is dense and long, but every clause carries either mode-specific or risk-relevant information. The length is justified by the tool's complexity, yet it could be better organized (e.g., bullet lists) for 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?

Given no output schema, the description provides a thorough enumeration of return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers parameter semantics, defaults, and use-case context, making it contextually complete for a complex dual-mode tool.

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

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

Although schema coverage is 100%, the description goes well beyond schema descriptions. It explains the dual meaning of size_usd ('max spend on buys, target proceeds on sells' vs 'settlement notional S'), default values, clamping (10–1,000,000), and side auto-selection logic in basket mode. This adds material semantic value for correct usage.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order-book depth validation, not just edge 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 explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable) and names the exact alternative tools, satisfying the when/when-not criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond this by disclosing edge cases: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and the statement that 'Real cross-venue spreads are rarer than the macro-shortcut list suggests.' This is rich, honest behavioral disclosure that helps the agent set expectations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and bolded field names. Every sentence adds value, though some points are reiterated (e.g., the 'pre-mapped ≠ tradeable' warning echoes the compatibility_warning explanation). It is appropriately sized for the tool's complexity, but not perfectly lean.

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

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

With no output schema, the description carries the full burden of explaining return values and semantics. It does so comprehensively: leg-by-leg prices, top_spreads_pp formula (Kalshi − Polymarket), safety fields with two distinct warning cases, temporal_alignment, and skip counters. The description fully equips an agent to interpret results correctly despite lacking an output schema.

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

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

Schema coverage is 100% for all three parameters, providing a baseline of 3. The description adds further meaning by explaining mode selection: topic uses pre-mapped shortcuts while kalshi_event_ticker and polymarket_event_slug override the mapped sides, and it gives concrete examples of ticker formats. This interaction semantics goes beyond the schema's individual parameter 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' a specific verb+resource statement that clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges. It further details two modes and the exact output, leaving no ambiguity about what the tool does.

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—comparing equivalent bet shapes across venues—and explicitly states when results should not be relied on: 'aligned:false means spreads are mathematically meaningless' and 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It lacks explicit alternative tool names, but the when/when-not guidance is substantial.

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 that it returns attribute rows and geometry, and suggests a sampling pattern, which gives useful behavioral context beyond the annotations without contradicting them.

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

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

The description is three sentences long, front-loaded with the primary purpose, lists key parameters in a compact way, and ends with a useful tip. Every sentence earns its place with no wasted words.

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

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

Given the tool's moderate complexity, the combination of description, schema, and annotations covers the core operation, parameter semantics, and return type. Some details like pagination workflow are not elaborated in the description, but the schema's offset documentation fills that gap, making this a well-rounded definition.

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

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

The input schema has 100% coverage with clear descriptions for every parameter. The description mostly repeats these details (e.g., 'SQL-like where', 'comma-separated out_fields') without adding significant new semantic information beyond what the schema provides, so it meets the baseline but does not exceed it.

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

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

The description clearly states 'Query an ArcGIS Feature Service / Map Service layer by its url', specifying the verb and resource. It also notes the source 'from search_datasets', but does not explicitly distinguish itself from sibling tools like layer_info or search_within, so it lacks clear sibling differentiation.

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

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

The description provides context by indicating this tool is used after search_datasets and offers a practical sampling tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly state when to avoid this tool or name alternatives, so it stops short of full usage guidance.

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

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

While annotations already declare the tool as readOnly, idempotent, and non-destructive, the description adds important behavioral context: it is 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and supports listing all keys when the key argument is omitted. This goes beyond the structured annotations and helps the agent understand scope and invocation variants.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence contributes meaning. There is no redundant information; the pairing with remember/forget and the scoping detail are compactly included without clutter.

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

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

Given the low complexity (one optional parameter), complete schema coverage, and strong annotations, the description provides all necessary context: what it does, when to use it, how parameters behave, and how it relates to siblings. Nothing important is missing.

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

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

The schema already provides 100% coverage for the optional 'key' parameter, but the description adds semantic value by explaining that omitting the key lists all saved keys and providing examples of what keys might represent (target ticker, address, research notes). This helps the agent understand the parameter's purpose and behavior beyond the schema's basic type description.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. This specifies a concrete verb and resource, and it distinguishes itself from sibling tools like remember and forget by explicitly referencing them.

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

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

It gives explicit usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' This explains when to use the tool and contrasts with the alternative of re-deriving information. It also mentions pairing with remember and forget, clarifying the tool's role within the family.

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 states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies state mutation. However, annotations declare readOnlyHint=true, directly contradicting that side effect. This is an annotation contradiction, so score is 1.

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

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

The description is five sentences, front-loaded with purpose, and each sentence adds value: return payload, filtering, mark_read behavior, and polling/HTTP alternative. No filler.

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

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

For a read-tool with 5 optional parameters and no output schema, the description covers purpose, return fields, filtering, mark_read, and an alternate access method. The return payload is partially described, and parameter details are in the schema. It is reasonably complete, though the contradiction with readOnlyHint is a 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?

Schema covers all 5 parameters (coverage 100%), so baseline is 3. The description adds beyond schema by explaining mark_read semantics (flags events read so next call only shows newer ones) and giving an example type 'sec_8k'. This extra guidance justifies a 4.

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

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

The description opens with 'Pull fired events from your subscription feed'—a specific verb+resource. It further clarifies the tool returns alerts with source, citation_uri, and raw payload, differentiating it from siblings like list_subscriptions or recent_changes.

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

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

The description explains polling is fine and mentions the same feed is available at a direct HTTP endpoint for scripts/dashboards, giving an alternative. It does not explicitly state when-not-to-use, but the context is 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 discloses key behaviors beyond annotations: the multi-source fan-out to SEC EDGAR, GDELT→GNews fallback, PatentsView sunset soft-fail, and the one-call parallel execution. This complements the readOnlyHint/idempotentHint annotations without contradiction.

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

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

The description is dense but every sentence earns its place. It front-loads with user-intent phrases, then packs source details, date formats, return types, and the alternative tool pointer into a structured, information-rich block 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 having no output schema, the description specifies the return shape (changes[], total_changes, pipeworx:// URIs) and all source behavior. It covers fallbacks, time-window formats, and entity identification, making it fully self-contained for an AI agent to select and invoke correctly.

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

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

Although the input schema already documents all three parameters, the description adds valuable semantics: the `since` parameter accepts both ISO dates and relative shorthand with concrete examples, and it recommends '30d' or '1m' for typical monitoring. This enriches the schema with practical invocation guidance.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with a specific verb ('fans out') and scope. It distinguishes itself from entity_profile by explicitly naming the alternative for static profiles.

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

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

It provides explicit when-to-use signals through natural-language triggers, and an explicit alternative: 'Use entity_profile instead when you want the static profile.' It also clarifies fallback behavior and soft-failure conditions, giving clear guidance on when results are reliable.

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 cover safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but description adds behavioral context: key-value pair scoped by identifier, and persistence differences (authenticated persistent vs anonymous 24-hour retention). This goes well beyond annotations and sets accurate expectations.

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

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

Description is efficiently written: purpose in first sentence, usage guidance and examples in second, storage semantics in third, and companion tool pairing in final sentence. No fluff or repetition; 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 2-parameter tool with no output schema, the description provides all necessary context: what to store, when to use it, persistence behavior, and how it relates to recall/forget. It is complete and self-contained.

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

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

Schema already documents both parameters with clear descriptions (key and value examples, coverage 100%). Description adds general context (what to store) but no additional parameter-level detail. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

Description opens with a specific verb+resource: 'Save data' and clarifies scope ('across this conversation or across sessions'). It distinguishes from sibling tools by explicitly pairing with 'recall' and 'forget', and gives concrete examples of what to store (resolved ticker, target address, etc.).

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

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

Provides explicit usage guidance: 'Use when you discover something worth carrying forward' and gives examples. Also names alternatives/companion tools: 'Pair with recall to retrieve later, forget to delete.' This clearly tells the agent when to use this tool and how it relates to 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds valuable behavioral context: it cascades through several lookup endpoints internally, returns official identifiers plus citation URIs, and auto-disambiguates inputs. This goes beyond the annotations without contradicting them.

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

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

The description is somewhat long but every sentence carries useful information. It is structured with a clear opening directive, supported types, return details, and a value-add statement. It is not overly verbose, but it could be slightly tighter without losing clarity.

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

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

Given the tool has only 2 parameters, a clear enum, and high schema coverage, the description fully covers the necessary context. It explains the return values (ticker, CIK, company_name, RxCUI, ingredient, brand) and citation URIs, making the tool's behavior complete even without an output schema.

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

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

Schema coverage is 100% with descriptions for both parameters, but the tool description adds substantial meaning: it details acceptable input formats for company (ticker, CIK, or name) and drug (brand or generic), and notes auto-disambiguation. This enriches the schema with practical usage details.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with specific examples (ticker, CIK, RxCUI) and supported types. It distinguishes itself by positioning as the first tool to use when you have a name but need an ID, which differentiates it from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit usage context: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use this tool or name an alternative, so it falls 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false, lowering the transparency burden. The description adds behavioral context by explaining that it 'probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns specific metrics. This goes beyond the annotations without contradicting them, though it does not detail rate limits or error handling.

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

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

The description is three sentences, front-loaded with the core purpose, then details the mechanism, use case, and output. Every sentence adds value, and there is no redundancy or fluff. It is concise while covering all key aspects.

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 supplies a clear summary of the return value ('ranked list with score, confidence, signal density per entity'). The input schema fully documents parameters, annotations cover safety, and the description explains behavior and use case. This is complete for a read-only comparison tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal parameter meaning beyond the schema—it mentions 'your brand + N competitors' but the schema already states that the first entity is the subject. It does not clarify any additional parameter behavior beyond what is already in the input schema, so no higher score is warranted.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs and resources, and distinguishes itself from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking. The output is also specified ('ragged list with score, confidence, signal density'), 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 a clear usage context: 'Useful for competitive AI-marketing audits' with a concrete example ('does Claude know about us as well as our competitors?'). It implies that this tool is for comparing entities, whereas ai_visibility_check is likely for single-entity checks. However, it does not explicitly state when NOT to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, eliminating ambiguity about side effects. The description adds valuable behavior beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and the sources_failed field will list timeouts. No contradiction with annotations.

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

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

While long, the description is densely informative and every sentence serves a purpose: purpose, usage trigger, output summary, ecosystem scope, and failure behavior. The front-loaded sentence immediately conveys the core function. No redundant 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?

With no output schema present, the description thoroughly explains the return value structure (summary block fields, per-advisory detail, links, alternative versions). It also covers latency, failure handling, and ecosystem scope. For a composite tool with external APIs, this makes the tool fully self-contained for an agent.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema (package name, version). The description adds context about the tool's npm-only dependency and that version defaults to latest, but this is already stated in the schema. It doesn't introduce new parameter semantics, so the baseline 3 applies.

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

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

The description opens with a specific and vivid purpose: a composite check for adding an npm package to a project, fanning out across deps.dev and bundlephobia. It clearly distinguishes this tool from siblings (e.g., scan_competitor_ai_presence) by explicitly limiting scope to the NPM ecosystem and focusing on package health/size metrics.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states an exclusion/alternative: for PyPI/Maven/Cargo/Go, one should use deps.dev:version directly. This makes when-to-use and when-not-to-use clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds concrete return-value details (name, summary, record_count, owner/org, url) and the inter-tool workflow, which goes beyond the structured metadata.

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

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

Two sentences, no filler. The first sentence states the core function; the second enumerates output fields and the recommended next step. Every word 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 read-only search tool with optional parameters and no output schema, the description provides purpose, output structure, and clear follow-up usage. It is sufficient for an agent to select the tool and understand what to do with results.

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

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

The input schema covers all 3 parameters with descriptions, so the baseline is 3. The description adds no additional parameter semantics beyond saying 'by keyword' which matches the query parameter, but it does not explain the limit or org_id in more depth.

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 ('Search') and names the exact resource ('Lake County GIS open geospatial datasets'), including example categories. It also distinguishes itself from siblings by noting the returned Feature Service URL can be passed to query_layer/layer_info.

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 clear context for when to use the tool (finding open GIS datasets by keyword) and explicitly indicates a follow-up action ('pass that url to query_layer / layer_info'). It doesn't state when not to use it or name alternative search tools, but the workflow is evident.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the bar is lower for additional behavioral disclosure. The description goes beyond by revealing implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation flagging, and that results include offsets for verification. All of this adds significant transparency 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 four sentences, each earning its place: it states the core function, provides the primary use case, suggests a pairing with a sibling tool, and discloses technical constraints. It's front-loaded with the key 'inside a fetched record' scope and remains focused without verbosity.

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 appropriately explains what the tool returns: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (longer inputs truncated and flagged) and the max input size. Given the tool's moderate complexity and strong annotations, the description fully equips an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some semantic richness (e.g., what kind of text to pass, examples of queries), but it largely restates what the schema already provides. It doesn't introduce new parameter-level information that changes how to use them.

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

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

The description specifies a clear verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing that it operates on already-fetched text rather than a broader knowledge base, and it clarifies the output (top-N passages with offsets and scores). This makes 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 explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt' and how it saves context. It also provides an alternative and complementary workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear, actionable 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?

Adds substantial behavioral context beyond annotations: OAuth requirement, anonymous/BYO cannot persist, SMS cap (10/day), phone verification, and webhook auto-disable with signing secret. No contradiction with annotations (readOnly=false, destructive=false).

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

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

Single dense paragraph, front-loaded with core action, then prerequisites, types, and delivery channels. Every sentence contributes useful information with no wasted words.

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

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

Covers core types (sec_8k, polymarket_edge, fred_series) and delivery (feed, email, sms) but omits webhook and two types (patent_grant, clinical_trial) from prose. However, the schema fully describes these, so the description remains fairly 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 description largely repeats examples already in the schema (e.g., items:'5.02', topic:'fed'). It adds no new parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description uses a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also states the return value (subscription id) and clearly differentiates from sibling tools like list_subscriptions/unsubscribe by focusing on creation.

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

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

Provides clear context: requires OAuth account, phone verification for SMS, and delivery options. It does not explicitly state when-not-to-use or name alternative creation tools, but does mention pulling the feed via recent_alerts as a consumption alternative.

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

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

Annotations already indicate safe, read-only, idempotent, open-world behavior. The description adds substantial context: it returns category-bucketed example questions, includes exact tool+argument shape from the live catalog, and supports full spread via no arguments or focused via topic. This reveals invocation behavior and output content 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?

Long single paragraph but densely informative; all sentences contribute value. Front-loaded with natural language query examples, though it could benefit from bullet points for readability. Not excessive given the tool's onboarding purpose.

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

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

For a one-parameter, no-output-schema tool, the description fully covers what it returns, how the parameter behaves, and when to use it. It even gives example phrasings and lists categories. No obvious gaps remain for an agent to understand 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 already documents topic with 100% coverage. Description augments by explaining that omitting topic yields a cross-category spread while passing a topic focuses results, and provides example values that align with the schema. This adds semantic understanding of how to use the 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?

Description clearly states the tool's role as an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It says to use it FIRST when unfamiliar with Pipeworx, which distinguishes it from other tools, though it doesn't explicitly name sibling tools like discover_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?

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how the optional topic parameter affects breadth vs. focus. No explicit alternatives or exclusions, but the 'FIRST' placement is strong.

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

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

The description goes beyond annotations by disclosing ownership enforcement and the deactivation (vs deletion) behavior. This complements the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) and provides critical context about side effects and permissions.

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 concise sentences, front-loaded with the core action and followed by necessary constraints and side effects. 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 tool with one parameter and no output schema, the description covers purpose, constraints, and behavioral effects thoroughly. It also connects to recent_alerts for historical data, which is helpful. Minor omissions like error handling are not critical given the idempotent annotation.

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

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

Schema coverage is 100% with the 'id' parameter already described as a subscription UUID returned by subscribe. The tool description itself adds no extra parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the operation (cancel). It also distinguishes from siblings like 'subscribe' (creation) and 'list_subscriptions' (listing) by mentioning ownership enforcement and deactivation behavior.

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

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

The description provides clear usage context: you can only cancel your own subscriptions, and cancellation deactivates rather than deletes, preserving historical events via recent_alerts. It doesn't explicitly name alternative tools, but these details imply when to use this tool and what to expect.

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

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

Annotations already declare the tool read-only and non-destructive, but the description adds substantial behavior beyond that: it explains the two execution paths (SEC EDGAR/XBRL fast path and grounded pipeline), lists possible verdicts, mentions verbatim evidence and citations, and notes the tolerance override behavior. This enriches the agent's understanding of what happens internally. No contradiction with annotations.

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

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

The description is lengthy but every sentence carries information: triggers, use cases, paths, return values, and efficiency gains. It is front-loaded with natural-language triggers and well-structured with hyphens and examples. Slightly verbose but not wasteful, earning a high score rather than perfect.

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 two parameters and no output schema, the description fully carries the burden of explaining the return value (verdict, actual value, citation, reasoning) and the conditional behavior for different claim types. It gives enough context for an agent to select and invoke the tool correctly without needing additional documentation.

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

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

Schema coverage is 100%, but the description adds meaning to both parameters. It provides example claims for the `claim` parameter and explains `tolerance_pct` semantics beyond the schema: how to set it for hallucination detection, the default cap at 5, and the override behavior. This goes well beyond the baseline.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with concrete trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from siblings by emphasizing the claim-verification workflow and noting it replaces several sequential calls. The verb+resource ('validate claim') is specific and unambiguous.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear context. It also differentiates between company-financial claims and other claims with separate paths. However, it doesn't explicitly state when not to use it or mention alternative sibling tools, so it stops 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.