Arcgis Austin

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

Annotations already indicate read-only, idempotent behavior. The description adds valuable context: default model 'Workers AI Llama-3.3-70b (free)', the BYO key cost implication for Anthropic, and the return format. 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?

Three sentences: main purpose, default/key behavior, return format, and use cases. Front-loaded with the core function, every sentence earns its place.

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

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

Despite lacking an output schema, the description specifies the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view.' Combined with annotations and full parameter docs, the tool is fully specified for correct invocation.

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

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

Schema covers all four parameters with descriptions. The description enriches parameter semantics by explaining that `_apiKey` is only needed when including 'anthropic' in models and that users pay Anthropic directly, plus the default model behavior.

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: 'Probe one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' This specific verb+resource combination distinguishes it from sibling tools like ask_pipeworx, which focus on asking questions rather than assessing visibility.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly name alternative tools or specify when not to use, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is an internal router (one of 5,710 tools), it auto-fills arguments, and it returns answers with stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and is information-dense, but it trails into redundancy: the trigger-phrase sentence repeats near the end and 'even if web search could also answer it' appears multiple times within a short span. A tighter single pass would make it a 5.

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

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

For a read-only tool with a single required string parameter, the description is nearly complete: it covers when to use it, what to pass, the internal routing/fill behavior, and the return format (structured answer with citation URIs), with no output schema to lean on. The only real gap is not addressing the distinct use cases of its sibling variants.

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

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

Schema coverage is 100%, so the baseline is 3 — the schema already documents question and its five aliases as natural-language input. The description adds value by telling the agent it only needs to supply the question because the tool 'fills arguments' internally, and the six example queries demonstrate the expected input form and scope.

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 mechanism: 'Routes the question to the right one of 5,710 tools across 1494 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is a clear verb+resource definition that distinguishes the tool from web search and from siblings like validate_claim or search_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?

Extremely explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', a long domain list, trigger phrases ('what is', 'look up', 'find', 'get the latest'), and six concrete example queries, plus 'START HERE for most questions'. However, it never names any sibling alternative or states when-not-to-use it — notably it does not differentiate from ask_pipeworx_grounded, ask_pipeworx_beta, or deep_research, so a 5 is not earned.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable live-state context: candidate routing improvements are only enabled during tests, none is currently active, and the tool currently matches ask_pipeworx exactly. The statement 'Falls back to nothing — this IS a full working router' also prevents a common beta-tool misconception.

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

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

The description is compact but information-dense: identity, current status, usage guidance, and beta-safety clarification each get their own sentence. No sentence is wasted, and the most important fact (beta variant of ask_pipeworx) is front-loaded.

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

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

Despite having no output schema, the description references the exact response-shape contract via ask_pipeworx and clarifies arguments and current behavior. Combined with the annotations and sibling context, an agent has enough to invoke the tool correctly and understand what to expect.

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

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

Schema coverage is 100%: all six parameters are documented as aliases for question. The description says 'same arguments as ask_pipeworx' but does not add per-parameter meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, an identical universal router with the same 5,710 tools, arguments, and response shape. It also explicitly flags the experimental edge, which distinguishes it from the stable ask_pipeworx sibling.

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

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

It directly instructs when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names ask_pipeworx as the stable comparator and explains that results are compared against it, giving an agent a clear selection 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?

Annotations cover read-only/idempotent/non-destructive safety, but the description adds substantial behavioral context beyond them: the exact success return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, the full refusal enum (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the routing scale (5,710 tools across 1494 sources), and the extra-LLM-call cost. No contradiction with annotations — readOnlyHint='true' matches the read/fetch framing.

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?

Front-loaded with the key differentiator, then flows logically: mechanism, success return, refusal return, usage guidance, cost comparison. Dense but every sentence earns its place; the detail about 5,710/1494 sources is mildly ornamental but conveys scale. Not overlong given the complexity it documents.

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 carries the full burden of explaining return values, failure modes, cost implications, and routing behavior — and discharges all of it. An agent knows exactly what the tool returns on success, exactly what refusal reasons to expect, and when to choose this over siblings. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The tool description adds no parameter-level semantics, but the schema already documents all 6 parameters and the meaning of the natural-language question field, so the description need not compensate.

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

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

The opening phrase 'Hallucination-resistant answer mode for high-stakes reads' names a specific verb (answers with evidence), resource (the grounded extraction pipeline), and stance. It distinguishes itself from ask_pipeworx by the extraction constraint 'using ONLY what the tool result contains', so an agent can tell them apart without inspecting schemas.

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

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

Explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' with concrete domains (financial verdicts, legal claims, medical lookups). Also states the exclusion explicitly: 'prefer ask_pipeworx for casual lookups', naming the alternative and the cost trade-off ('Costs one extra LLM call') that justifies the choice.

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

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

The description goes far beyond the annotations by disclosing the resolver contract (market_match_confidence, alternatives, suggestions), status codes (low_confidence_match, market_closed_or_inactive), parent-event extractor, news fallback with retry_after_sec, wide-spread warnings, and cancellation-rule risk with ev_impact. It also explains blocking behavior and safety short-circuits. No contradictions with the readOnlyHint/idempotentHint annotations—this is a read-only research tool.

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

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

The description is lengthy, but it is front-loaded with purpose and usage in the first two sentences, then organized with CAPS labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) for clear scanning. Every section carries decision-relevant info, but the sheer volume and some redundancy (e.g., multiple mentions of closed markets) keep it from a 5.

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

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

