Arcgis Lacounty

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds meaningful behavioral context beyond annotations: the default free model, the 'BYO key' cost implication where 'you pay Anthropic directly for those calls,' and the pass-through to api.anthropic.com. It does not mention rate limits, but with annotations covering the safety profile, this is solid.

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 function, followed by model options and use cases. Every sentence earns its place with no redundant filler or repetition of schema details.

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

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

With no output schema, the description explains the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'), covers default parameter behavior, and lists use cases. This is complete for a read-only tool with good annotations and 100% schema coverage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model behavior ('Default model is Workers AI Llama-3.3-70b (free)') and the cost implication of the _apiKey parameter, which the schema does not convey.

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 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' which clearly states a specific verb, resource, and output. It distinguishes the tool from siblings like scan_competitor_ai_presence by focusing on arbitrary entities and topics, not just competitors.

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

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

The description explicitly states 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' providing clear use contexts. However, it does not exclude any alternatives or reference sibling tools, so it misses the highest bar of explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavior beyond this: it routes to a dynamic collection of tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and notes it works on every tier with 'one fast call'. It does not contradict annotations, but it doesn't elaborate on failure modes or rate limits, so a slight deduction is warranted.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and is information-dense without fluff. It is a single paragraph, but it packs multiple pieces of guidance (purpose, usage, examples, alternatives) that all earn their place. It is slightly longer than strictly necessary because some phrases like 'works on every tier, one fast call' are nice-to-have rather than essential, so a 4 is appropriate.

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 as a router to over 5,500 tools, and the absence of an output schema, the description provides comprehensive context: it explains coverage, citations, examples, when to escalate, and even addresses breaking-news. This fully prepares an agent to select and invoke the tool correctly without needing more details.

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

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

Schema coverage is 100% with 'question' described as 'Your question or request in natural language' plus aliases documented. The description's examples ('current US unemployment rate', 'Apple's latest 10-K') reinforce what a good query looks like, but they largely overlap with the schema's own examples. The description does not add new parameter-level semantics beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('ask', 'routes', 'returns') and clearly identifies the resource: a tool that answers factual questions via 5,501 tools across 1,441 sources, returning structured answers with stable pipeworx:// citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them as alternatives.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', 'current'. It also clearly states when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'), and even covers breaking-news use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable context beyond these: beta status, live candidate testing, the fact that it currently matches ask_pipeworx exactly, and that results are compared for merge decisions. This goes beyond annotation coverage.

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

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

Four sentences, front-loaded with core identity, followed by current state, usage guidance, and a clarification about fallback. Every sentence earns its place; 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?

Given the tool's complexity, the description covers what it is, its relationship to ask_pipeworx, when to use it, current behavior, and an important nuance about fallback. Output schema is absent but response shape is referenced by stating it's identical to ask_pipeworx. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, enumerating all six params as aliases for question. The description adds no extra parameter-specific meaning beyond saying 'same arguments' as ask_pipeworx, which is a cross-reference but not a semantic detail. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router handling 5,501 tools with the same arguments and response shape. It explicitly distinguishes itself from the stable ask_pipeworx and the grounded variant by noting its experimental routing improvements.

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

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

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It also clarifies current state ('No candidate is active right now') and that it is a fully functional router, not a 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 readOnly and safe, but description adds rich behavioral details: same routing as ask_pipeworx, extraction limited to tool result, specific success/refusal response shapes, and refusal reason taxonomy. This goes far beyond annotation hints and reveals exactly how the tool behaves.

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

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

The description is well-structured and front-loaded with the core purpose, then flows into mechanism, output, usage, and cost trade-off. Every sentence contributes distinct information without redundancy or bloat.

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

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

For a tool with one real parameter and no output schema, the description fully compensates by specifying return fields, refusal reasons, routing details, and cost trade-off. It covers the tool's complexity thoroughly and leaves no critical gap 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% with all parameters being aliases for question. The description does not add parameter-level detail beyond what the schema states, but it does clarify that the question is used for routing and argument filling. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with specific verb and resource. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and refusal mechanism, making its purpose unmistakable.

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

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

Explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups', providing clear when-to-use and when-not-to-use guidance with an explicit 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 mark it read-only and idempotent, but the description adds substantial behavioral detail: parallel fan-out, low-confidence short-circuiting with status 'low_confidence_match', 'market_closed_or_inactive' handling, wide-spread illiquidity flags, and cancellation-rule parsing with EV impact. It transparently warns about resolution-rule risks and blocking behavior.

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

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

The description is long but well-structured with clear headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and each section adds critical operational details. No filler exists, but the length could be trimmed for agents with limited context windows. Still, it earns its length through specificity.

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 comprehensively. It documents response shapes, resolver contract fields, parent event extraction, news fallback fields, safety statuses, and cancellation-rule semantics. It also lists the full classifier taxonomy and includes examples of fan-out for different bet categories, covering edge cases like wide spreads and closed markets.

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 all three parameters with 100% description coverage, including formats and defaults. The tool description reiterates the market input forms but adds no new meaning for parameters. It does provide context for how fan-out works, but that is not directly tied to parameter semantics.

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 action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains the process (resolve, classify, fan out, return evidence packet) and distinguishes from siblings like polymarket_edges or polymarket_arbitrage, which focus on opportunity scanning rather than per-bet research.

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

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

