Arcgis Berkscounty

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: default model selection, cost implications of using Anthropic (BYO key), and the per-model return structure, going beyond the 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?

The description is just three sentences, all substantive, with the core function stated first. No filler or redundant information; 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?

Despite the lack of an output schema, the description mentions the per-model return shape and combined view. It covers model selection, API key handling, and context disambiguation, making it sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so all parameters are described. The description adds meaning by explaining the default model behavior, the relationship between _apiKey and the models array, and how the context parameter aids disambiguation, which goes beyond the schema field descriptions.

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

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

The description clearly states the tool probes LLMs and scores visibility (0-100) per model, using a specific verb and resource. It distinguishes itself from sibling tools like ask_pipeworx by focusing on visibility scoring rather than Q&A or entity resolution.

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 lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), providing clear when-to-use context. However, it neither mentions complementary/alternative tools nor offers explicit exclusions, so it stops short of full guidance.

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

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

Annotations already indicate a read-only, idempotent, open-world tool, so the description additionally explains the routing behavior: it picks among 5,596 tools, fills arguments, and returns pipeworx:// citation URIs. This adds valuable context about how the tool behaves beyond the annotations. No contradiction with annotations is present.

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

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

The description opens clearly with 'PREFER OVER WEB SEARCH' and has a logical flow: data categories, mechanism, trigger phrases, examples. However, it is repetitive, repeating the 'START HERE' sentence and the example list, which makes it longer than necessary. A more trimmed version would earn a higher score.

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

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

Given the simple input schema and read-only annotations, the description is largely complete: it tells the agent what kinds of questions to route, how the tool works, what kind of answer to expect, and gives concrete examples. The only notable gap is the lack of explicit comparison with beta/grounded sibling variants, but that does not leave the agent unable to invoke it.

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

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

The schema already fully documents the single 'question' parameter and its aliases. The description adds usage triggers and concrete example questions, helping an agent understand the expected natural-language input style. This is useful beyond the schema and warrants a higher-than-baseline score.

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

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

The description clearly states the tool's purpose: it routes natural-language factual questions to a set of verified data sources and returns structured answers with citations. It gives a specific verb, resource, and scope, and distinguishes itself from web search. However, it does not explicitly differentiate itself from sibling tools such as ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description gives explicit guidance on when to use, including trigger phrases like 'what is', 'look up', 'get the latest', and examples. It even says to prefer this over web search and to start here for most questions. It does not provide clear 'when not to use' or point to specific sibling alternatives, so it is not a perfect 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?

The annotations already cover read-only/idempotent/open-world characteristics. The description adds real transparency about the beta: it emits candidate improvements and that no candidate currently active? god, good. this is a full working router, not a stub. This is beyond what annotations say about runtime 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 reasonably concise and front-loaded with the most important context, and every sentence contributes either usage, behavioral state, or clarification. The exact retire date is more detail than needed, but not enough to measurably harm the description.

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 router with one required parameter and full schema, the description covers the important context: it is a full working router, currently identical to ask_pipeworx, and has the same arguments and response shape. There is no output schema, and the description does not detail exact return content, but the pointer to the identical response shape compensates.

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% already, and all parameters are just aliases for the single question parameter. The description adds no meaningful parameter detail beyond saying the arguments are identical to ask_pipeworx, so the baseline score of 3 is appropriate.

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

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

The description clearly characterizes the tool as the beta variant of ask_pipeworx, an identical-in-interface universal router, and distinguishes it from the stable sibling via candidate routing. It lacks a simple action verb, but the instruction to use it exactly like ask_pipeworx and the specification of a former tool base make the purpose clear.

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

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

It explicitly says to use it like ask_pipeworx when the newest routing is desired, which is a concrete usage condition. The alternatives of stable vs experimental are referenced but not fully spelled out as a stable-only branch. The mention that results are compared against the stable router adds helpful context.

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

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

The description discloses behavioral traits beyond the annotations, such as extraction using only the tool result, explicit refusal with reasons like 'not_in_source' or 'tool_error', and the specific success return shape (evidence, confidence, source, etc.). It also discloses performance implications (extra LLM call), which the annotations do not cover.

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

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

Though relatively long, every sentence is informative and front-loaded: the key trait (hallucination-resistant) appears first, followed by the mechanism, return/refusal behavior, use cases, and cost trade-off. There is no fluff.

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

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

The description covers the full call cycle: selection, execution, extraction, return, and refusal modes. It even specifies the cost and preference relative to siblings, so an agent has everything needed to decide and invoke the tool correctly.

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

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

The parameter schema is fully documented with 100% coverage: all six parameters are aliases for 'question' and are described. The description doesn't add additional parameter semantics, but no further explanation is needed because the schema is already clear.

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

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

The description clearly states the tool's purpose: it is a hallucination-resistant answer mode that routes through 5,596 tools and extracts answers solely from the returned tool result. It explicitly differentiates itself from ask_pipeworx by mentioning the same routing but with grounded extraction, which distinguishes it from its sibling.

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 guidance is explicit: 'Use whenever an answer will be quoted, cited, or acted on, and must not invent facts' with concrete examples. It also clearly tells the agent to prefer ask_pipeworx for casual lookups because of the extra LLM call cost.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description extensively details behavior: resolver contract with confidence levels, short-circuit paths for low-confidence matches, closed-market handling, wide-spread warnings, and cancellation-rule risk. It also explains fan-out parallelism and response shapes, making the tool's behavior exceptionally transparent.

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

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