With no output schema, the description fully carries the burden of explaining return values and edge cases. It comprehensively describes result.market, result.analysis, result.evidence, the resolver contract, parent_event partition, news fallback fields, status codes for blocking paths, and cancellation-rule risks. This is an extremely complete picture for a tool this complex.

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 all three parameters with descriptions and examples (100% coverage). The description adds contextual examples for the market parameter (slug, URL, question text) and shows fan-out behavior, but it does not add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names a specific verb ('Research'), a specific resource ('Polymarket bet'), and the method ('pulling relevant Pipeworx data'). It also distinguishes itself from siblings by describing its fan-out to category-specific data packs and its evidence+comparison output, which is unique among the listed sibling tools.

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

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

The description provides explicit usage guidance with concrete examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes classifier lists and fan-out examples to make the intended use cases concrete. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools for comparison, 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, and non-destructive. The description adds significant context: data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This exceeds the baseline and fully discloses behavior.

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

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

The description is dense but well-structured: trigger phrases, preference directive, per-type details, sorting behavior, and return format. Every sentence contributes new information and it's front-loaded with the most actionable content. No filler.

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

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

For a tool with two types, up to 5 entities, and no output schema, the description comprehensively covers what it does, data sources, edge cases, output format, and efficiency benefits. It provides enough detail for an agent to select and invoke correctly.

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

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

Schema already covers 100% of parameters with descriptions. The description adds value by providing concrete examples (AAPL, MSFT, ozempic, mounjaro), elaborating on what each type pulls (financials vs. adverse events), and specifying that values are tickers/CIKs or drug names. This is more than a simple repeat of schema info.

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 performs side-by-side comparison of 2–5 companies or drugs in one call, using specific verbs like 'compare' and 'rank'. It distinguishes itself from sequential single-pack lookups, making it clear what makes this tool unique.

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

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

Explicitly instructs to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and provides trigger phrases ('X vs Y', 'which is bigger') that indicate when to use it. Also clarifies differences between company and drug comparisons, 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?

The description goes far beyond the readOnly/idempotent annotations by disclosing account and paid-tier requirements, clarifying that it is NOT open-web search, and detailing the output packet shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, fetchable citation_uri). It also documents latency expectations and semantic excerpting behavior. No contradiction with annotations.

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

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

The description is long but dense with decision-relevant details: account requirements, alternatives, output format, depth behavior, citations, and latency. It is front-loaded with the account gate and alternative tool. Only minor redundancy exists around 'not open-web search', which is stated more than once.

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 compensates by specifying the return packet structure, gap/contradiction handling, citation_uri guarantees, semantic excerpting, latency, and limitations for breaking news. The depth behavior is also explained. An agent has enough context to call 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?

Schema description coverage is 100%, so the schema already fully documents the 'question' and 'depth' parameters, including enum meanings and paid-tier caveats. The description reinforces those meanings in prose but does not add semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' delivered in one call. It explicitly distinguishes itself from open-web search and names the sibling ask_pipeworx as the alternative for different use cases, so an agent can tell this apart from related tools.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data'. It also gives when-not-to-use and alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. This is comprehensive routing guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the return format and self-containedness 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 well-structured with three sentences covering purpose, usage, and return behavior. The long list of domains is somewhat verbose but each item adds clarity about the tool's coverage. It earns its place as a comprehensive yet efficient description.

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

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

For a discovery tool, the description is complete: it explains what it does, when to use it, what it returns, and how results are structured. No output schema exists, but the description sufficiently covers return expectations. It gives the agent everything needed to decide and invoke.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'describing the data or task' which aligns with the query parameter, but adds no additional parameter-specific meaning. The schema itself provides detailed descriptions and examples for all params.

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: 'Find tools by describing the data or task.' It clearly distinguishes from sibling tools like search_datasets or query_layer by focusing on tool discovery rather than data retrieval. The scope is further clarified with examples of domains covered.

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

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

Explicitly provides when-to-use guidance: 'Use when 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.' This clearly differentiates from alternatives and gives a tactical recommendation.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context about the parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, and discloses the USPTO PatentsView API sunset and soft-fail behavior. This exceeds what annotations alone provide.

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

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

The description is dense but efficient; it packs examples, return structure, and caveats into a single paragraph without fluff. It is front-loaded with the purpose and uses semicolons to organize the return fields. Slightly overlong but each clause adds 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 there is no output schema, the description compensates by detailing the return payload (cik, company_name, recent_filings with pipeworx URIs, fundamentals fields, patents, news mentions, LEI). It also covers limitations (names unsupported, USPTO sunset) and the parallel-call behavior, making it fully self-contained.

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

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

Even with 100% schema coverage, the description enriches the `value` parameter with concrete examples ('AAPL' or zero-padded CIK '0000320193') and explicitly states that names are unsupported, pointing to `resolve_entity`. It also clarifies the `type` enum is currently limited to 'company'.

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

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