The description explicitly tells when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes blocking behaviors for low-confidence and closed markets, helping the agent decide if the tool is appropriate and how to interpret results.

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, openWorldHint, idempotentHint, destructiveHint), the description discloses data sources (SEC EDGAR/XBRL, FAERS), special handling of off-calendar fiscal years, sorting behavior by primary metric, and output format with pipeworx:// citation URIs. This significantly exceeds the information carried by annotations alone.

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

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

The description is front-loaded with relatable query examples and packs a wealth of information—data sources, fiscal year handling, sorting, output format—into about five sentences. There is no redundancy; every clause contributes to the agent's understanding.

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 tells the agent exactly what to expect: 'paired data + pipeworx:// citation URIs per entity.' It covers both entity types, sorting, and fiscal year correctness, making it complete for the tool's complexity.

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

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

While the schema already covers both parameters (100% coverage), the description enriches their meaning by explaining what each 'type' value retrieves (10-K financials vs adverse-event counts) and clarifying 'values' with ticker/CIK and drug name examples. This goes beyond the schema's basic definitions.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides concrete trigger phrases. It distinguishes itself from sequential single-pack lookups by emphasizing 'ALWAYS PREFER' for comparisons, setting it apart from related tools like entity_profile.

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

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

The description gives explicit trigger phrases and states when to use the tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'). However, it does not explicitly mention when NOT to use it or name an alternative tool, missing the full 'when-not/alternatives' criterion.

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?

Goes far beyond annotations by disclosing account requirements, latency (15-60s, up to 90s), parallel decomposition, output structure (findings packet with evidence/confidence/fetched_at/citations), explicit gaps[] for unanswered facets, never-invented guarantee, contradiction detection, and excerpting behavior. No contradiction with readOnly/openWorld/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?

Though lengthy, the description is densely packed with non-redundant, critical information. It is front-loaded with the most actionable caveat ('ACCOUNT REQUIRED') and follows a logical flow: purpose, constraints, alternatives, behavior, and performance. Every sentence earns its place for a tool of this 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?

Without an output schema, the description must explain return values and behavior, and it does thoroughly: findings packet contents, gaps[], contradictions[], hop field, citation_uri resolvability, and expected latency. It also covers prerequisites, depth-level differences, and usage boundaries, making it fully self-contained for an agent.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds value by explaining question type ('Broad/multi-part is fine') and elaborating depth semantics in context (quick/standard/thorough hops, gap recovery, contradictions[]), which enriches the schema enum definitions.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' in ONE call. It explicitly distinguishes from siblings by noting 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also includes account prerequisites and an alternative when not signed in.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds behavioral detail beyond the annotations by specifying that results include names, descriptions, and full input schemas with curated examples, and that each result is 'ready to call directly, no second schema lookup needed.' This is useful, non-obvious context.

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

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

The description is well-structured and efficient: it starts with the core action, lists representative domains, explains the return format, and closes with practical guidance. Each sentence contributes unique value, and the length is appropriate for the tool's discovery 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?

Given its read-only nature, the lack of an output schema, and the richness of the domain list, the description is nearly complete. It explains what is returned and how results are ready for direct invocation. It could mention error behavior or edge cases, but that is a minor gap for a 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 coverage is 100%, so the baseline of 3 applies. The description does not add parameter-level semantics beyond what the schema already provides; however, it does mention the 'top-N' return behavior, which relates to the 'limit' parameter. Overall, the schema carries the burden adequately, so a midrange score is appropriate.

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

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

The description clearly states the action ('Find tools'), the resource ('tools'), and the mechanism ('by describing the data or task'). It enumerates the covered domains and explicitly distinguishes itself from data-retrieval siblings by focusing on tool discovery. The phrase 'Call this FIRST when you have many tools available' reinforces its unique role as an exploratory entry point.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name specific alternative tools to use instead, the context makes the appropriate scenario clear, which justifies a score above the midrange.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds useful behavioral context: fans out across sources, returns specific fields, patents API sunset with soft-fail, GDELT→GNews fallback. This exceeds what annotations alone provide.

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

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

Every sentence carries functional weight: example queries, usage guidance, data sources, return structure, limitations, and fallback behavior. It's long but efficiently organized with semicolons and 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?

Despite no output schema, the description fully enumerates returned fields (cik, recent_filings, fundamentals, patents, news, LEI) and explains the data sources. It also notes limitations and alternatives, making the tool's behavior predictable.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the input format (ticker or CIK, names not supported) but adds no additional parameter semantics beyond the schema.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' and lists example queries. It distinguishes itself from chaining single-source lookups and mentions sibling tools like resolve_entity for names.

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

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