The description is long but well-organized with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a strong first sentence that front-loads the purpose. Every section adds necessary detail for a complex tool, though the sheer length could be intimidating.

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

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

With no output schema, the description takes on the full burden of explaining return values and edge cases. It covers resolver confidence, parent events, news fallbacks, safety suppression, illiquidity warnings, and cancellation rules—everything an agent needs to handle the tool's complexity correctly.

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

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

The input schema already provides full descriptions for all three parameters (market, depth, include_raw), so the baseline is 3. The description adds extra context with examples of market formats and clarifies the 'thorough' default for depth, but it does not materially enhance parameter understanding beyond what the schema already offers.

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

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

The description opens with a specific, action-oriented statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings by emphasizing one-call aggregation and the market-vs-model comparison, and the 'Use for...' phrases further anchor its purpose.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' which gives clear usage context. It also provides safety guidance ('ALWAYS inspect these before trusting the analysis block', 'Check this before sizing sports/esports/event-occurrence bets') but does not explicitly name alternative tools or say when not to use it.

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

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

The description adds rich behavioral context beyond the annotations: it discloses data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years (AAPL, NVDA), sorts results by primary metric, and returns paired data with citation URIs. This significantly enhances the agent's understanding of what the tool does beyond the readOnlyHint.

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 trigger phrases to help the agent recognize when to use the tool. Every sentence serves a purpose: usage triggers, core function, per-type data details, sorting behavior, and return format. It is dense but tightly structured 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?

The description covers purpose, usage, parameters, data sources, edge cases (off-calendar fiscal years), and return format. Given the tool's complexity and lack of output schema, it provides comprehensive information needed 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?

Even though the schema has 100% coverage, the description adds meaning by explaining what each type value does: company pulls 10-K financial data, drug pulls adverse-event and trial counts. It also provides examples for the values parameter and clarifies the 2–5 limit.

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

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

The description explicitly states a side-by-side comparison of 2–5 companies or drugs, using a specific verb ('compare') and resource ('companies or drugs'). It distinguishes itself from sibling tools like entity_profile by emphasizing parallel comparison and listing concrete data sources for each entity type.

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

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

The description provides explicit 'when to use' guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and includes trigger phrases like 'Compare X and Y' and 'rank these companies'. It also notes it replaces 8–15 sequential lookups, clarifying the 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 establish read-only, idempotent, non-destructive behavior, and the description adds exceptional behavioral context beyond that: the parallel decomposition over 5,596 tools, the findings-packet shape with confidence/source/fetched_at/citation, the never-invents gap[] guarantee, contradictions[] for standard/thorough, and semantic excerpting for large records. It also discloses latency (15-60s; up to ~90s for thorough). 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 every sentence carries operational weight — no filler. Critical routing info is front-loaded (account requirement, fallback tool, domain strip), followed by process, output format, latency, and peer comparison. The density is proportional to the tool's complexity; the structure is front-loaded and information-dense without redundancy.

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

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

For a tool of this complexity (2 params, 100% schema coverage, NO output schema), the description carries the full burden of explaining return semantics — and it does so comprehensively: the findings packet fields, gap[] and contradictions[] collections, the fetchable citation guarantee, and latency. The only minor omission is what exactly happens if the user requests 'thorough' without a paid plan, but that's a small edge detail against an already thorough 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?