The description opens with concrete user queries ('Tell me about X', 'research Acme') and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools by advocating over 'chaining single-pack SEC/XBRL/news lookups' for holistic requests.

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 instructs to 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also provides a direct alternative: if only a name is given, 'use resolve_entity first.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which convey that deletion is permanent and likely safe to repeat. The description adds the nuance of clearing 'sensitive data' but doesn't disclose additional behaviors beyond the annotations. No contradiction found.

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

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

The description is three concise sentences that each serve a distinct purpose: stating the action, providing when-to-use guidance, and mentioning complementary tools. There is no redundancy or filler.

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

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

For a simple single-parameter delete tool, the description covers purpose, usage context, and pairing. The absence of an output schema is acceptable given the tool's simplicity, and the annotations handle the destructive behavior, making the description 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 schema fully describes the only parameter ('key') with the description 'Memory key to delete', achieving 100% coverage. The description's phrase 'by key' merely repeats this meaning without adding extra semantics, such as allowed formats or examples.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), making the tool's function immediately clear. It also distinguishes itself from sibling tools like remember and recall by explicitly focusing on 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 usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also names complementary tools ('Pair with remember and recall'), offering clear guidance on when to use this tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: it 'fetches the page,' 'extracts title/description/key links,' and emits a single text blob in standard llms.txt format. It also notes it works for 'any URL' and is 'production-ready.' This contextualizes the operation beyond the annotation flags without contradicting them.

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

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

The description is three sentences: first states purpose, second explains mechanics, third lists use cases. Every sentence carries meaningful information with no redundancy or fluff. It is front-loaded with the core function and remains highly scannable.

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 compensates by explicitly stating the output format ('standard llms.txt markdown format' and 'single text blob ready to drop at site-root/llms.txt'). It covers inputs, process, output, and practical use cases. The tool is simple (two params, no nested objects), so this level of detail 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?

The input schema has 100% coverage; both 'url' and 'max_links' are described with clear examples and constraints. The description does not add additional parameter semantics beyond what the schema already provides. Since the schema fully covers parameters, 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 states a specific verb ('Generate'), a specific resource ('a production-ready llms.txt file'), and the mechanism ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It clearly differentiates the tool from siblings by focusing on llms.txt generation, while siblings like 'scan_competitor_ai_presence' or 'ai_visibility_check' address broader AI visibility concerns.

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 'Useful for:' scenarios (indexing a client's site, drafting for a project, auditing a competitor), which clearly communicates when to use the tool. It does not mention exclusions or alternatives, so it stops short of full comparative guidance, but the context is clear enough for an agent to select it appropriately.

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's 'Get' is consistent. The description adds valuable behavioral context by detailing what is returned (schema, geometry type, record count, capabilities), which goes beyond the annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and outputs without any unnecessary words or repetition.

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

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

Given the simple one-parameter tool with no output schema, the description adequately covers the return values and leverages annotations for safety. It lacks minor details like error handling or URL format nuances, but these are not critical for this simple read-only 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 has 100% coverage for the single url parameter with a clear description and example. The tool description does not add additional parameter semantics, but with full schema coverage 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 gets an ArcGIS layer's schema, listing specific outputs (fields, geometry type, record count, capabilities). However, it does not explicitly distinguish itself from sibling tools like query_layer, which might query the layer's data.

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

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

No guidance is provided on when to use this tool versus alternatives such as query_layer or search_within. There are no exclusions, prerequisites, or context indicating specific use cases.

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 context by specifying the return fields and emphasizing 'caller's active subscriptions' (scoping), which is beyond the annotations. No contradiction.

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

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

Two sentences, front-loaded with the core purpose, then a concise usage note. Every word earns its place; no fluff or redundancy.

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

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

For a simple 1-optional-param read tool with no output schema, the description covers purpose, return fields, and usage context completely. It tells the agent exactly what to expect and how to use 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?

Schema description coverage is 100% for the single optional parameter include_inactive, which already explains its meaning. The description does not mention the parameter, but the schema carries the burden, warranting 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 the tool lists the caller's active subscriptions, with a specific verb ('List') and resource ('subscriptions'). It distinguishes from sibling tools like subscribe/unsubscribe by focusing on read-only listing, and enumerates the returned fields (id, type, params, etc.).

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

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

Explicit usage guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool relative to subscribing/unsubscribing, effectively naming the alternatives and contexts.

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

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

Despite annotations (readOnlyHint=false etc.), the description adds critical behavioral context: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It discloses the claim_token flow and team response cadence ('The team reads digests daily and signal directly affects roadmap'). These go well beyond the binary annotation flags and give the agent a full picture of consequences and limits.

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

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

The description is long but every sentence earns its place. It front-loads the core purpose, then methodically covers when to use, exclusions, token mechanics, rate limits, and roadmap impact. There is no redundant phrasing or filler. The structure is logical, moving from what → when → how → constraints, making it easy for an agent to parse and act on.

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 burden of explaining return values, and it does: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' It also covers rate limits, quota impact, and the exclusion of non-Pipeworx tools, making it complete for the agent's decision-making and invocation.

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

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

Input schema covers 100% of parameters with descriptions, providing a baseline of 3. The description adds extra meaning beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' clarifies how to fill message/context, and 'Filing without an account returns a `claim_token`; pass it back later...' explains the claim_token parameter's purpose and usage pattern. This additional guidance pushes 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback types (bug, feature, data_gap, praise) and clearly distinguishes from siblings like ask_pipeworx by stating 'ONLY for tools served by this Pipeworx connection' and contrasting with 'another vendor's Gmail, Splunk, Slack, etc. connector.' This provides excellent differentiation.

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

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

The description gives explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server in your client... file it with that server instead,' naming the alternative action. This is textbook usage guidance with both inclusion and exclusion rules.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds valuable context: no PII, derived from CF analytics-engine, and caching behavior (5min-1h). This goes beyond annotations without contradicting them.

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

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

The description is well-structured with a clear lead sentence, practical use cases, and data-source context. Every sentence adds value with no repetition or fluff, and it is appropriately sized for a simple tool.

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

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

For a simple read-only tool with no output schema and one optional parameter, the description fully covers purpose, use cases, data composition, and freshness. The information provided is sufficient for an agent to select and 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?

The single parameter 'window' is fully described in the schema at 100% coverage, including the enum and semantics. The description reiterates the window options but adds no new parameter-level information 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 trending usage data: top tools, top packs, and total call volume over selected windows. This distinguishes it from sibling tools by focusing on aggregate agent behavior rather than specific data lookup.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). Does not explicitly state when not to use it, but the context is clear enough for an agent to decide.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial context beyond that: internal checks (monotonicity, partition-sum), placeholder filtering, similarity threshold, the fill-check mechanism, and a warning not to trade when realizable edge is ≤ 0. This is far richer than the 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 long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and usage modes. Every sentence carries operational detail, and the formatting makes the complex content navigable rather than a wall of text.

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

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