Explicitly says when to use it ('when the user asks for a holistic view') and ALWAYS PREFER over chaining single-pack lookups. Also provides exclusion: names not supported, use resolve_entity first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds usage rationales but no new behavioral details beyond what annotations and the schema provide. It does not contradict annotations, but the value-add is limited.

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 that are direct and informative. The action is front-loaded, and each sentence earns its place: definition, when-to-use, and relationship to sibling tools. 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?

For a single-parameter deletion tool with comprehensive annotations and full schema coverage, the description is complete. It explains purpose, usage context, and related tools without needing to describe return values (no output schema exists). The simple design is fully covered.

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

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

The input schema fully describes the single 'key' parameter with a clear description ('Memory key to delete'). The tool description repeats the concept 'by key' but adds no additional meaning beyond the schema. Baseline 3 is appropriate for 100% schema coverage.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory'), and the mechanism ('by key'). It explicitly differentiates from siblings like 'remember' and 'recall' by focusing on deletion, and the pairing instruction further clarifies its complementary role.

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

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

The description provides explicit when-to-use scenarios: stale context, completed task, or clearing sensitive data. It does not explicitly state when not to use the tool, but the 'Pair with remember and recall' hint gives some context for alternative operations. Slightly below a perfect score due to lack of exclusions.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that it fetches the page, extracts metadata, and emits a specific markdown format, as well as noting the output is a single text blob. This adds behavioral context without contradicting annotations.

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

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

The description is about 60 words, starts with a clear purpose statement, and efficiently covers process, output, and use cases without redundancy.

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

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

Despite lacking an output schema, the description explicitly states the return value ('a single text blob ready to drop at site-root/llms.txt') and outlines the extraction steps, which is sufficient for a simple 2-parameter 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% with both 'url' and 'max_links' already described. The description adds minimal extra meaning by mentioning 'key links' and the standard format, but it doesn't materially enhance the parameter understanding beyond what the schema already provides.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file') with scope ('for any URL'), clearly distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence. It also lists target AI crawlers, making the purpose unambiguous.

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

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

It provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') but does not mention when to avoid using it or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds value by specifying the exact schema components returned (fields, geometry type, count, capabilities), which is additional behavioral context beyond the annotations. No contradiction exists.

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

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

The description is a single, efficiently worded sentence that immediately states the purpose and lists the key outputs. No wasted words, and the structure places the action and resource first, making it easy to scan.

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

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

Given the tool's simplicity (one parameter, no output schema) and strong annotations, the description is nearly complete. It enumerates the return data, which is essential since no output schema exists. It could optionally mention handling of invalid URLs, but this is not critical for a read-only schema tool.

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

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

The input schema provides a complete description of the 'url' parameter (including an example), so schema coverage is 100%. The description simply says 'by url' which adds no new meaning beyond what the schema already provides, aligning with the baseline score of 3.

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

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

The description clearly uses the verb 'Get' with a specific resource ('ArcGIS Feature/Map Service layer's schema') and enumerates the exact returned data: fields, geometry type, record count, and capabilities. This distinguishes it from sibling tools like query_layer, which would be used for data queries, making the purpose unambiguous.

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

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

The description implies clear usage context: when you need schema information for an ArcGIS layer. It does not explicitly state exclusions or alternatives (e.g., 'for data, use query_layer'), but the specificity of the resource and output makes the intended use clear without being misleading.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context beyond annotations by specifying the return fields (id, type, params, etc.) and the default scope ('active subscriptions'). It does not contradict any annotation.

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

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

Two sentences with no fluff. The first sentence states the action and scope; the second lists return fields and usage intent. Front-loaded and every sentence earns its place.

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

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

For a simple list tool with one optional parameter, the description covers purpose, return fields, and usage guidance. Annotations provide safety profile, and no output schema exists but the return fields are explicitly listed. This is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for the only parameter (include_inactive), so the schema fully documents it. The description does not add parameter-level detail beyond mentioning 'active subscriptions,' but the schema already covers the meaning and default behavior. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes from siblings like subscribe and unsubscribe by focusing on the listing/reviewing function. The mention of return fields further clarifies the 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?

Provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to invoke this tool relative to subscribe/unsubscribe, with clear context for both pre-add review and pre-cancel lookup.

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 readOnlyHint=false, so this is a write operation. The description discloses key behaviors: filing returns a claim_token that can be used later, rate-limit '5 per identifier per day,' and that it's free and doesn't count against quota. These go beyond the annotations and set expectations for side effects and limitations.

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 densely packed with necessary instructions and exclusions. It is front-loaded with the core purpose, then logically flows through use cases, boundaries, token mechanics, and rate limits. Every sentence contributes actionable information without redundancy.

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

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

The description is exceptionally complete for a feedback tool. It covers acceptable feedback types, scope boundaries, formatting guidelines, the claim_token lifecycle, rate limiting, and the lack of quota impact. Without an output schema, it still explains expected return behavior (claim_token) and follow-up usage, leaving little ambiguity.

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

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

Schema coverage is 100% with each parameter described, but the description adds meaningful semantics beyond the schema. It explains the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and reinforces how to use the 'type' and 'context' parameters correctly (e.g., describing issues in terms of Pipeworx tools/packs).

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise) and distinguishes it from sibling research or memory tools by emphasizing it's for feedback on Pipeworx tools only.

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

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