Schema coverage is 100% and already fully describes both `question` and `depth` semantics. The description earns extra credit by adding the cost gate for `depth:'thorough'` needing a paid plan, and the use-case guidance (broad/multi-part is fine, decomposition is the point) that helps an agent choose parameter values. This raises it above the baseline 3, though the schema already does the primary documentation work.

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 names a specific verb and resource ('Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources'), declares what it is not ('this is NOT open-web search'), and explicitly contrasts itself with ask_pipeworx for single lookups. It also gives concrete example queries ('compare X and Y's regulatory + financial exposure'), so an agent can unambiguously identify what this tool is for and how it differs from all 30+ siblings.

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

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

Explicit when/when-not guidance: 'If you are not signed in, use ask_pipeworx instead', 'Best for broad/multi-part questions over structured data', and 'For a single lookup use ask_pipeworx instead.' It also names the constraint of paid plan for the 'thorough' depth. This leaves no ambiguity about when the agent should choose this tool vs. a sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by explaining what results contain (names, descriptions, full input schemas with curated examples), that they are ready to call directly without a second lookup, and that the tool should be invoked first in multi-tool scenarios. This goes beyond annotations but doesn't cover all potential edge cases like pagination or error handling, hence a 4.

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

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

The description is four sentences, but each sentence serves a purpose: purpose, usage, return format, and a 'call first' recommendation. The domain list is long but directly informs query possibilities. It is front-loaded with the core verb and resource, making it easy to parse. Slightly verbose due to the exhaustive domain enumeration, but still efficient.

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

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

For a discovery tool with no output schema, the description fully covers what is returned (name, description, full schema, examples), when to use it (browse/search/discover), and how to invoke it successfully (natural language query). It also provides a comprehensive list of supported domains, making it complete for an agent to decide and call the tool without further information.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds value by clarifying that query is a natural language description of the data/task, providing a domain list that directly informs query construction, and using 'top-N' to explain the limit parameter. This raises it above the baseline of 3 without fully compensating for all parameter nuances.

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

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

The description opens with 'Find tools by describing the data or task', clearly stating the verb (Find) and resource (tools), and differentiates itself from siblings by noting it should be called first when many tools are available. Unlike vague descriptions, it provides a concrete mechanism (describing data/task) and a specific role in the tool ecosystem.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and gives a strong directive to 'Call this FIRST when you have many tools available'. It also implies when not to use it ('not just one answer'), but does not name alternative tools or provide explicit when-not-to-use scenarios, stopping 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?

Adds significant behavioral context beyond annotations: fans out across multiple sources, returns specific data fields, and notes important fallback/soft-fail behavior (e.g., 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', 'GDELT→GNews fallback'). This aligns with readOnly/idempotent annotations and provides operational details.

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

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

The description is front-loaded with purpose and examples, then provides necessary details about return fields. It is longer than ideal, but each sentence carries information (e.g., the list of return fields and source fallback). Slightly verbose with example phrases, but well-organized and not wasteful.

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

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

Despite no output schema, the description details the return structure (cik, recent_filings, fundamentals, patents, news, LEI) and constraints (US public company, names not supported, zero-padded CIK). It covers the tool's complexity effectively, including failure modes, so an agent has a complete picture.

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

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

The schema already covers both parameters with full descriptions (100% coverage), including the enum for type and the ticker/CIK format for value. The description repeats this information (e.g., 'zero-padded CIK') without adding new semantic meaning. 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 produces a 'full cross-source profile of a US public company in ONE parallel call', with specific verb examples like 'Tell me about', 'research', 'brief me on'. It distinguishes itself from single-source lookups by explicitly preferring this tool for holistic views, and the return structure is outlined.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the alternative for name-only inputs: 'use resolve_entity first if you only have a name'. This clearly tells the agent when to use this tool vs 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 destructiveHint=true and idempotentHint=true. The description adds that it deletes 'previously stored' memories and mentions sensitive data, but does not disclose error behavior, return values, or irreversibility beyond the annotation. It is consistent with annotations but adds only modest behavioral context.

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

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

The description is two sentences, front-loaded with the core action, and contains no redundant information. It is efficiently structured and easy to scan.

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

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

The tool is simple with one parameter, and annotations cover the destructive and idempotent aspects. The description provides clear usage context and references sibling tools, but it does not mention behavior for missing keys or the return format. This is a minor gap, making the description slightly incomplete but sufficient for the tool's simplicity.

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 only parameter 'key' described as 'Memory key to delete.' The description's phrase 'by key' adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, effectively distinguishing it from sibling tools like remember (store) and recall (retrieve). It is unambiguous and action-oriented.

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

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

Explicitly provides when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references pairing with remember and recall, giving clear context on how the tool fits into the memory workflow.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds valuable behavioral context by explaining it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and stating the output is a 'single text blob ready to drop at site-root/llms.txt.' 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 three sentences long, each adding distinct value: the first states the primary action and audience, the second outlines the process, and the third lists concrete use cases. There is no redundancy or filler.

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

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

For a relatively simple tool, the description covers the main workflow, output format, and use cases. The lack of an output schema is mitigated by stating the output is a 'single text blob ready to drop at site-root/llms.txt.' Error handling and edge cases are not mentioned, but given the low complexity and rich schema, this is acceptable. A score of 4 reflects the minor omission of max_links behavior, which is already covered by the 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?

Both parameters (url and max_links) are fully described in the input schema, so schema coverage is 100%. The description mentions 'any URL' and the extraction process, but it does not add semantic meaning beyond the schema for either parameter, and max_links is not referenced in the description. 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 verb ('Generate') and a concrete resource ('production-ready llms.txt file'), then clarifies the purpose for AI crawlers. This clearly distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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

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

The description includes a 'Useful for:' section listing three concrete scenarios (client sites, own projects, auditing competitors), providing clear context for when to invoke this tool. However, it does not explicitly contrast against alternative tools or state when not to use it, so it falls short of a perfect 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?

The description adds value beyond annotations by detailing the specific data returned (fields, geometry type, record count, capabilities). The annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is covered. The description aligns with these annotations and provides additional output context, earning a 4.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, lists the key outputs, and contains no redundant words. It is appropriately concise for a tool with one parameter.

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

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

Given the tool's simplicity (one parameter), the absence of an output schema, and the rich annotations, the description is complete. It explicitly names the four types of information returned, leaving no major gaps for the agent to infer. The context is entirely sufficient.

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 single parameter 'url' is fully described in the schema with an example, achieving 100% schema coverage. The tool description mentions 'by url' but adds no additional meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema carries the semantic weight.

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 the specific verb 'Get' with a clear resource ('ArcGIS Feature/Map Service layer's schema') and specifies the exact output components: fields, geometry type, record count, and capabilities. This clearly distinguishes it from siblings like query_layer, which would focus on retrieving data rather than schema.

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 makes it clear that the tool is used to retrieve schema information via URL, which implies when to use it. However, it does not explicitly mention alternatives or when not to use it, though the sibling tool 'query_layer' suggests a clear alternative for data queries. The context is clear but lacks explicit exclusions or alternative names.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is clear. The description adds transparency by listing the exact return fields and specifying that it only returns the caller's subscriptions, providing context beyond the annotations. No contradiction is present.

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

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

The description consists of two efficient, front-loaded sentences. The first states purpose and return output; the second explains when to use it. Every word earns its place, with 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?

For a simple list tool with one optional parameter and no output schema, the description is complete: it explains what the tool does, what it returns, and why you might call it. The return fields are enumerated to compensate for the absent output schema. No significant 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 covers the sole parameter (include_inactive) with a clear description, and coverage is 100%. The tool description mentions 'active subscriptions' which indirectly relates to the parameter but does not add new semantic meaning 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 uses a specific verb ('List') with a clear resource ('the caller's active subscriptions') and explicitly names the returned fields (id, type, params, created_at, etc.), making its purpose unambiguous. This distinguishes it from sibling tools like subscribe and unsubscribe by focusing on reading existing subscriptions.

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

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

The description gives direct usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It explains when this tool is appropriate and even implies the relationship to subscribe/unsubscribe, but it does not explicitly name alternative tools or say when not to use it.

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

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

Annotations are all false and provide no safety or side-effect info, so the description carries the burden. It discloses rate limiting (5/day), quota immunity, the claim_token mechanism, and daily human review, giving the agent a clear picture of consequences beyond structured fields.

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

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

The description is long but dense, with every sentence conveying a distinct operational fact (scope, exclusions, token flow, rate limit, quota). Front-loaded with the core 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?

Despite having no output schema, the description explains return behavior (claim_token on anonymous filing, later status when token passed) and all necessary constraints. Covers what to report, how to scope it, and operational limits, making it complete for a feedback 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 already covers all four params with descriptions, including enum meanings and claim_token semantics. The description adds practical usage guidance—how to pass claim_token later and to describe issues in terms of Pipeworx tools—so it adds value beyond the schema.

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

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

The opening sentence states a specific verb ('Tell... something is broken, missing, or needs to exist') and resource ('Pipeworx team'), clearly distinguishing it from the research/query siblings. The title and name align, and examples in the description cement its purpose.

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

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

Provides explicit when-to-use categories (bug, feature/data_gap, praise) and a clear exclusion: only for tools served by this Pipeworx connection, with instructions to file elsewhere for other MCP servers. Also advises what not to include (end-user prompt) and how to follow up via claim_token.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the data source (CF analytics-engine), privacy (no PII), and caching (5min-1h depending on window). This adds meaningful context about what the tool actually does and its freshness.

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 structured with a hook, output statement, numbered use cases, and a transparency note. At roughly 100 words, it remains efficient and front-loads the core 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 read-only tool with one optional parameter and no output schema, this description covers return values, use cases, data provenance, privacy, and caching. It is fully sufficient for an agent to decide when and how to invoke it.

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

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

The single parameter window is fully documented in the schema, so the description does not need to explain its values. It adds a small detail that caching depends on window, extending the schema meaning.

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 concrete purpose statement ('What other AI agents are calling on Pipeworx right now') and explicitly lists outputs ('top tools, top packs, and total call volume'). This clearly distinguishes it from discovery or query tools by focusing on aggregated trending signal.

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 three numbered 'Useful for' scenarios that specify when to consult trending data, such as confirming a canonical tool before asking a question. However, it does not mention when not to use it or alternative sibling tools like discover_tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context beyond annotation: the partition filter drops placeholder slugs and returns null signals for high placeholder fractions; the fill check prices against live CLOB depth and warns not to trade if realizable_edge_pp ≤ 0. This is substantial transparency about edge cases and operational behavior. No contradiction with annotations.

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

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

The description is long but information-dense. It uses clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to break up complex logic. Every sentence contributes unique operational knowledge—mode behavior, response shape, constraints, and risk warnings. 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 no output schema and high complexity, the description fully covers what the tool does, how to invoke it in each mode, what the response contains (opportunities[] with fields, partition_check details), and how to interpret fill-check results. It even gives examples of valid inputs. The absence of an output schema is mitigated by the textual description of the response 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?

Schema coverage is 100% (both event and topic have descriptions with examples). The description goes significantly beyond the schema by explaining mode semantics: event accepts slugs or full URLs, walks child markets and checks ordering; topic searches related events and flattens markets. It also explains the semantic anchor and partition filter thresholds that affect parameters. This adds real value over structured schema.

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

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

The description starts with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes multiple modes (trending_scan, event, topic) and contrasts with sibling tools by mentioning cross-event scanning and fill risk. The purpose is unmistakable and not a tautology.

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

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

Explicit guidance is given: '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 recommends event mode for specific markets and explains when cross-event mode is superior ('Cross-event mode catches ... patterns that single-event misses'). It also points to an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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

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

The description goes far beyond the annotations by detailing response structure, model families, edge calculation, Kelly caps, slippage assumptions, diagnostics, and caching behavior. It also discloses limitations (e.g., Fed bets excluded due to unreliable signal) and explains why segments may be empty. This is exceptionally transparent and consistent with the readOnly/idempotent hints.

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

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

The description is lengthy but well-structured, front-loaded with the core purpose and organized into clear thematic paragraphs. Some redundancy exists (e.g., 'FIVE MODEL FAMILIES' appears to list only four families), but overall it is appropriately detailed for the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It covers top-level response keys (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity), model family behaviors, caching, and diagnostic funnel counters. An agent can confidently interpret results and decide when to call this tool.

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

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

Although the schema provides 100% parameter documentation, the description adds significant semantic value by explaining the rationale behind knobs like min_partition_leg_kelly (why parent-level Kelly is always 0) and how tradeable-edge filters work. It also clarifies slippage assumptions and how edge is evaluated net of slippage, enriching the bare schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The use case 'what should I bet on today' and the mention of Pipeworx data differentiate it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 intended use case ('what should I bet on today') and explains when knobs like min_liquidity and max_spread_pp should be applied. It does not explicitly name alternative tools or state when not to use it, but the emphasis on high-level discovery implies a distinction from more detailed sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial context beyond that: response structure (tracked/expired/snapshot_dates), decay computed on |edge_pp_net|, snapshot gaps on cache-miss, 60-day TTL, and 'not intraday' caveat. 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 well-structured with Args, RESPONSE, and LIMITS sections, and purpose is front-loaded. Slightly verbose with rhetorical framing ('wide for a reason nobody is willing to take'), but each section earns its place given the tool's complexity.

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

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

No output schema exists, so the description must explain return values—and it does thoroughly: tracked[] items, expired[] with lifespan_days, snapshot_dates[] meaning, and historical limits. This is complete for a complex telemetry 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% (both days and window have descriptions). The description mirrors defaults (days default 14 max 30, window default 1wk) but adds no new meaning 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 purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. This specific verb+resource distinguishes it from sibling polymarket_edges by focusing on historical persistence rather than current edge values.

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: use this when you need to know edge age/decay, not just current edge width. The rationale ('a fresh wide edge and a 3-week-old wide edge are different trades') implies when to choose this tool, but it doesn't explicitly name alternatives or state when not to use it.

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

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

The description adds substantial context beyond annotations: it details ladder-walking behavior, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and the specific risk of partial basket fills converting arb into unhedged directional positions. This complements the readOnly and idempotent hints without contradiction.

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

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

The description is long but highly structured, using labeled sections (SINGLE-MARKET, BASKET) and clear lists of return values. Each sentence carries meaningful information, though some compression could improve readability without losing key details.

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

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

Given the tool's complexity (two modes, many return fields, no output schema), the description is remarkably complete: it explains mode selection, parameter semantics, return values, and risk caveats like thin_legs and forced_directional_risk. It fully compensates for the lack of 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?

Even though the schema describes all parameters (100% coverage), the description adds deeper meaning: it explains size_usd interpretation differently for single-market vs basket (spend vs target proceeds vs settlement notional), and clarifies side defaults and mode selection. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It names specific verbs ('check', 'returns') and distinguishes between single-market and basket modes, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to rely on theoretical edge and warns against partial fills, giving clear contextual triggers and alternatives.

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

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

The description richly discloses behavior beyond the annotations: it details compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It explicitly warns about potential meaninglessness of spreads when aligned:false, and honestly states that most pre-mapped topics return warnings. The annotations (readOnly, openWorld, idempotent, non-destructive) are complemented rather than contradicted.

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 specific, non-redundant information. It uses clear structural markers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. The density is justified by the tool's complexity, and there is 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 tool's complexity, the absence of an output schema, and the need to explain cross-venue matching caveats, the description is remarkably complete. It covers input modes, response contents (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment), and edge cases (skipped_cross_type, aligned:false). It gives agents enough to interpret results and avoid false expectations.

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

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

The input schema already provides 100% coverage with per-parameter descriptions, so the baseline is 3. The description adds meaningful mode-level semantics: it clarifies that `topic` auto-fetches matching events on both venues, while explicit ticker/slug parameters override for custom pairings. This helps the agent choose which parameters to supply, though the schema already includes override details. The added value is moderate but real.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (Kalshi–Polymarket spread) and the action (computing/reporting the spread), distinguishing it from sibling tools like polymarket_arbitrage which focus on single-venue edges. The two modes and response description further clarify 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 explicitly explains when to use each mode: 'TWO MODES: (1) `topic` — 10 pre-mapped macro shortcuts... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings.' It also provides when-not guidance: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This helps the agent decide whether and how to invoke the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, covering safety. The description adds value by specifying the return format (attribute rows and geometry) and providing a usage pattern. It does not contradict annotations and offers context beyond 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 core purpose, followed by a parameter summary and a practical tip. Every sentence contributes useful information with no redundancy.

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

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

For a 6-parameter tool with no output schema, the description covers the essential context: source of the URL (search_datasets), return type (rows and geometry), and a sampling pattern. It does not elaborate on pagination behavior or error handling, but the schema covers offsets and limits, so it is sufficiently complete.

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

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

The input schema has 100% coverage with detailed descriptions for all six parameters. The description merely summarizes the parameters (SQL-like where, comma-separated out_fields, etc.) without adding new syntactic or semantic details. This matches the baseline for well-documented schemas.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, using a specific verb and resource. It distinguishes itself from sibling tools like search_datasets (finds datasets) and layer_info (presumably metadata) by focusing on 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 provides a clear usage context: the URL should come from search_datasets, and it offers a practical sampling tip (where="1=1" + out_fields="*"). However, it does not explicitly mention alternatives or when not to use this tool, such as layer_info for metadata, so it's slightly below 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral context beyond annotations: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys by omitting the argument. It doesn't describe error handling or return format, but for a simple memory read, this is adequate.

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, with the main action front-loaded and no wasted sentences. It includes a few extra details (scoping, pairing) that each earn their place. Slightly longer than a minimal two-sentence description but still appropriately sized.

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 memory tool, the description covers behavior, scoping, and relationships with sibling tools. Since there is no output schema, the return value is implied (the saved value or list of keys). The context signals and schema are sufficient; the description fills the essential 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 coverage is 100% (one parameter with description). The description adds meaning by clarifying the dual behavior of the 'key' parameter: retrieve a specific key when provided, list all keys when omitted. This goes beyond the schema's description and helps the agent use the parameter correctly.

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

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

The description starts with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes the tool from its siblings 'remember' (save) and 'forget' (delete), leaving no ambiguity about its function.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides pairing guidance with 'remember' and 'forget', making the usage context clear and differentiating from alternatives.

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

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

The description discloses mark_read state mutation ('flag returned events read so the next call only shows newer ones') and tells about the same feed at a URL. However, this contradicts the readOnlyHint annotation, which implies no state changes. This is an annotation contradiction, so the score is 1 per rubric.

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

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

Three sentences, front-loaded with the core purpose, and every sentence adds information (payload composition, filtering, side-effect, polling/alternative URL). No fluff.

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

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

For a read-oriented tool with full schema coverage, this description covers the return payload, filter flags, side-effect behavior, polling suitability, and alternative access method. The only missing element is unread_only semantics, but that's already in the schema. Despite the annotation contradiction, the description is 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?

Schema covers all five parameters, so the baseline is 3. The description adds an example filter value ('sec_8k') for type and clarifies the consequence of mark_read (next call returns only newer events), going beyond the schema. Unread_only is left to the schema, but overall adds value.

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 pair ('Pull fired events from your subscription feed') and clarifies it returns the most recent alerts, distinguishing it from sibling tools like list_subscriptions (which lists subscriptions) and recent_changes (which likely lists 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 gives practical context: it says polling works fine and names an alternate REST endpoint for scripts/dashboards, which helps agents decide when to use this tool vs direct HTTP access. It doesn't explicitly contrast with sibling tools, but the purpose is clear enough.

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

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

Annotations indicate a safe, read-only, idempotent operation. The description adds valuable behavioral details: fan-out to specific APIs (SEC EDGAR, GDELT/GNews, USPTO), fallback logic (GDELT preferred, GNews on rate limit/5xx), soft-fail due to PatentsView API sunset, and response structure. This goes well beyond the annotations.

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

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

The description is information-dense but well-structured: it opens with user-facing query patterns, then explains the underlying fan-out and parameters, then return shape, then the alternative tool. Every sentence adds unique value, and the length is justified by the tool's complexity.

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

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

Even without an output schema, the description specifies the return format (changes[] grouped by source, total_changes, pipeworx:// citation URIs). It also covers potential caveats like API fallbacks and sunset-driven soft-fails. Given the tool's complexity and the absence of an output schema, this is complete.

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

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

Schema descriptions already cover all three parameters (100% coverage). The description enriches this with concrete examples for `since` (ISO and relative like "7d", "30d", "3m", "1y"), recommended values ("30d" or "1m"), and the exact format for `value` (ticker or zero-padded CIK). This is additive, not redundant.

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 a change feed for a company over a recent window, with explicit examples of likely queries. It distinguishes itself from the sibling entity_profile by stating that tool is for static profiles regardless of window.

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

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

The description provides explicit usage scenarios ("What's new with X", etc.) and directly names the alternative tool (entity_profile) with the exact condition for choosing it over this tool. It also explains fallback behavior for news sources, which helps the agent decide when to invoke.

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 meaningful context beyond annotations: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions, and retention duration (24 hours). It does not mention overwrite behavior, but the idempotentHint annotation reduces the need for that detail. This is strong supplementary information for a simple write tool.

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

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

The description is front-loaded with the primary purpose and then adds usage context, storage details, session-specific behavior, and companion tool references. Every sentence contributes critical information without redundancy or fluff, making it concise and well-structured.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, usage, persistence semantics, and integration with related tools. Combined with complete schema descriptions and annotations, the description leaves no significant behavior unexplained.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents key and value with examples. The description's examples mirror schema fields without adding new semantic depth for the parameters. Baseline 3 is appropriate since the description does not degrade but also provides no additional parameter-level insight.

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 ('Save data the agent will need to reuse later') and specifies the resource (key-value pairs). It distinguishes itself from sibling tools by explicitly naming recall and forget as companion operations, making its purpose unmistakable.

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

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

It gives explicit when-to-use guidance ('Use when you discover something worth carrying forward') with concrete examples (resolved ticker, target address, user preference) and contrasts with the alternative of having to look it up again. It also names companion tools (recall, forget), clarifying the relationship with 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 mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral detail: internal cascade through multiple lookup endpoints, graceful degradation of LEI/FIGI enrichment, explicit statement of unresolved identifiers, cross-source identity spine, and source-labeling of identifiers. No contradictions with annotations.

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

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

The description is front-loaded with action examples and a clear directive. It is longer than necessary but every sentence earns its place by adding critical detail about identifier sources, resolution behavior, and edge cases. Some redundancy in the company type explanation could be tightened, but overall it is well-structured and informative.

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 2 parameters with 100% schema coverage, no output schema, and no nested objects, the description is remarkably complete. It fully explains the return value structure (identifiers with source labels, unresolved list), error handling (graceful degradation), and the scope of supported identifiers. An agent can confidently use this tool 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% with both parameters described, but the description adds substantive value: it explains that 'company' type returns a cross-source identity spine including CIK, ticker, LEI, FIGI, and ownership data, and that 'drug' returns RxCUI, ingredient, brand, and a citation. It also provides concrete input examples (AAPL, 0000320193, ozempic) and behavior for ISIN inputs.

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

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

The description opens with concrete examples of user queries ('What's the ticker for...', 'find the CIK for...'), immediately establishes the core action ('resolve a user-spoken NAME to the canonical/official identifiers'), and explicitly states 'Use FIRST whenever you have a name but need an ID.' It distinguishes between entity types (company vs drug) and clearly differentiates from sibling tools by focusing on identifier resolution.

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

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

The description provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and lists example queries that trigger this tool. It does not explicitly state when NOT to use it or mention alternative tools like entity_profile or compare_entities for cases where an ID already exists, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it internally calls ai_visibility_check per entity, ranks results, and returns a structured list with score, confidence, and signal density. No contradictions.

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

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

Three concise sentences, all substantive: the core action, a motivating use case with an example, and the output contents. Front-loaded and free of 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, but the description compensates by listing output components (ranked list, score, confidence, signal density). It also explains the internal mechanism and typical scenario. Minor gaps, such as not restating the entity-count limit, are covered by the 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 has 100% coverage, so baseline is 3. The description reinforces the entities array semantics (brand + competitors) and the intended use of context, but adds no new syntax or format details beyond what the schema already provides.

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

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

Clearly states the tool's function: compare AI visibility across multiple entities via probing, ranking, and surfacing most/least recognized. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI-visibility competitive context.

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

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

Provides an explicit use case for competitive AI-marketing audits with a concrete example question. Does not explicitly name alternative tools or exclusion criteria, but the mention of ai_visibility_check implies when a simpler single-probe tool would be used.

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. The description adds valuable behavioral details beyond that: partial failure degradation with sources_failed listing timeout sources, and a specific latency caveat (5-30s for first bundlephobia measurement). This level of transparency is excellent and not contradicted by 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 and front-loaded. The first sentence captures the core purpose, the second gives usage context, the third enumerates the return payload, and the fourth covers limitations and failure handling. Every sentence earns its place with no redundant fluff, making it appropriately sized for a composite tool.

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

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

For a tool with a non-trivial output (summary block, per-advisory detail, links, alternative versions) and no output schema, the description adequately enumerates the key return fields. It also covers ecosystem scope, fallback behavior, and latency expectations. Given the tool's complexity, this provides a complete picture for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the description doesn't need to repeat parameter definitions. Both parameters ('package' and 'version') are already well-described in the schema (including scoped package acceptance and default version behavior). The description adds no further parameter-level semantics, hitting 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 it's a composite check for 'should I add this npm package' combining deps.dev and bundlephobia data. It uses a specific verb ('scan') and resource ('dependency'), and explicitly differentiates from other ecosystem-specific tools by noting NPM-only in v1 and pointing to deps.dev:version for other ecosystems.

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 triggers are provided ('Use whenever an agent asks “is X safe / popular / small” or “what does adding lodash cost me”'). It also gives clear exclusion guidance: NPM only in v1, with alternatives for PyPI/Maven/Cargo/Go. This distinguishes when to use this tool vs. a more direct deps.dev:version fallback.

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 is read-only, idempotent, and non-destructive. The description adds useful behavioral context: it returns name, summary, record_count, owner/org, and a Feature Service URL, and clarifies the data scope (Berks County open GIS). No contradictions.

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

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

Two well-structured sentences: the first states the core purpose, the second details the return payload and the next logical action. Every sentence earns its place without fluff or redundancy.

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

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

With no output schema, the description compensates by enumerating return fields (name, summary, record_count, owner/org, url) and suggesting how to use the url. It is complete enough for a straightforward search tool, though edge cases like empty results or pagination are not discussed.

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

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

All three parameters (query, limit, org_id) have descriptions in the schema, giving 100% coverage. The description reinforces the 'keyword search' aspect of the query parameter but does not add meaning beyond the schema examples. 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 uses a specific verb ('Search'), names the resource ('Berks County GIS open geospatial datasets'), and scopes it by keyword. It also distinguishes itself from siblings by listing return fields and explicitly pointing to query_layer / layer_info as downstream 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 clearly states when to use this tool (searching datasets by keyword) and gives concrete next-step guidance (pass the returned url to query_layer or layer_info). It lacks explicit 'when not to use' exclusions, but the context is strong 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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations: it explains the embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and the 200K character cap with truncation flagging. 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 well-structured and front-loaded: the first sentence states the core purpose, the second gives usage context, and the third explains technical implementation and limits. Every sentence earns its place, with no fluff or repetition. It is concise yet information-dense.

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

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

For a tool with no output schema, the description is remarkably complete. It explains the return format (passages with character offsets and similarity scores), the use case, pairing with a sibling tool, algorithmic details, and the input size limit with truncation behavior. This gives an agent everything needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description adds meaning by explaining the purpose of the 'text' parameter (pre-fetched record, too big for prompt), the query parameter with examples, and the behavior of 'limit' (top-N). It also adds the truncation behavior for 'text', which enriches the schema's 'max ~200K chars' note.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record' and outlines the inputs (pre-fetched text + natural-language query) and outputs (top-N passages with character offsets and similarity scores). It also differentiates from siblings by emphasizing 'inside a fetched record' and referencing ask_pipeworx_grounded for grounding workflows.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also names a pairing/alternative (ask_pipeworx_grounded) and how to combine them, making it clear when this tool is the right choice.

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=false, idempotentHint=true), the description adds auth requirements (OAuth only), return value, the always-on feed, SMS verification and 10/day cap. These are meaningful behavioral traits not visible in structured fields.

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

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

Although long, it is dense and well-organized: purpose, auth, types, then delivery. Every sentence provides necessary context, and the most important info is front-loaded.

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

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

Covers types, auth, return, feed/email/sms. It omits webhook (present in schema) and two enum types (patent_grant, clinical_trial) which are in the schema. The schema fills these gaps, but the omission is a minor completeness issue.

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 semantic value with examples like 'items:["5.02"] = officer change' and 'params:{topic:"fed"}', clarifying how to construct valid params beyond the schema's dry examples.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the new subscription id. This clearly distinguishes it from siblings like list_subscriptions and unsubscribe, using a specific verb and resource.

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

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

It states prerequisites ('Requires a Pipeworx OAuth account'), explains types and delivery channels, and gives context like 'feed (always on — pull via recent_alerts...)'. It does not explicitly name alternatives, but the guidance is strong enough for an agent to know when to use it.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context: results are drawn from the live catalog of thousands of tools, are category-bucketed, and include exact tool+argument shapes. 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 a single dense paragraph that starts with example user questions (front-loading intent) and then explains the tool. It is longer than strictly necessary but every sentence contributes. Could be tightened slightly without losing value.

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

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

With no output schema, the description fully covers the return format (category-bucketed example questions with tool+argument shapes), invocation patterns (no args vs topic), and use cases. It is complete for an onboarding/discovery tool.

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

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

Schema description already covers the `topic` parameter with the full list of options and the behavior when omitted. The description merely repeats examples already in the schema, adding no new semantic information, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shape, positioning it as the onboarding entry point. It distinguishes itself from sibling tools by naming the meta-tools it teaches (ask_pipeworx, entity_profile, compare_entities) and by saying 'Use this FIRST'.

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 tells the agent when to use this: '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 when to call with no arguments versus a `topic`, which gives clear usage context.

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

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

Beyond annotations, the description discloses that the row is deactivated (not deleted), ownership restrictions, and that historical events remain available via recent_alerts. This adds meaningful behavioral context beyond the readOnlyHint/destructiveHint/idempotentHint flags.

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, action-first, no wasted words. The deactivation detail and ownership note are concise yet informative. Structure is easy to scan and front-loaded with the core action.

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

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

For a one-parameter tool with no output schema, the description is fully sufficient. It explains the effect, ownership restrictions, and post-cancellation behavior. Nothing critical is missing.

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

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

Schema already documents 'id' as a UUID returned by subscribe (100% coverage). The description adds the ownership constraint ('you can only cancel your own subscriptions'), which is a useful semantic on top of the schema. While minimal, it goes beyond the schema.

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

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

Description starts with a specific verb+resource: 'Cancel a subscription by id.' It clearly identifies the action and object, and the title 'Unsubscribe from Alerts' reinforces the domain. This distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

The description implies its use case (cancelling a subscription) and adds an important constraint (ownership is enforced). It does not explicitly name alternatives or state when not to use, but the purpose is clear enough without ambiguity.

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

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

The description provides rich behavioral detail beyond the annotations: it distinguishes could_not_verify (verification failure, not evidence) from unsupported (no source cover), warns against showing could_not_verify as evidence, and explains the two execution pipelines. It also mentions the verification_error structure. This complements the readOnly/idempotent hints 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?

Although lengthy, the description is well-structured: triggering phrases, scope, pipeline routing, return values, and a highlighted caller trap. Every sentence adds substantive guidance, and the use of separators and 'IMPORTANT' keeps it scannable. The length is justified by the tool's complexity.

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

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

With no output schema, the description fully specifies the return format (verdict enum, grounded value with pipeworx:// citation, reasoning), explains failure modes (could_not_verify vs unsupported), and clarifies the efficiency benefit over sequential calls. This is complete given the tool's complexity and the annotation context.

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

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

The input schema already has 100% coverage, documenting both claim and tolerance_pct with examples and defaults. The description does not add parameter-level meaning beyond the schema, but the baseline of 3 applies given the schema's completeness.

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

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

The description opens with natural-language invocation examples and states the core purpose: 'natural-language claim verification against authoritative sources.' It clearly distinguishes the SEC EDGAR fast path for financial claims from the grounded pipeline for all other claims, and positions the tool as a replacement for multi-step sequential calls, setting it apart from sibling tools.

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

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

Explicitly states the usage condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes internal routing rules for financial vs. other claims. However, it does not explicitly name alternatives like ask_pipeworx_grounded or compare_entities, so the differentiation from siblings is implicit rather than a direct 'when not to use' statement.

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