With no output schema, the description fully explains the response structure: opportunities[] with fields, partition_check object, and fill-check outputs. It also covers edge cases (null signals, skipped_low_similarity, placeholders_filtered) and even names the sibling tool for custom sizing. For a complex arbitrage tool, this is exceptionally 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?

Although schema coverage is 100% and both parameters have descriptions, the tool description adds significant meaning: it explains the difference between single-event and cross-event modes, provides concrete example slugs and seed questions, and clarifies what happens in each mode (e.g., walks child markets, runs comparator on union). This goes well beyond the schema.

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

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

The description opens with a clear verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then enumerates three distinct modes (trending_scan, event, topic), each with a specific scope, which distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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: '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 explains which mode is recommended for a specific market and cross-references polymarket_fill_risk for custom sizing, giving clear alternatives.

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

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

Annotations only declare read-only, open-world, idempotent, and non-destructive traits. The description adds substantial behavioral context: result caching at the KV level, segmented response with model-specific algorithms, diagnostics for why segments are empty, the 24h-move warning about edge already priced in, and specific exclusion of Fed bets due to unreliable signals.

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

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

The description is extremely long and dense with niche details like per-sport alpha values (tennis 1.02, soccer 1.10, MMA 1.15), placeholder-slug filters, and Run 8 historical gate relaxations. While logically front-loaded with the core purpose, much of this detail is not necessary for tool selection or invocation and could be relegated to output documentation.

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

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

With no output schema, the description compensates by thoroughly detailing response top-level fields (by_segment, fed_candidates, _diagnostics), edge metrics (edge_pp_net, kelly_fraction, liquidity, spread), and the funnel counters for empty segments. It also covers caching behavior, making the tool's runtime characteristics fully transparent.

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

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

All 9 parameters are already described in the schema, yet the description adds deeper context: it explains the purpose of 'tradeable-edge knobs', clarifies that min_kelly doesn't apply to partition arbs while min_partition_leg_kelly does, and details how slippage is subtracted from raw edge before ranking. This goes well beyond the schema's individual parameter descriptions.

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

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

The description opens with a clear, specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also positions the tool for a concrete use case ('what should I bet on today'), distinguishing 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 states it is 'built for what should I bet on today' and explains how knobs like min_liquidity/max_spread_pp filter opportunities. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for an agent to select it for edge discovery.

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, and idempotentHint, but the description goes far beyond by explaining response structure (tracked, expired, snapshot_dates), snapshot gaps due to cache-miss, TTL limits, decay calculation method, and the meaning of negative values. No contradictions with annotations; the description adds rich behavioral context.

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

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

Although long, the description is front-loaded with a one-line purpose, then clearly labeled sections (Args, RESPONSE, LIMITS). Every sentence provides necessary detail—parameter semantics, response fields, and limitations—without fluff. The structure makes dense information scannable and efficient.

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

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