The description gives explicit when-to-use guidance ('Use when a tool returns wrong/stale data...') and explicit when-not-to-use guidance, including a clear exclusion for tools from other MCP servers: 'if the tool came from a different MCP server... file it with that server instead.' It also instructs how to frame feedback (in terms of Pipeworx tools/packs, not user prompts).

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. The description adds contextual detail about data provenance (CF analytics-engine), no PII, and caching behavior (5min-1h), which goes beyond the annotations and helps the agent understand freshness and privacy.

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 a clear opening statement, numbered use cases, and a compact note on data provenance and caching. Every sentence contributes value, and the length is appropriate for the information conveyed.

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

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

For a simple tool with one optional parameter and rich annotations, the description is nearly complete. It explains the returned content (top tools, packs, total volume), data source, no PII, and caching. A minor gap is the lack of a detailed response structure, but this does not impede correct invocation.

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

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

The sole parameter 'window' is fully documented in the schema with an enum and detailed semantics about short vs. long windows. The tool description only briefly mentions the window options, adding no new meaning beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a recent window, using a specific verb and resource. It distinguishes itself from siblings by focusing on aggregate trending data rather than individual lookups.

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

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

The description explicitly lists three 'Useful for' scenarios, providing clear context on when to use the tool, such as discovering hot data sources and confirming canonical tools. It does not name alternative tools or explicitly state exclusions, but the use cases are 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?

While annotations already declare readOnly, openWorld, idempotent, and non-destructive, the description adds valuable behavioral context: the semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder fraction >20% returns null), FILL CHECK logic with realizable edge ≤0 warning, and the fact that it uses live CLOB depth. 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 dense yet every sentence contributes useful information: mode specifics, thresholds, filters, output structure, and fill-check behavior. It is front-loaded with the core purpose, and while lengthy, the complexity of the tool justifies the detail. There is no fluff or redundancy.

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

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

With no output schema, the description thoroughly covers return values: opportunities[] fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check details. It also explains edge cases (thin legs, skipped_low_similarity, placeholder filters) and provides safety warnings (do not trade if realizable_edge_pp ≤ 0), making it fully self-contained for an AI agent.

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

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

The input schema already provides full descriptions of the event and topic parameters, but the tool description exceeds this by offering concrete examples ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), explaining mode-specific behavior, and detailing how each parameter influences the scan. This significantly enriches the schema's 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 clearly states the tool's purpose with a specific verb and resource: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It distinguishes itself from sibling tools like polymarket_fill_risk by noting that custom sizing should use that tool, and it outlines specific modes (trending, event, topic) that add clarity.

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: "Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan." It also recommends the event mode for specific markets and mentions the alternative for custom sizing (polymarket_fill_risk), giving clear context and exclusions.

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

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

Beyond the annotations (read-only, idempotent), the description discloses critical behavioral details: output structure (by_segment, fed_candidates, _diagnostics), caching behavior ('Cached 1h'), potential for empty segments and why, and the limitation of Fed signals ('1m-T vs EFFR signal is unreliable'). This transparency exceeds what annotations provide.

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

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

The description is well-structured with labeled sections, but it is verbose, containing many implementation-specific details (e.g., specific model parameters like 'tennis 1.02, soccer 1.10'). While every section conveys useful information, the length borders on over-specification, and some phrases could be tightened without losing value.

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

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