With no output schema, the description takes on full responsibility for explaining return values, and it does so thoroughly: tracked, expired, and snapshot_dates each get definitions and caveats. It also covers limitations (TTL, snapshot enablement, daily closes) and edge cases (gaps mean no scan). For a telemetry tool with this complexity, the description is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: days is described as 'lookback, default 14, max 30' while schema also mentions clamp 2-30, and window is framed as 'snapshot family' with examples from schema. It clarifies how parameters map to snapshot data, adding value over the schema alone.

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+resource combination: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers what the tool does—tracking edge longevity and decay—and differentiates from sibling tools like polymarket_edges by focusing on time-series behavior rather than current edges.

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

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

The description implicitly states when to use this tool: when you need to know how long an edge has existed and whether it is shrinking, contrasting fresh vs. old wide edges. It does not explicitly name alternative tools or provide 'when not to use' exclusions, but the context strongly implies usage scenarios and distinguishes from the base edges tool.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds rich behavioral detail: walk-the-ladder execution, mode-specific returns (top_of_book, vwap_fill_price, slippage_pp, verdict), basket-level overround capture, and the 'forced_directional_risk' naming of risky legs. It also warns about partial-fill failure modes—context far beyond the annotation flags. No contradiction.

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

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

The description is dense yet well-structured: a one-line purpose, then REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. Every sentence carries practical information; it is front-loaded with the core purpose and mode requirements. Length is justified by the tool's two-mode complexity.

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

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

With no output schema, the description carries the burden of explaining return values—and it does so thoroughly for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, plus basket-specific theoretical_sum, realizable_sum, capture_ratio, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also notes the USD threshold for use, making the tool fully usable without external references.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond field names: it explains mode-dependent semantics (size_usd as spend on buys vs target proceeds on sells vs settlement notional in basket), defaults, clamp range (10–1,000,000), and REQUIRES one of market/event. This substantially enriches the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as use-case triggers in the 'USE THIS' sentence.

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: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books not capturable, partial fills create unhedged directional risk), giving clear context for when this tool is needed over alternatives.

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

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

Discloses extensive behavior beyond the annotations: response structure, compatibility warnings and codes, unknown-leg handling, skipped cross-type/cross-subtype counters, and temporal alignment. Annotations only indicate read-only/idempotent behavior, so this description carries substantial additional transparency. 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 well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core definition. It is dense and long, but the detail is largely justified given there is no output schema, though it could be tightened without losing key 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 covers return values, safety fields, compatibility codes, skipped counters, and temporal alignment, making the tool genuinely usable. The main gap is that it never explicitly states that exactly one mode is required or what happens if no arguments are provided, which is relevant given the schema lists 0 required parameters.

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 already documents each parameter. The description adds meaningful semantics: topic auto-fetches matching events, explicit tickers override the topic-mapped side, and the two modes are clearly defined. This exceeds the baseline schema-only value.

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

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

States a specific verb and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling Polymarket tools by focusing on cross-venue comparison, and explicitly describes two operational modes. No ambiguity or tautology.

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

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

Provides clear usage context by explaining the `topic` shortcut mode versus explicit `kalshi_event_ticker`/`polymarket_event_slug` pairings, and warns that pre-mapped topics are not automatically tradeable. It does not name specific sibling alternatives or explicit when-not-to-use conditions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds return behavior ('Returns attribute rows (and geometry)') and a practical sampling tip, which is useful beyond the annotations. No contradictions found.

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

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

The description is two sentences, front-loaded with the main purpose and parameters. The second sentence is a valuable, non-redundant tip. No filler or 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 read-only query tool with high schema coverage and safety annotations, the description covers the essential return type (attribute rows and geometry) and gives a quick-start example. It could mention potential errors or external service behavior, but overall it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by summarizing the SQL-like semantics of 'where' and the combination of where="1=1" with out_fields="*" for sampling, which is a meaningful usage pattern not fully explicit in the schema.

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

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

The description clearly specifies the verb 'Query' and the resource 'ArcGIS Feature Service / Map Service layer', and explicitly ties it to 'search_datasets' for provenance. It distinguishes itself from siblings like layer_info (metadata) and search_within (spatial search) by focusing on layer querying by URL.

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 context: querying a layer obtained from search_datasets, and even gives a concrete sampling pattern with where="1=1" and out_fields="*". However, it does not explicitly state when NOT to use this tool or name alternatives, so it falls short of a full 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the behavior of omitting the key to list all entries, which 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?

Three sentences, each earning its place: core functionality, usage examples, scoping, and sibling pairing. No redundancy or filler.

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

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

For a simple one-parameter retrieval tool with no output schema, the description covers purpose, usage, scope, and related tools completely. The agent has everything needed 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?

Input schema fully describes the single optional `key` parameter with the omit-to-list-all behavior. The description reinforces this but adds little beyond what the schema already states, so baseline 3 applies.

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

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

The description clearly states the tool retrieves values saved via remember, with an optional list-all-keys mode. It distinguishes itself from sibling tools (remember saves, forget deletes) by explicitly naming the pairing.

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

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

Provides explicit usage context: look up previously stored context without re-deriving it, and mentions when to use siblings (remember, forget). This gives the agent clear decision guidance.

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

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

The description directly contradicts the readOnlyHint annotation by stating that setting mark_read:true flags events as read, which mutates the persisted feed state. This is a state-changing behavior, and the annotation indicates a read-only operation, so the description fails to align with the annotation.

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

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

The description is three sentences, front-loaded with the primary purpose, then return payload details, filtering options, mark_read behavior, and an alternative access endpoint. Every sentence earns its place; no filler or redundancy.

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

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

For a read-oriented tool with five parameters and no output schema, the description covers what is returned, how to filter, the mark_read side effect, and even provides an external endpoint. The main shortfall is the annotation contradiction, which prevents a perfect score, but structurally it is nearly complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful context beyond the schema: it provides a concrete example for type ('sec_8k'), clarifies the meaning of since as an ISO timestamp, and explains the behavioral effect of mark_read on subsequent calls. 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 opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states what the tool returns (most recent alerts with source, citation_uri, raw payload) and distinguishes it from sibling tools like list_subscriptions and recent_changes by focusing on the persisted alert feed.

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 usage context: filtering by type and since, using mark_read to make subsequent calls return only newer events, and notes that polling works fine. It also gives an alternative access method via HTTP for scripts/dashboards, though it does not explicitly name sibling tools or state when not to use this tool.

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

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

Despite strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavior: multi-source fan-out, GDELT→GNews fallback with conditions, USPTO soft-fail, and output including citation URIs. This goes well beyond what annotations convey.

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

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

Although long, every sentence adds distinct value: use cases, source details, fallback logic, parameter formats, return structure, and alternative tool. It is well-organized and front-loaded with the core purpose.

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

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

Given the multi-source architecture and lack of output schema, the description thoroughly covers the return value (grouped changes, total count, citation URIs), fallback behavior, and source reliability. It is complete for an agent to select and invoke this tool correctly.

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

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

Schema covers all three parameters clearly, but description adds valuable examples for 'since' (ISO vs relative) and for 'value' (ticker vs CIK), plus typical monitoring suggestion. This exceeds the baseline 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 this is a change feed for a company over a time window, with concrete example queries ('What's new with X'). It distinguishes from sibling entity_profile by noting when to use the static profile instead.

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

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

It gives explicit use cases, mentions fallback behavior, and directly states when to use entity_profile instead. The 'since' parameter guidance ('Use 30d or 1m for typical monitoring') adds practical usage context.

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

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

Adds meaningful context beyond annotations: storage is 'scoped by your identifier,' and persistence differs by auth state ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). This complements the annotations (idempotentHint, destructiveHint, etc.) without contradicting them.

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

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

The description is compact and well-structured: it starts with the core purpose, then usage contexts, storage details, and sibling references. Every sentence adds value with no fluff or repetition.

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

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

For a simple key-value store tool, the description covers all essential aspects: purpose, when to use, persistence/scoping, and relationship to recall/forget. No return value is needed, and the schema fully documents parameters.

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

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

The schema already fully describes both parameters with examples and descriptions (100% coverage). The tool description itself does not add further parameter-level detail, so the baseline score applies.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('save') and resource ('data'), and explicitly differentiates from siblings by mentioning 'recall' and 'forget' as complementary tools.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also names alternatives/related tools: 'Pair with recall to retrieve later, forget to delete.'

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 significant behavioral context: graceful degradation ('LEI/FIGI enrichment degrades gracefully'), internal cascading ('each call cascades through several lookup endpoints'), and explicit handling of unresolved identifiers ('unresolved rather than omitted'). 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 comprehensive but still well-structured, with examples front-loaded and supported types listed in a clear paragraph. Every sentence adds value, though the detail about 'cross-source identity spine' and source-specific behavior could be slightly trimmed. It earns its length given the complexity.

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

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

No output schema is provided, but the description explains what each type returns (identifiers, sources, unresolved list). It covers edge cases (ISIN lookup, graceful degradation, explicit unresolved). While a formal output structure would help, the description is nearly complete for an agent to understand the expected result format.

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

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

Schema coverage is 100% with descriptions for both params, but the description adds crucial meaning: explains the 'type' enum with detailed resolution behavior for 'company' (CIK, ticker, LEI, FIGI, ISIN mapping) and 'drug' (RxCUI, ingredient, brand). For 'value', it clarifies that ISINs resolve to legal entities via GLEIF. This goes well beyond the schema's brief 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 concrete examples ('What's the ticker for...', 'find the CIK for...') and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.' and specifies exactly what it resolves (company, drug) with detailed identifier types.

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.' and provides natural-language query patterns that trigger the tool. It also notes that internal cascading replaces 2-3 manual lookups. While it does not explicitly exclude alternative tools like compare_entities or entity_profile, the 'first' guidance strongly signals when to use it.

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

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

Annotations already flag readOnly/openWorld/idempotent/non-destructive. The description adds process details (probes each entity, ranks by score, surfaces most/least recognized) and return shape (score, confidence, signal density), which goes beyond the safety profile. It does not mention auth/rate limits, but those are not contradicted and the schema carries the API key info.

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 filler. The first sentence states the core action, the second explains the mechanism, and the third gives a concrete use case and return format. All sentences earn their 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?