Given the absence of an output schema, the description compensates by thoroughly explaining the response top-level keys, per-opportunity fields, and diagnostic details. It also covers edge cases (why segments might be empty, 24h-move warnings) and the impact of knobs, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds value by grouping parameters under 'TRADEABLE-EDGE KNOBS' and explaining their strategic purpose (e.g., min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable'), which enriches understanding beyond individual 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines its purpose as a discovery tool for betting opportunities, contrasting with alternatives by noting agents can discover opportunities 'without paging hundreds of markets.' This distinguishes it from sibling tools like polymarket_arbitrage or 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 clear context: built for 'what should I bet on today' and describes when to use it for opportunity discovery. It also details tradeable-edge knobs and filters, giving practical guidance on how to tailor calls. However, it does not explicitly state when to use alternatives or provide exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes far beyond by detailing response structure (tracked, expired, snapshot_dates), the meaning of trend classifications, how decay is computed, snapshot gap semantics, the 60-day TTL bound, and that decay uses daily closes rather than intraday data. This is rich, non-contradictory behavioral disclosure.

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

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

The description is long but well-structured into Args, RESPONSE, and LIMITS sections, with each paragraph serving a distinct purpose. Some colorful asides (e.g., 'competition clock') add readability, though a bit more trimming could improve conciseness 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 there is no output schema, the description fully compensates by explaining the exact response keys, their meanings, edge cases (missing snapshots, expired opportunities), and historical depth limitations. It is complete for an agent to invoke the tool and interpret results correctly.

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

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

The input schema already covers 100% of parameters with descriptions for days and window, so the baseline is 3. The description adds minor context like 'snapshot family' for window and confirms defaults, but it does not materially augment the schema descriptions.

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

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

The description clearly defines the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, with a specific question it answers: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay 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?

The description gives a clear use case: when you need to know edge age and whether it is decaying, with meaningful context about why a fresh vs. old edge matters. It does not explicitly name an alternative (e.g., polymarket_edges) or provide when-not-to-use guidance, but the intended use is clear and the LIMITS section offers practical exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds deep behavioral detail: walks the ladder, returns verdict clean|degraded|cannot_fill, warns about thin_legs and forced_directional_risk. It does not contradict annotations and meaningfully extends them by highlighting the dominant loss mode in real arb-bot P&L.

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

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

The description is dense and structured with clear sections (SINGLE-MARKET, BASKET) and front-loaded definition. Every sentence carries information, but the paragraph is long and might overwhelm an agent scanning for quick details. Still, the complexity justifies the length, so it earns a solid 4.

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

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

Despite having no output schema, the description enumerates all returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like partial fills and unhedged risk, making it fully complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds crucial semantic distinctions: size_usd is 'max spend on buys, target proceeds on sells' in single-market vs 'settlement notional' in basket; side behavior differs (auto-detect in basket based on partition sum). This goes beyond schema field descriptions and clarifies the mode-dependent interplay.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk check, and it defines both single-market and basket modes with distinct outputs.

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

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

The description gives explicit usage instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (partial fills convert an arb into unhedged directional position), providing strong context and alternative differentiation.

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?

With annotations already marking read-only/idempotent, the description adds substantial behavioral context: safety fields (compatibility_warning triggers), temporal alignment semantics, skipped cross-type/subtype counters, and the important caveat that non-equivalent bet shapes mean no arb. It explains what happens in edge cases and why, far beyond the annotation hints. No contradiction with annotations.

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

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

The description is long but well-structured with clear markers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence carries useful information; however, the density and length are substantial. It earns a 4 rather than 5 because it is somewhat verbose, though justifiably so 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?

For a complex tool with no output schema, the description is remarkably complete: it covers input modes, response fields (raw probabilities, spread[].top_spreads_pp), compatibility warning conditions, temporal alignment, and practical caveats. An agent could confidently invoke this tool across edge cases based on the description alone.

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 covers all 3 parameters with descriptions, the tool description adds meaningful semantics: the 'topic' mode with pre-mapped shortcuts, how explicit ticker/slug overrides work, and what the response contains (leg-by-leg prices, spreads, safety fields). This goes above schema basics and helps the agent understand parameter interaction.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by emphasizing the cross-venue, same-question scope. The purpose is immediately evident and precise.

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 details two usage modes (topic shortcuts vs explicit ticker/slug pairing) and explains when each is appropriate. It also warns that most pre-mapped topics currently return compatibility_warning, effectively telling agents when NOT to rely on the tool's convenience mode. It doesn't name sibling alternatives as substitutes, but the mode guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by specifying that it returns 'attribute rows (and geometry)' and supports 'SQL-like' querying, plus a sampling tip. It does not disclose pagination limits beyond offset/limit or rate limits, but with annotations present, this is sufficient.

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

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

The description is two sentences, front-loaded with the core purpose, and includes a practical usage tip. Every sentence earns its place with no redundancy or filler.

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

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

For a query tool with 6 parameters and no output schema, the description provides essential context: what it queries (ArcGIS layer by URL), what it returns (attribute rows and geometry), and a sampling strategy. The link to search_datasets is helpful. It lacks explicit mention of response format, but the return description is adequate given 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 description coverage is 100% (all 6 parameters have descriptions and examples). The description repeats parameter names (where, out_fields, order_by, limit, offset) without adding substantial new meaning. The sampling tip is useful but not a semantic explanation of individual parameters, 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's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It specifies the resource (Feature/Map Service layer) and the action (query), and distinguishes it from siblings like layer_info (which likely provides metadata) and search_datasets (which finds datasets).

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

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

The description provides clear context: use this tool to query a layer by URL, and implies it follows search_datasets. It also includes a practical tip for sampling ('where="1=1" + out_fields="*"'). However, it does not explicitly state when not to use it or mention alternatives like search_within or layer_info.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: scoping to user identifier, and the omission behavior for listing all keys. 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?

Three sentences with no redundancy. The first sentence states the core action, the second provides usage rationale, and the third covers scoping and sibling pairing. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains what, when, and how to use, plus scoping and relationships to remember/forget. No missing critical 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 coverage is 100%, so the schema documents the 'key' parameter well. The description adds semantic value by explaining the key is 'previously saved via remember' and providing concrete examples (target ticker, address, research notes), which enriches understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list), identifies the resource (saved memory), and distinguishes from sibling tools by explicitly pairing with remember and forget.

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

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

The description provides clear when-to-use context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also implies alternatives by referencing remember and forget, though it doesn't explicitly state exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral details: mark_read:true mutates read state, the feed is persistent, and the return payload includes source, citation_uri, and raw event. 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?

Three sentences, front-loaded with the main action, then return contents and filtering, then mark_read behavior and alternative access. Every sentence adds value with no redundancy or fluff.

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

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

Combined with comprehensive annotations and full schema coverage, the description completes the picture: what is returned, how filtering works, side effects, and alternative access for non-agent use. Adequate for a read-oriented alert feed tool.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description enriches beyond this by giving an example type ('sec_8k'), specifying ISO timestamp for 'since', and explaining the effect of mark_read. It doesn't detail limit/unread_only, but the schema covers them.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It differentiates from siblings like list_subscriptions (managing subscriptions) and recent_changes (general updates) by focusing on fired alerts, and adds detail about return contents.

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:'Polls work fine' and 'the same feed is also at GET registry.pipeworx.io/alerts.json' tells the agent when to use the tool vs. an HTTP endpoint. Suggests filtering by type/since for targeted usage, though it does not explicitly name alternative tools for alert retrieval.

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, openWorld, idempotent), the description discloses key behavioral traits: fan-out to multiple sources, fallback logic, soft-failure of the USPTO feed due to API sunset, and the return structure (changes[], total_changes, citation URIs). This gives the agent a realistic model of what the tool will do.

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

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

The description is longer than ideal but well-structured: it opens with natural-language examples, states the core function, enumerates sources, explains input syntax, specifies return format, and closes with an alternative tool. Every section serves a purpose, though the list of example queries could be trimmed without losing essential meaning.

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

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

Despite the lack of an output schema, the description clearly states the return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers edge cases like GNews fallback and USPTO soft-fail, and differentiates from entity_profile. This is complete for a tool with this complexity.

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

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

Schema coverage is 100%, so the parameters are already fully described. The description adds only a minor usage recommendation for 'since' ('Use "30d" or "1m" for typical monitoring') and restates the ISO/relative shorthand that the schema already provides. This does not significantly expand parameter understanding 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 defines the tool as a change feed for a company over a recent time window, with specific verbs like 'change feed' and 'Fans out to'. It distinguishes itself from sibling entity_profile by explicitly naming the alternative and contrasting the use case (dynamic changes vs. static profile).

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

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

The description provides explicit when-to-use guidance through example natural-language queries, and explicitly says 'Use entity_profile instead when you want the static profile...'. It also offers practical advice such as 'Use "30d" or "1m" for typical monitoring' and explains the fallback behavior (GDELT preferred, GNews when rate-limited).

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 readOnlyHint=false and idempotentHint=true. The description adds valuable behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This discloses persistence and scoping details that annotations don't cover, though it doesn't mention overwrite semantics for duplicate keys.

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 only three sentences, front-loaded with the action, and every sentence serves a purpose: the main verb, the use case, and persistence behavior plus sibling tools. No wasted words or redundant information.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully covers purpose, when to use, persistence semantics, and related tools. It doesn't need to explain return values since a simple confirmation is implicitly expected, and the retention policy addresses the most important contextual concern.

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 clear descriptions for key and value. The description supplements this by providing examples of typical keys (ticker, address, preference) and values (findings, addresses, preferences, notes), which helps the agent infer appropriate parameter usage beyond bare schema definitions.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete,' making it obvious that remember is for saving while recall and forget handle retrieval and deletion.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and gives concrete examples like 'a resolved ticker, a target address, a user preference.' It also names complementary tools (recall, forget), offering clear alternatives for related actions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: internal cascading through multiple endpoints, auto-disambiguation for companies, and citation URIs returned. No contradictions.

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

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

The description is moderately sized and contains relevant information: examples, supported types, internal behavior, and citations. It is not overly verbose, though the opening could be slightly more front-loaded with the core purpose rather than examples first.

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

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

With no output schema, the description adequately explains return values for both entity types, including citation URIs and auto-disambiguation. It also mentions the internal lookup cascade, giving context for behavior. It does not cover error cases, but for a simple lookup tool it is largely complete.

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

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

Schema coverage is 100%, with both parameters well-described and examples provided. The tool description repeats the parameter details and adds return-value context, but does not significantly extend the schema's parameter semantics. Baseline of 3 is appropriate.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with a specific verb and resource. It provides example queries and supported types (company, drug), and distinguishes itself from sibling tools by positioning it as the first step when an ID is needed.

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 FIRST whenever you have a name but need an ID,' giving a clear use case. It also notes it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention alternatives or when not to use it, though the guidance is implicitly clear.

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

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