The description covers purpose, process, use case, and return fields, making the tool's behavior comprehensible without an output schema. It doesn't explain edge cases like the optional models/_apiKey behavior in prose, but the schema already documents those, so the coverage is adequate for 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 covers 100% of parameters with descriptions, including the distinction that the first entity is the 'subject'. The tool description does not add any additional param-level meaning beyond what the schema already provides, so it stays at the baseline 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?

Description states 'Compare AI visibility across multiple entities side-by-side' – a specific verb+resource. It further distinguishes from sibling tools by mentioning it probes via ai_visibility_check, ranks by score, and tallies most/least recognized, narrowing to competitive AI-marketing audits.

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

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

The description gives clear use context ('competitive AI-marketing audits') and an illustrative question. It implies the single-entity tool ai_visibility_check for individual checks by saying it 'probes each entity ... with ai_visibility_check', but doesn't explicitly say 'use this instead of X when you have multiple entities', so no explicit exclusion/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 the tool as readOnly, idempotent, and non-destructive. The description goes above the annotation baseline by disclosing composite fan-out behavior, latency characteristics ('bundlephobia's first measurement on a new version can take 5-30s'), and graceful degradation ('sources_failed will list it if it times out, the rest still returns'). These behavioral traits are valuable and not inferable from 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 the core identity, then systematically covers usage, return fields, ecosystem scope, and failure behavior. While a bit longer than average, every sentence contributes new, actionable information. The structured ordering (purpose → use → outputs → limits → exceptional behavior) makes it easy for an agent to parse.

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

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

There is no output schema, so the description fully specifies the return payload: summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min/gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and alternative versions. It also covers partial failure semantics and ecosystem constraints, making the tool's behavior well-understood without any additional context.

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

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

The input schema has 100% description coverage for both parameters (package and version), including scoped package syntax and default-to-latest behavior. The description does not add further parameter-level detail beyond the schema, so the baseline of 3 is appropriate; the schema already carries the semantic weight.

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

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

The description opens with a specific, compound purpose: 'Composite "should I add this npm package to my project" check in ONE call'. This clearly names the resource (npm dependency) and action (scan/check), and distinguishes it from sibling tools like validate_claim or scan_competitor_ai_presence by listing unique data sources (deps.dev, bundlephobia) and outputs (license, advisories, bundle size).

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear usage boundaries and redirects to a more appropriate tool for non-NPM ecosystems.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which already convey the safety profile. The description adds useful behavioral context: it returns specific fields (name, summary, record_count, owner/org, feature service URL) and indicates the tool is for open geospatial datasets. However, it doesn't say anything about pagination or rate limits, which would be extra value, but annotations suffice for core transparency.

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

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

The description is two sentences: the first concisely states purpose and scope, the second lists return fields and the chaining action. Every word adds value, no redundancy, and it's appropriately sized relative to the tool's simplicity.

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

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

Given no output schema, the description compensates by naming the exact fields returned and the chaining recommendation. The tool is a search/discovery read operation, so it doesn't need to explain side effects. The only slight gap is lack of mention of pagination, but with 1-50 limit and no required params, the context is sufficient for a candidate selection task.

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

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

Schema description coverage is 100%, with each parameter (limit, query, org_id) having a meaningful description. The tool description adds context about the default org (City of Austin GIS) and that query is keyword-based, but it doesn't repeat parameter details beyond that. Baseline 3 for high coverage, with a slight bump for the description's note that 'query' can be multiword and the default scope, which supplements 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 a specific verb ('Search') and resource ('City of Austin GIS open geospatial datasets'), and enumerates content areas. It distinguishes itself from sibling tools like query_layer and layer_info by explaining its role as a discovery step and explicitly mentioning that the returned URL is to be passed to those tools.

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

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

The description provides explicit usage guidance: use this tool to find datasets by keyword, and then pass the returned Feature Service URL to query_layer / layer_info. It positions the tool as a discovery precursor, making the appropriate context clear and implicitly distinguishing it from tools that operate on a specific layer.

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

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

Beyond the readOnly/openWorld/idempotent/destructive annotations, the description discloses technical behavior: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging. These are meaningful operational details that help the agent predict results 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?

The description is information-dense but not bloated. The first sentence delivers the core purpose, the second explains when to use it, and the third provides technical context. Every clause adds value, though the final sentence is fairly long with multiple clauses; still, it is well-structured and front-loaded.

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

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

Given no output schema, the description fully covers what the agent needs: input requirements, result shape (passages with character offsets and similarity scores), use case, algorithmic details, and input limits. It is complete for a search tool with 3 parameters and rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'text' parameter's practical role ('the text you already pulled'), giving concrete example queries for the 'query' parameter, and reinforcing the char limit with truncation behavior. It does not fully restate the schema but enhances it with usage context.

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' with a clear resource ('inside a fetched record') and explicitly contrasts with sibling ask_pipeworx_grounded. It clearly states the tool's function: semantic search over already-fetched text with passage-level results, distinguishing it from other search/query tools.

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

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

Provides explicit guidance on when to use: when the record is too big to fit in the prompt, to save context and return only relevant passages. It also names the complementary alternative ask_pipeworx_grounded and explains the workflow ('fetch with the gateway, ground over the relevant passages instead of the whole document'), giving clear usage direction.

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

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