The description discloses that the tool probes each entity using the sibling tool ai_visibility_check and returns a ranked list with score, confidence, and signal density. This adds behavioral context beyond the annotations (readOnly, idempotent, etc.), which already indicate safety but do not explain the delegation to another tool or output contents.

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

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

The description is concise and front-loaded with the core purpose in the first sentence. Each subsequent sentence earns its place by explaining the mechanism, use case, and return format without redundancy or fluff.

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

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

The description covers the key aspects for a tool with no output schema: it states what the tool does, how it works (via ai_visibility_check), what it returns (ranked list, score, confidence, signal density), and when to use it. It does not mention edge cases or error behavior, but for the complexity of this tool, the description 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 for all four parameters, including detailed descriptions of entities, models, _apiKey, and context. The description adds only a paraphrase ('your brand + N competitors') that echoes the schema's entity description, providing no new semantic meaning beyond what the schema already contains. Thus, the baseline of 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It names the specific resource (i.e., AI visibility) and the verb 'compare', and distinguishes itself from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic) by focusing on AI presence.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an illustrative question ('does Claude know about us as well as our competitors?'). It does not explicitly mention alternatives or when not to use, but the context is well-defined, satisfying the 'clear context, no exclusions' level.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s with sources_failed indicating timeouts. This goes beyond annotations.

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

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

The description is dense yet every sentence earns its place: purpose, sources, use case, output contents, ecosystem limitations, and failure modes. It's front-loaded with the primary intent and remains readable despite its length.

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

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

With no output schema, the description fully enumerates the return block fields, per-advisory details, links, alternative versions, and failure behavior. Given the composite complexity and multiple sources, 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 covers both parameters (package name and optional version) with 100% coverage. The description adds no extra parameter nuance; it only references the version's default behavior which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states it's a composite 'should I add this npm package' check fanning out across deps.dev and bundlephobia. The verb 'check' plus the use-case framing ('is X safe / popular / small') makes the tool's purpose unambiguous and distinct from siblings.

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

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

Explicitly provides when to use: whenever an agent asks about safety/popularity/size or cost of adding a package. It also states what NOT to use it for: non-NPM ecosystems fall under deps.dev:version directly, steering alternative tool 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds behavioral context by detailing the return fields and the Feature Service URL, enabling the agent to understand how the output feeds into other tools. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the tool's purpose, then immediately states the return value and downstream usage. Every sentence earns its place 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?

Given 3 optional parameters and no output schema, the description is comprehensive: it defines the search domain (LA County GIS), lists example topics, specifies the return fields (name, summary, record_count, owner/org, url), and explains how to use the url with sibling tools. This fully covers the tool's role and integration.

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

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

The input schema provides 100% coverage for all three parameters (query, limit, org_id) with descriptions. The tool description does not add additional parameter semantics beyond the schema, so it stays at the baseline for high schema coverage.

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

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

The description uses a specific verb ('Search'), specifies the resource ('Los Angeles County GIS open geospatial datasets'), and provides concrete examples (parcels, parks). It also distinguishes from sibling tools by explicitly directing the returned URL to query_layer/layer_info, clarifying its role as a discovery tool.

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

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

It clearly states when to use this tool (to find datasets by keyword) and provides a clear downstream workflow ('pass that url to query_layer / layer_info'). While it doesn't explicitly exclude other search tools, the context makes the intended usage unambiguous.

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

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

Annotations already mark it read-only and idempotent, but the description goes well beyond: it discloses the embedding model (BGE-base-en), windowing (500-char overlapping), distance metric (cosine), the 200K char cap with truncation and flagging, and that passages include character offsets for quote verification. This rich behavioral detail is exactly what an agent needs to predict results.

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

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

Every sentence earns its place: the first defines the action, the second covers when to use, the third pairs with a sibling, and the last provides technical constraints. Despite its density, it is tightly written with no filler, front-loading the most critical information.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: passages, offsets, and similarity scores. It also covers edge cases (truncation flag) and algorithm details, making the tool's behavior fully predictable for an agent that may need to act on the results.

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

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

Schema coverage is 100%, so parameters are documented, but the description adds meaningful context: 'text you already pulled' clarifies the resource type, 'natural-language query' and examples illustrate query usage, and 'top-N passages' reinforces the limit parameter. It also explains how parameters interact with the search mechanism, adding value beyond the schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' using a specific verb and resource that clearly defines the tool's function. It contrasts with sibling tools by noting it returns passages with offsets rather than whole-document answers, and explicitly pairs with ask_pipeworx_grounded, making its unique role unmistakable.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt,' and explains how it saves context. It also provides a usage workflow with ask_pipeworx_grounded, effectively steering the agent to the right alternative for grounding over relevant passages.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, etc.), the description discloses key behaviors: persistence requires OAuth (anonymous/BYO cannot persist), returns the new subscription id, the feed is always-on and can be pulled via recent_alerts or a public endpoint, and SMS has a 10/day cap. It also hints at side effects (creating a subscription) without contradicting annotations.

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

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

The description is compact and front-loaded with the main purpose. It packs in multiple subscriptions types and delivery methods without excess verbosity. Each sentence contributes useful detail, though the density of examples makes it slightly long. It is well-structured for the complexity of the tool.

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

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

Given the tool's complexity (3 parameters, nested objects, 5 subscription types, multiple delivery channels), the description is complete. It covers authentication, return value, supported types, delivery semantics, and constraints. Even without an output schema, it specifies that the tool returns the new subscription id, which is 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?

Schema description coverage is 100%, and the schema already documents all parameters, including nested examples and constraints. The description repeats the supported types and delivery options but adds little new semantic information beyond summarizing the schema. It does not clarify any parameter format that is absent from the schema, so it earns the baseline score of 3.

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

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

The description clearly states a specific action ('Create a proactive monitoring subscription'), names the resource ('live-data event stream'), and explicitly distinguishes from siblings by noting it returns a new subscription id. It lists concrete subscription types, making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool (e.g., to subscribe to monitored event streams) and includes explicit prerequisites (OAuth account, verified phone for SMS), but does not explicitly contrast with alternatives like list_subscriptions or recent_alerts. It gives boundary conditions (10/day cap, always-on feed) but no direct 'use X instead' 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 set readOnly/openWorld/idempotent/non-destructive, and the description adds behavioral context: it returns category-bucketed example questions with exact tool+argument shape, and it is drawn from a live catalog. It also explains the no-args vs topic 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 longer than one sentence but every clause adds value: usage triggers, parameter behavior, and output nature. It is front-loaded with example phrasings and ends with concrete instructions, though it could be slightly tightened without loss.

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 covers return contents (category buckets, example questions, tool+argument shape), invocation modes, and topic values. Combined with annotations, this gives an agent everything needed to decide when and how to call 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 covers topic with 100% coverage, so baseline is 3. The description adds meaning by giving examples ('finance', 'pharma', 'betting'), explaining that omitting returns a cross-category spread, and emphasizing that each result includes the tool+argument shape needed to ask. This elevates it above baseline.

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

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

The description clearly identifies suggest_questions as the onboarding entry point for a freshly connected agent, using specific verbs like 'Returns category-bucketed example questions' and 'Call with no arguments...'. It also distinguishes from sibling tools by positioning it as the FIRST tool to use and explicitly references meta-tools such as ask_pipeworx and entity_profile.

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

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

It provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It explains when to omit vs pass topic, and names related tools (ask_pipeworx, entity_profile, compare_entities), giving clear context for selection.

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

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

Annotations already indicate non-read-only, open-world, idempotent, and non-destructive. The description adds valuable context: ownership is enforced, and the row is deactivated (not deleted) preserving historical events. This enriches beyond annotations without contradiction.

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

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

Two concise sentences, front-loaded with the primary action. Every sentence adds value: the first states the action, the second covers ownership and the non-destructive behavior.

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

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

For a simple one-parameter tool with annotations and no output schema, the description explains the core operation, side effects (deactivation vs deletion), and the ownership constraint. It is complete enough for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage for the 'id' parameter, describing it as a uuid returned by subscribe. The description merely says 'by id' without adding further semantic detail, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (cancel) and the resource (subscription by id). It differentiates from sibling tools like subscribe and list_subscriptions by focusing on cancellation.

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

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

It clearly implies when to use (to cancel a subscription) and adds context about ownership constraints and the availability of historical events via recent_alerts. However, it doesn't explicitly mention alternatives or when not to use, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: the structured SEC EDGAR + XBRL route vs the grounded fallback, exact percent-delta math, tolerance override semantics, and the exact verdict taxonomy plus citation and reasoning in the return. No contradiction with annotations.

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

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

The description is dense and front-loaded with user-intent examples, making the tool immediately identifiable. Each sentence earns its place, but it is somewhat long with the query-phrase list and the 'Replaces 4–6 sequential calls' note; still, it is well-structured and avoids fluff.

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

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

With only 2 params, a rich schema, and full annotations, the description fully covers what the tool does, how it routes claims, what it returns (verdict, value, citation, reasoning), and how tolerance works. The absence of an output schema is compensated by a clear return contract. No significant gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description supplements the schema by explaining the percent-delta math and reinforcing the tolerance override behavior, and gives different example claims than the schema. However, most parameter meaning is already in the schema, so the additive value is moderate.

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

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

The description begins with concrete query patterns and a precise verb-resource pair: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this tool as the fact-check/verify tool from siblings like ask_pipeworx or compare_entities, and explains the two internal paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for everything else).

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

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

Explicit guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes the company-financial fast path from the general grounded pipeline, and notes the tool replaces multiple sequential calls, giving context for when it should be preferred over chained simpler calls.

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