Annotations already mark this as non-read-only, idempotent, and non-destructive. The description adds substantial behavior: returns the new subscription id, account restrictions, webhook signing secret shown once, SMS verification and daily cap, and auto-disable after failures. No contradiction with annotations.

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

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

The description is front-loaded with purpose and prerequisites, then systematically covers types and delivery channels. It is dense but well-organized; every sentence adds value, though it is longer than strictly necessary 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?

Given no output schema and high complexity, the description omits two of five enum types (patent_grant, clinical_trial) and the webhook delivery channel, both present in the input schema. This could mislead an agent about supported subscription options. Return value is covered, but the gaps are significant.

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 rich parameter descriptions for params and delivery. The description repeats some examples (sec_8k items, polymarket topic, fred series_id) but adds little beyond schema; the phone-verification note is already implied in the delivery.sms schema description. Baseline 3 is appropriate.

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

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

Description opens with 'Create a proactive monitoring subscription to a live-data event stream', using a specific verb and resource that clearly distinguishes it from siblings like list_subscriptions or unsubscribe. It then enumerates concrete subscription types and delivery channels, reinforcing its role.

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

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

Specifies a prerequisite ('Requires a Pipeworx OAuth account – anonymous + BYO cannot persist subscriptions') and clarifies the action is for creating subscriptions. It does not explicitly contrast with alternatives, but the context makes it clear and no exclusions are given.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world traits. The description goes beyond by disclosing the dynamic nature ('drawn from the live catalog of thousands of tools'), the return structure (category-bucketed example questions with tool+argument shape), and that omitting the topic gives a 'full spread'—all meaningful behavioral context.

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

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

The description is longer than typical, but every sentence contributes: it leads with relatable example queries, states the core purpose, enumerates categories, describes the return value, and gives call variants. It is front-loaded and information-dense, though slightly verbose; a tighter second half could earn a perfect score.

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

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

Given the tool's complexity (one optional parameter, no output schema), the description fully covers what it returns, when to use it, and how to invoke it. It answers the likely questions an agent would have about this onboarding tool, making it contextually complete.

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

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

Although the input schema already describes the optional `topic` parameter with an enum-like list, the description adds concrete examples ('finance', 'pharma', 'betting'), maps them to the category names, and explains the default behavior when the parameter is omitted ('Call with no arguments for the full spread'). This goes well beyond the schema's 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 the 'onboarding entry point' for discovering what to ask Pipeworx, with a specific verb ('Returns category-bucketed example questions') and resource. It distinguishes itself from siblings by mentioning it maps questions to 'exact tool + argument shape' from the live catalog, and it names related meta-tools explicitly.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains two invocation modes (no arguments vs. passing a topic), which acts as clear usage direction.

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

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

Beyond annotations, the description adds key side-effect details: ownership enforcement ('you can only cancel your own subscriptions'), and the deactivation policy ('row is deactivated, not deleted') with a link to recent_alerts for historical events. These clarify exactly what the mutation does and its persistence implications, which is valuable context not present in the annotations.

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

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

Two concise sentences: the first states the primary action and input, the second provides necessary behavioral caveats. No redundant wording, and each sentence carries essential 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?

For a simple one-parameter mutation with no output schema, the description fully covers what happens, who can do it, and the resulting state. The annotation hints cover idempotency and destructiveness, and the description adds ownership and historical data retention. This is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for the single parameter ('Subscription id (uuid) returned by subscribe.'). The description only says 'by id', adding no extra meaning beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription') with an explicit identifier ('by id'). It clearly distinguishes the tool from siblings like subscribe and recent_alerts by noting the deactivation behavior retains historical events.

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 usage context is implied: use this to cancel a subscription. Ownership enforcement is stated, but there is no explicit mention of alternatives or when not to use it (e.g., to re-enable, use subscribe). It does not say to list subscriptions first, though that is a natural precursor. This is adequate but not explicit about 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?

Discloses critical behavioral details beyond annotations: the verdict enum, inclusion of grounded/structured values with pipeworx:// citation, and the important distinction between could_not_verify (check did not happen) and unsupported (no source exists). Also explains the verification_error structure. 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?

Although lengthy, every sentence serves a purpose. The structure flows from usage examples to routing logic to output semantics to critical edge-case warnings. It is dense but not redundant, and the 'IMPORTANT for callers' callout is well-placed for high-risk misinterpretation.

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 covers the full behavioral contract: what verdicts are possible, what evidence is returned, how errors are communicated, and the two lookup paths. For a tool of moderate complexity with 2 parameters, 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 already covers both parameters fully (100% coverage). The description adds extra semantics for tolerance_pct: 'set 1–2 for hallucination detection where any material error must be refuted' and clarifies default behavior ('capped at 5'). This goes slightly beyond the schema but not dramatically.

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: natural-language claim verification against authoritative sources. It lists concrete example queries ('fact check', 'verify the claim'), distinguishes between company-financial claims (SEC EDGAR) and other factual claims, and notes it replaces 4-6 sequential calls. This clearly distinguishes it from sibling tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for financial vs. other claims and highlights that it replaces multiple sequential calls, making the decision to use it vs. alternative pipelines clear.

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