Arcgis Chestercounty

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: default model is free, passing _apiKey probes Anthropic with direct cost to the user, and it returns per-model {score, confidence, signals, raw_response} + combined view. This goes beyond annotation coverage, though it does not detail rate limits or failure 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?

Three sentences, front-loaded with the core purpose. Each sentence earns its place: purpose, default/cost behavior, return format, and use cases. 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 4-parameter tool with no output schema, the description covers the essential aspects: what it does, which models are involved, cost implications, return payload structure, and typical use cases. It could elaborate on scoring methodology or error handling, but it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by specifying the default model (Workers AI Llama-3.3-70b, free) and clarifying the cost implication of passing _apiKey, which enriches the models parameter semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on cross-model visibility scoring.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when not to use it or name alternatives. The guidance is contextual but lacks exclusions or direct sibling comparison.

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

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

The description adds meaningful behavioral context beyond the readOnly/openWorld/idempotent annotations: it routes to one of 5,596 tools, fills arguments automatically, returns structured answers with stable citation URIs, and can handle both current and historical data. This sets expectations for what happens when the tool is called, and there is no contradiction with 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 long but front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and every sentence serves a purpose: examples, trigger phrases, sibling distinctions, and result format. It is slightly repetitive, but the deliberateness is justified in extremely high ambiguity context.

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

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

The description provides enough to select and invoke the tool correctly: domain coverage, query types, routing behavior, output expectations, and alternative tools. The pure structured output with pipeworx:// citation URIs fills the gap of the missing JSON output schema, and the no-nested, single-string input is fully addressed.

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 parameter meaning is already fully present in the schema. The description still adds value by clarifying that the single required question/natural-language input should describe real-world entities, data, or events, illustrated with examples such as 'current US unemployment rate' and 'Active clinical trials for GLP-1'. This elevates a schema-only baseline.

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

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

The description states exactly what the tool does: routes a natural-language question to the relevant tool among 5,596 tools, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It also names the broad domain coverage (SEC, FDA, FRED, patents, news, etc.) and distinguishes itself from siblings like ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH', enumerates trigger phrases ('what is', 'look up', 'get the latest', etc.), and provides concrete examples. It also gives explicit routing rules for siblings: ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, bet_research, and validate_entity.

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 cover read-only/non-destructive behavior. The description adds meaningful behavioral detail: this is a full working router, not a fallback; behavior may change when candidate improvements are live; and currently it matches ask_pipeworx exactly. It could say slightly more about how failures or edge cases are handled, but the open-world and idempotent annotations lower the burden.

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

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

The description is information-dense but compact—four sentences covering purpose, current state, usage, and fallback behavior. It front-loads the relationship to ask_pipeworx and then provides procedural guidance. A minor redundancy is mentioning both 'identical' and 'currently matches ask_pipeworx exactly,' but it is not harmful.

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

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

With no output schema, the description adequately says the response shape is identical to ask_pipeworx's. It gives the agent current state, usage direction, and sibling alternative. It could still be more explicit about whether this is a safe choice for critical queries or whether the stable router should be preferred, but overall it provides sufficient context 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 description coverage is 100% and every parameter is documented as an alias for question. The description adds 'same arguments, same response shape' but does not add parameter-specific detail; the schema already carries that weight. This is the appropriate baseline score when the schema fully explains the inputs.

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

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

The description clearly states that this is the beta variant of ask_pipeworx, an identical universal router with the same 5,596 tools, arguments, and response shape. It also explains what differs: candidate routing improvements are enabled live when under test. This strongly 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?

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router, helping an agent choose this tool versus ask_pipeworx. The current state of no active candidate is disclosed so an agent knows exactly what to expect.

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

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

With annotations already covering read-only and idempotent behavior, the description adds valuable behavioral details: it describes the routing mechanism, the constraint that answers come only from tool output, the success return shape, refusal reason enums, and the additional LLM call cost. No contradiction with the annotations.

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

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

The description is information-dense yet organized: purpose, mechanism, output shape, refund/enum, explicit use cases, and cost comparison. Each sentence earns its place and the high-stakes usage condition 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 the lack of an output schema, the description fully defines return structure, refusal reasons, and expected behavior. It also covers routing semantics and cost trade-offs, leaving an agent with everything required to invoke the tool correctly and interpret its response.

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 all 6 parameters, including the question field and all aliases. The description does not add parameter-specific semantics, but the schema already carries this burden adequately, 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 starts with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly states that it routes to the right source tool, fetches data, and extracts an answer only from the tool result. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and the extra LLM call cost.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and its trade-off: 'prefer ask_pipeworx for casual lookups.' This fully routes an agent to the correct 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?

The description goes far beyond the annotations by detailing resolver confidence levels, blocking behavior on low-confidence or closed markets, wide-spread tradeability flags, news fallback handling, and resolution-rule risk. It discloses rate-limit handling (GDELT 429s) and the fact that both blocking routes exist. These behavioral details are consistent with the read-only, open-world, idempotent annotations.

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

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

The description is long but well-structured with bold section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it scannable. Every section adds substantive information required for safe use, though it could be tightened slightly. It is front-loaded with the primary purpose, and the sections follow a logical order.

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

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

With no output schema, the description takes on the full burden of explaining return values, and it does so comprehensively: it details the shapes of result.market, result.analysis, result.evidence, the resolver contract, parent_event extraction, status strings, and cancellation-rule parsing. It also handles edge cases like low-confidence matches, closed markets, wide spreads, and news fallback failures. Given the tool's complexity, this is a complete specification.

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

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

The schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful context for the 'market' parameter by reinforcing the three accepted input formats and for 'depth' by showing concrete quick vs thorough fan-out examples; it also explains how include_raw affects response size. This elevates it slightly above the baseline.

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

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

The description clearly identifies the tool as 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which is specific and distinguishes it from sibling tools focused on edges, arbitrage, and deep research. It also lists concrete use cases ('should I bet on X', etc.) and explains the classifier categories and fan-out behavior, leaving no ambiguity about the tool's role.

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

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

The description explicitly states when to use the tool with example queries and gives detailed fan-out examples for different bet categories. It doesn't name alternative sibling tools or explicitly say when NOT to use it, but the context is clear enough to inform selection among the available research tools.

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

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

Beyond the readOnly/idempotent annotations, the description discloses concrete behaviors: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled per entity type, handling of off-calendar fiscal years, result sorting by primary metric, and the return format (paired data + citation URIs). This provides deep transparency about execution and output.

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, leading with examples and then explaining behavior. It is slightly long with an extensive trigger-phrase list and repeated emphasis on 'parallel call', but every sentence carries meaningful info, so it remains 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?

Without an output schema, the description compensates by explaining return format (paired data + citation URIs), sorting behavior, data source nuances (off-calendar fiscal years), and the scale of the operation (replaces 8–15 lookups). This gives a complete mental model for invocation and interpretation.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaning by explaining what each type actually retrieves (company: latest 10-K revenue, net income, cash, long-term debt; drug: FAERS counts, FDA approvals, trials) and clarifies value formats (tickers/CIKs vs drug names), enriching the enum and array semantics beyond the schema.

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

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

The description clearly and specifically states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides explicit trigger phrases and distinguishes itself from sibling tools by noting it replaces 8–15 sequential lookups, making its purpose unmistakable.

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

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

Usage is explicitly guided with 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and a list of query patterns that should trigger this tool. This makes the when-to-use unambiguous relative to alternatives, fulfilling the highest bar for this dimension.

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

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

Even though annotations already declare readOnly and idempotent hints, the description adds substantial behavioral context: account/auth requirements, paid-plan constraints, the grounded structured-data nature, the parallel decomposition behavior, verbatim-evidence findings, explicit gaps, fetchable pipeworx:// citations, contradiction handling, excerpting of large records, and expected latency. No contradiction with 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 long but dense and well-structured. Key operational constraints are front-loaded (account requirement, fallback tool), followed by what the tool does, then return behavior and performance. Every sentence carries substantive information; some repetition of the depth semantics between schema and description is minor.

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 describing return behavior: findings, evidence, confidence, source, fetched_at, citation URI, gaps[], contradictions[], and semantic excerpting. It also covers error-adjacent behavior ('never invented'), authentication/plan needs, and timing. Nothing essential for correct selection or invocation is missing.

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

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

The input schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds meaningful behavior about depth variants — quick/standard/thorough facet counts, follow-up hops, contradiction scanning, and latency implications — which helps the agent choose a depth beyond just the enum names.

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 precise action: perform grounded multi-source research over 1,465 structured data sources in one call, decomposing the question into facets and routing them in parallel. It clearly separates itself from open-web search and from simpler lookups via ask_pipeworx, so an agent can tell what deep_research is and is not.

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 routing guidance: use ask_pipeworx if not signed in, use ask_pipeworx for a single lookup, and use deep_research for broad/multi-part questions over structured data. It also notes paid-tier requirements for 'thorough', which is directly actionable.

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 cover read-only/idempotent/non-destructive behavior. The description adds valuable context about the return format: 'top-N most relevant tools with names, descriptions, and full input schemas' and 'ready to call directly, no second schema lookup needed.' This 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 three sentences with a clear progression: purpose, use case, return value. The list of data domains is somewhat long but provides useful examples. No redundant or filler content.

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

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

With no output schema, the description fully explains the return value: top-N tools with names, descriptions, and full input schemas, ready to call directly. This makes the tool self-contained and complete for a discovery meta-tool.

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

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

Schema coverage is 100% with all parameters described, including aliases and the limit parameter. The description mentions 'top-N' and 'describing the data or task' but adds little beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation.

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: 'Find tools by describing the data or task.' It clearly distinguishes this from sibling tools by focusing on discovering tools rather than querying data or performing analysis. The list of domains reinforces the scope.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It does not explicitly name alternatives or when not to use, but the guidance is clear and actionable.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses important behaviors: it fans out across multiple sources, returns specific fields, and notes that the USPTO PatentsView API sunset May 2025 with a 'soft-fails until reactivated' behavior, plus a GDELT→GNews fallback for news. This adds substantial context not evident 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 concrete example queries, then states the core purpose, preference over alternatives, fan-out sources, return fields, and input constraints. Despite being a single long paragraph, every sentence carries meaningful information with no fluff, and the structure logically flows from usage to behavior to parameters.

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

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

With no output schema, the description compensates by enumerating the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers key context like soft-failure of patents, news fallback chain, and the restriction on input types. Given the tool's complexity, the description is sufficiently complete for an agent to invoke and interpret results.

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

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

The schema already documents both parameters (type and value) with descriptions and examples, providing 100% coverage. The description essentially repeats the same parameter information (ticker or CIK, names not supported, use resolve_entity first) without adding new semantics. Since schema coverage is complete, the baseline is 3, and no extra value is added by the description.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call', with specific examples like 'research Acme' and 'brief me on Tesla'. It distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack lookups and noting that names are not supported (use resolve_entity first).

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving clear when-to-use guidance. It also provides a when-not-to-use by stating names are not supported and pointing to resolve_entity for that case, along with example query patterns.

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, covering the key behavioral traits. The description adds minimal new transparency, only confirming the deletion operation and that it targets previously stored memories. It doesn't disclose additional behaviors like side effects, error handling, or non-existent key behavior, so a mid-range score is appropriate.

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-loads the action ('Delete'), and wastes no words. It effectively combines purpose, usage context, and relationship to sibling tools in a compact form.

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

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

Given the tool's simplicity (one parameter, no output schema, good annotations), the description covers the essential purpose and usage. However, it does not address behavior when the key does not exist or whether deletion is reversible, which would enhance completeness but is not critical for this simple operation.

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

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

The input schema has 100% coverage with the property 'key' described as 'Memory key to delete', which fully explains the parameter. The description reinforces this without adding new semantic details, so it stays at the baseline of 3 for high schema coverage.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'previously stored memory by key', clearly distinguishing it from siblings like 'remember' and 'recall' by its destructive nature. The scope is unambiguous and directly tied to the tool's name.

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

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

It provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember and recall', but it does not explicitly state when not to use it or list alternative tools for similar purposes, so it falls slightly 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?

The description discloses that the tool fetches the page, extracts metadata, and emits a text blob, which aligns with the annotations (read-only, open-world, idempotent). It adds process context without contradicting the safety profile, though it doesn't discuss error handling or rate 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 three tightly written sentences: purpose, process, and use cases. Every sentence adds value, and key information is front-loaded. 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 tool with no output schema, the description adequately explains the output ('single text blob'), the process, and typical applications. It doesn't cover error scenarios, but given the simple parameter set and strong annotations, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (`url` and `max_links`). The description reinforces 'for any URL' but adds no additional parameter-level details, matching the baseline for full schema coverage.

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

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

The description states a specific action ('Generate a production-ready llms.txt file for any URL'), the method (fetches, extracts, emits), and the output format. It distinguishes from sibling tools by focusing on creating the file rather than merely checking AI presence.

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

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

Clear use cases are provided ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). However, it does not explicitly exclude alternatives like ai_visibility_check, making differentiation somewhat implied rather than direct.

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, establishing safety. The description adds value by specifying exactly what schema elements are fetched (fields, geometry type, record count, capabilities), providing more concrete behavioral context than a generic 'get layer 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?

The description is a single, front-loaded sentence that names the operation, resource, and output details with zero filler. Every word contributes meaning.

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

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

For a simple read-only tool with one well-documented parameter, the description is nearly complete. It lists the key return items, though it lacks explicit mention of response format or error behavior; however, with no output schema and strong annotations, this is adequate.

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

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

The single parameter 'url' has 100% schema description coverage, including an example. The description's phrase 'by url' adds minimal semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get an ArcGIS Feature/Map Service layer's schema by url' and enumerates the specific data returned (fields, geometry type, record count, capabilities). This specific verb-resource pairing distinguishes it from sibling tools like query_layer or search_within.

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

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

The description provides clear context for when to use the tool—whenever layer schema information is needed. It does not explicitly name alternatives or exclusions, but for a single-purpose read tool, the intended use is unambiguous given the sibling list.

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 this as read-only, idempotent, and non-destructive. The description adds meaningful context beyond those by explicitly stating the return fields (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's active subscriptions. This is useful given there is no output schema.

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

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

The description is two concise sentences. The first states the purpose and return fields; the second gives usage guidance. No filler or redundancy; every word earns its place.

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

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

For a simple list tool with one optional parameter, strong annotations, and no output schema, the description is fully adequate. It explains what the tool does, what it returns, and when to use it, filling the gap left by the missing output schema.

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

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

The only parameter, include_inactive, is fully documented in the schema with a description, giving 100% coverage. The tool description mentions 'active' but does not explicitly explain the parameter's effect, so it adds no semantic value beyond the schema. A baseline of 3 is appropriate.

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

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

The description begins with 'List the caller's active subscriptions', which is a specific verb ('List') + resource ('subscriptions') + scope ('caller's active'). This clearly distinguishes it from sibling write operations like subscribe and unsubscribe. It also lists the exact return fields, leaving no ambiguity about the tool's function.

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

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

It states 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use the tool. It implies alternatives (subscribe/unsubscribe) without explicitly naming them, showing appropriate timing relative to those actions.

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

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

Annotations are all negative and provide little safety info, so the description carries the full burden. It fully discloses the two-phase workflow (filing returns a claim_token, later reading status), rate limits (5/day), quota exemption, and that the team reads digests daily. This goes well beyond what annotations offer.

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

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

Though longer than typical descriptions, every sentence earns its place: core purpose, use cases, explicit alternative, workflow, limits, and quota info. The most important context is front-loaded in the first sentence, and the rest is dense with actionable detail.

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 4 parameters, a nested object, no output schema, and uninformative annotations, the description still covers the full workflow: how to file, how to read a prior response, exclusion rules, and practical constraints. No significant gap remains for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful workflow context beyond schema descriptions: it explains the claim_token round-trip pattern, typical message length (1-2 sentences, 2000 chars max), and reinforces the type enum semantics. This additional guidance justifies a 4.

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

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

The description clearly states 'Tell the Pipeworx team something is broken, missing, or needs to exist' with a specific verb and resource. It distinctly differentiates from sibling tools like ask_pipeworx and discover_tools by focusing on feedback submission, not research or queries.

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 when to use the tool (bug, feature/data_gap, praise) and provides an exclusion rule: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary guidance.

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

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

The annotations already indicate a safe read-only, idempotent operation. The description adds valuable context by disclosing the data derivation (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h depending on window). This exceeds the baseline and complements 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 concise and well-structured, opening with a clear value proposition followed by a bulleted 'useful for' list and a final note on data characteristics. Every sentence adds meaningful information with no redundancy.

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

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

Despite having no output schema, the description explicitly states what the tool returns (top tools, top packs, total call volume) and the underlying data format. Combined with the annotations covering safety and the simple single-parameter schema, the description is fully sufficient for an agent to select and invoke the tool.

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

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

The only parameter 'window' has a full schema description with enum values and default. The tool description reinforces the options and adds an extra semantic: cache freshness depends on the chosen window. This goes slightly beyond the schema, but most of the meaning is already in the schema.

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

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

The description opens with a clear statement of what the tool does: reports what other AI agents are calling on Pipeworx. It specifies the outputs (top tools, top packs, call volume) and the time window options, distinguishing it as a meta-analytics tool rather than a specific data retrieval tool.

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

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

The description provides a 'Useful for' list with three concrete use cases (discovering hot data sources, confirming canonical tool choice, assessing alignment with agent needs). However, it does not explicitly state when not to use this tool or name alternatives, so it falls short of the highest bar.

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

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

Even though annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds rich behavioral context: partition placeholder filtering, Jaccard similarity threshold of ≥0.30, deviation >3pp trigger, and the fill check warning that realizable_edge_pp ≤ 0 means 'do not trade it'. This goes far 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 long but densely information-packed for a complex tool with three modes. It is front-loaded with the core purpose and then structured into clear sections (modes, semantic anchor, partition filter, response, fill check). Minor redundancy exists in repeating partition_check details, but each sentence earns its place.

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

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

For a tool with no output schema and two optional parameters, the description is exceptionally complete. It covers invocation modes, parameter details, algorithmic checks, response structure, risk guidance, and cross-references to polymarket_fill_risk. This is fully sufficient for an agent to select and invoke correctly.

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

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

The input schema already documents both parameters with descriptions, giving a baseline of 3. However, the description significantly adds meaning: it explains what event and topic modes do, provides examples of slugs, and describes the behavior and output for each. It also introduces the no-args mode, clarifying the parameterless invocation.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and references sibling tools like polymarket_fill_risk, making its unique purpose unmistakable.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It provides specific examples and says 'For custom sizing use polymarket_fill_risk', clearly indicating when to use 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 already declare readOnlyHint, openWorldHint, idempotentHint, but the description goes far beyond. It details the response segments (by_segment, fed_candidates, _diagnostics), the exact algorithms (lognormal barrier, GDELT ratio, favorite-longshot correction), slippage treatment, the 24h-move warning, caching (1h KV), and diagnostics for empty segments. This is exceptional behavioral disclosure.

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

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

The description is long but well-structured, front-loading the core purpose before diving into details. It uses ALL-CAPS section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and numbered segments to organize dense information. Every sentence contributes unique content, though some could be compressed; still, it earns its length for a 9-parameter 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?

Despite no output schema, the description fully documents the response envelope (top-level by_segment, fed_candidates, _diagnostics), field meanings (edge_pp_net, kelly_fraction_half, market.liquidity), filter logic, and caching. It even explains why fed bets are excluded and how to interpret empty segments. This is complete enough for an agent to invoke and interpret results without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic context. It labels knobs as 'TRADEABLE-EDGE KNOBS' and explains how min_liquidity/max_spread_pp drop opportunities, and how min_partition_leg_kelly differs from min_kelly due to partition design. This extra context goes beyond the schema's per-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 opening line, 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' gives a specific verb+resource statement. It further distinguishes itself by describing the three model families and the 'what should I bet on today' use case, clearly differentiating from sibling tools like polymarket_arbitrage.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides context for when to use the tool (high-level discovery) but does not name alternate tools or give explicit when-not-to-use guidance beyond the fed_bets note, so it's clear but not fully exclusionary.

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, but the description adds rich behavioral context beyond annotations: 60-day snapshot TTL, cache-miss snapshot writing, gap meaning, daily-close computation, net slippage, signed edge values, and distinct trend/decay computation on absolute values. 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 long but well-structured with clear labels (Args, RESPONSE, LIMITS) and front-loaded purpose. Every section adds necessary value, though the Args sentence partially duplicates schema information.

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

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

Given no output schema, the description thoroughly explains the response shape (tracked[], expired[], snapshot_dates[]), field meanings, and limitations like TTL and gap behavior. This is fully complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100% for both parameters (days and window). The description restates defaults and adds the lookback concept, but it does not materially add semantics beyond the schema's own descriptions. Baseline 3 is appropriate due to high schema coverage.

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

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

The description opens with a specific purpose: edge persistence and decay telemetry from daily polymarket_edges snapshots. It clearly answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from raw edge listings like polymarket_edges by focusing on time-series behavior.

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

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

The description clearly implies when to use this tool—when edge history/decay matters—and contrasts fresh vs. old edges. However, it does not explicitly name sibling tools as alternatives (e.g., 'use polymarket_edges for current edges only'), so it lacks an explicit when-not-to-use statement.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail: it walks the order-book ladder, supports two modes with different size_usd semantics, returns specific calculated fields (vwap_fill_price, slippage_pp, capture_ratio, etc.), and flags forced_directional_risk. It also warns about partial basket fills creating unhedged positions, which is meaningful behavioral context beyond annotations.

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

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

The description is dense but every sentence conveys necessary operational or risk information, organized with clear mode labels (SINGLE-MARKET, BASKET) and a required-field callout. It is longer than average but justified by the tool's dual-mode complexity and contains no fluff.

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

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

The tool has no output schema and only minimal annotations, yet the description enumerates all key return fields for each mode, including verdict values, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers defaults, clamps, and failure modes, making it fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter with mode-specific semantics beyond the schema: 'size_usd (default 1000 — max spend on buys, target proceeds on sells)' and basket interpretation 'settlement notional S (shares per leg; each share pays $1).' It also clarifies the `event` vs `market` selection and `side` defaults, adding real value.

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

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

The purpose is clearly defined as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' naming the specific resource (Polymarket fill risk) and action. It distinguishes itself from sibling tools by explicitly targeting pre-trade validation before polymarket_arbitrage or polymarket_edges signals.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also states why (theoretical overround not capturable on thin books) and the risk of partial basket fills, making the usage context unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds rich behavioral detail: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and how the tool explicitly reports when no arb exists. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries substantive information, but it could be slightly tightened; for example, the warning at the end could be condensed without losing meaning. Still, it earns its length given the tool's complexity.

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

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

No output schema exists, so the description fully compensates by explaining the response structure: leg-by-leg prices (0-1), top_spreads_pp (Kalshi − Polymarket), compatibility_warning conditions, temporal_alignment fields, and skipped counters. It covers edge cases (non-equivalent bet shapes, temporal misalignment) making the tool self-explanatory.

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

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

Schema coverage is 100% for the three parameters, but the description adds meaning beyond the basic types: it enumerates the 10 topic shortcut values, explains that explicit ticker/slug override the mapped side, and provides examples like 'KXFED-26OCT' and 'fed-decision-in-june-825'. This significantly helps an agent select correct inputs.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb+resource framing. It distinguishes from siblings like polymarket_arbitrage by detailing the two modes (topic shortcuts and explicit ticker/slug pairing) and the response semantics.

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: explains the two modes, when to use topic shortcuts vs explicit pairing, and warns that most pre-mapped topics currently return compatibility_warning and are not tradeable. It also explains conditions under which the spreads are meaningful (equivalent bet shapes, aligned temporal periods) versus when they are not, giving clear decision criteria.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds that it returns 'attribute rows (and geometry)' and provides a concrete sampling technique, giving useful behavioral context beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary verb and resource, and each clause adds value: target resource, parameter list, return format, and sampling tip. No wasted words.

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

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

For a read-only query tool with a fully documented schema and no output schema, the description covers the essential context: source of URL, parameter usage, return type (attributes + geometry), and a quick-start sampling pattern. It is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage, documenting all 6 parameters with descriptions (e.g., 'SQL where clause', 'Max features (1-2000, default 50)'). The description only adds a usage tip, not new parameter semantics, so it doesn't exceed the baseline of 3.

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

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

The description starts with a specific verb ('Query') and resource ('ArcGIS Feature Service / Map Service layer'), clearly indicating the tool's function. It also mentions the origin URL from 'search_datasets', which distinguishes it from sibling tools like 'layer_info' and 'search_within'.

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 notes the URL comes from 'search_datasets', implying a prerequisite workflow, and offers a sampling pattern ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly state when to use alternatives or provide exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral context by mentioning scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all-keys behavior when key is omitted. This goes beyond what annotations provide.

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

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

Two sentences, front-loaded with the primary action, and no filler. The pairing with remember/forget is stated compactly. Every sentence 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?

For a simple one-parameter tool with strong annotations and no output schema, the description covers purpose, usage, key semantics, scoping, and related operations. It is complete and well-rounded.

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% (the key parameter is described in the input schema). The description adds extra semantics by explaining that omitting the key lists all saved keys, which is not explicitly stated in the schema. This clarifies parameter behavior meaningfully.

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

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

The description starts with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes it from sibling tools like remember (save) and forget (delete).

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 the intended use case: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references pairing with remember and forget, implying recall is for retrieval. However, it does not explicitly mention when not to use it (e.g., for external search), but context is clear enough.

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

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

The description discloses mark_read:true behavior, which modifies read state, but this contradicts the readOnlyHint annotation. Since annotations declare readOnlyHint=true, the side-effect described is an inconsistency, scoring transparency at 1 despite otherwise useful behavioral detail.

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

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

The description is concise and front-loaded with the core action. Every sentence provides value: feed specifics, filter options, mark_read semantics, polling note, and alternative endpoint. No wasted words.

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

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

Given no output schema, the description explains return values (source, citation_uri, raw event payload). It also covers the main behaviors needed to use the tool effectively, and annotations cover safety profile. Slight reliance on schema for limit/unread_only is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a concrete example for type ('sec_8k') and explains the consequence of mark_read (next call shows only newer ones), going beyond schema descriptions. Limit and unread_only are only in schema, but no compensation needed.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts with source, citation_uri, and raw payload. The verb 'Pull' and resource 'subscription feed' are specific, and the inclusion of filtering and mark_read options distinguishes its read/query nature from sibling tools like subscribe/list_subscriptions.

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

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

It provides clear context: filtering by type and since, and explains polling works fine. It also offers an alternative endpoint for scripts/dashboards, which helps decide when to use this tool vs direct HTTP access. However, it doesn't explicitly compare to sibling tools like recent_changes, so no exclusion guidance.

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

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

Beyond the readOnly/idempotent hints, the description discloses internal behavior: 'Fans out to SEC EDGAR (filings since `since`), GDELT→GNews fallback (news mentions in window — GDELT preferred, GNews when rate-limited or 5xx), USPTO (patents granted; PatentsView API sunset May 2025 so this soft-fails until reactivated).' It also documents the return structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs').

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

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

Though dense, every sentence serves a purpose: example intents orient the agent, the core function is stated, data sources and fallbacks are enumerated, the `since` format is specified, return structure is given, and the sibling alternative is provided. No filler or redundancy.

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

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

Given the tool's complexity (multiple upstream sources, fallback logic, soft-fail condition, and no output schema), the description fully covers what the tool does, when to use it, how it behaves, and what it returns. The explicit alternative to entity_profile adds completeness by preventing misuse.

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 gives 100% coverage for all three parameters with clear descriptions (type enum, since formats, value as ticker/CIK). The description's mention of `since` formats merely echoes the schema and adds no new parameter semantics. Baseline 3 is appropriate because the 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 opens with concrete user intents ('What's new with X', 'latest on Y') and then states the core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names a sibling alternative with 'Use entity_profile instead when you want the static profile...', which differentiates this tool from at least one 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?

The description provides explicit usage signals via the example queries and closes with a clear when-not-to-use instruction: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives an unambiguous alternative for a distinct scenario.

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 idempotentHint=true and destructiveHint=false, and the description adds valuable context beyond these: scoping by identifier, persistence differences between authenticated and anonymous sessions, and the 24-hour retention limit. It does not mention behavior on duplicate keys, but the added retention and scoping details exceed 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 three sentences long, front-loaded with the main purpose, and every sentence adds utility: use cases, persistence behavior, and pairing with related tools. 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 simple two-parameter tool with a clear schema and annotations, the description covers purpose, usage, persistence, and tool relationships. It does not describe the return value, but that is not critical for a save operation, and the given context is otherwise sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, with both 'key' and 'value' already described with examples. The description reinforces the key-value pair concept and adds scoping context, but does not introduce new parameter-level detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'save' and describing the resource as a key-value pair. It also distinguishes itself from siblings by mentioning pairing with recall and forget, situating its role within the memory toolset.

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 when to use it ('Use when you discover something worth carrying forward') and provides concrete examples. It also names alternatives and complementary tools (recall to retrieve, forget to delete), giving clear guidance on when to choose this tool over others.

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 and idempotent. The description adds significant behavioral context: graceful degradation when external sources (GLEIF, OpenFIGI) are unavailable, cascading internal lookups, and explicit labeling of unresolved identifiers. No contradictions with annotations.

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

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

The description is detailed but well-structured, starting with example queries and use-case guidance, then listing supported types and behaviors. While slightly verbose, every sentence earns its place by providing essential information for correct tool selection and usage.

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 complexity of entity resolution across multiple sources (EDGAR, GLEIF, OpenFIGI, RxNorm) and two entity types, the description is remarkably complete. It explains what identifiers are returned, how unresolved ones are handled, and degradation behavior. No output schema is provided, but the description compensates thoroughly.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds meaning beyond the schema: for the 'value' parameter, it lists accepted formats (ticker, CIK, ISIN, name for company) and provides examples like 'ozempic' for drugs. This enriches the schema-definition without redundancy.

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's purpose: resolving a user-spoken name to canonical/official identifiers. It lists specific query patterns like 'What's the ticker for...' and 'find the CIK for...', and distinguishes the tool by stating it replaces 2-3 manual lookups. The purpose is specific and distinct from siblings like compare_entities or entity_profile.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' It also lists supported entity types (company, drug) and their input formats. While it does not explicitly state when not to use the tool, the guidance is clear and actionable for selecting this tool 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?

Annotations already declare read-only/open-world/idempotent/non-destructive. The description adds operational behavior: probing each entity with ai_visibility_check, ranking by score, and returning specific metrics (score/confidence/signal density). 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?

Three compact sentences: the first states the main purpose, the second explains the mechanism, and the third provides the use case and output format. Every sentence earns its place with no redundancy.

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

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

Despite no output schema, the description clearly states the return format (ranked list with score/confidence/signal density). It covers the underlying method, the use case, and the entities' roles. Remaining details (API key behavior) are already in the schema.

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

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

Schema description coverage is 100%, and the description does not add any parameter-specific semantics beyond what the schema already states. The mention of 'your brand + N competitors' is redundant with the entities parameter 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?

The description clearly states the specific verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. It distinguishes itself from the sibling tool ai_visibility_check by emphasizing the multi-entity comparison and ranking, making it unambiguous.

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

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

It provides a clear use case ('competitive AI-marketing audits') and an example question, giving strong contextual guidance. However, it never explicitly says when to use ai_visibility_check directly instead, so it lacks an explicit when-not/alternative statement.

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

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

The description richly discloses behavior beyond the read-only/idempotent annotations: it names the two external services, lists the exact return fields, warns about possible 5-30s latency on first bundlephobia measurement, and explains graceful degradation via sources_failed. 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 and well-organized, covering purpose, usage, return values, ecosystem scope, and failure behavior in a front-loaded structure. Every sentence carries useful information without filler.

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

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

Given the tool's complexity (composite of two external services, no output schema), the description is complete: it fully lists return fields, external data sources, performance considerations, and fallback guidance for other ecosystems. It leaves no major gaps for the agent.

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

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

Schema description coverage is 100% for both parameters (package and version). The description adds no new parameter semantics beyond what the schema already states; the version default is documented in the schema. Baseline 3 is appropriate.

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

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

The description states a specific purpose: a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It distinguishes itself from sibling tools by focusing on npm dependency viability and mentions the exact sources and output fields.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also explicitly excludes other ecosystems ('NPM ecosystem only in v1') and directs users to deps.dev:version for non-npm packages.

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 behavioral context by specifying the exact return fields (name, summary, record_count, owner/org, Feature Service url) and that it searches open geospatial datasets. This enriches understanding beyond annotations without contradiction.

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

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

Two concise sentences front-load the action and resource, and every phrase adds value—from the dataset categories to the return fields and the explicit handoff to query_layer/layer_info. No wasted words.

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

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

The tool is a straightforward search/discovery tool with no required parameters. The description covers what it returns, the scope, and the integration with sibling tools. Given the rich annotations and schema, no critical context is missing 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 coverage is 100%, with each parameter (limit, query, org_id) already described in the input schema. The description does not add parameter-level semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Search'), a precise resource ('Chester County GIS open geospatial datasets'), and lists categories ('parcels, addresses, zoning & public works'). It clearly distinguishes from siblings by naming 'query_layer' and 'layer_info' as downstream tools that consume the returned 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 implies the workflow: use this to discover datasets by keyword, then pass the returned Feature Service URL to query_layer or layer_info. This explicitly names the alternatives for querying data, giving clear guidance on when this tool is appropriate versus its siblings.

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

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

Annotations cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds substantial operational details: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and a flag. This exceeds annotation coverage and gives the agent a clear model of tool behavior.

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

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

The description is dense but every sentence serves a purpose: purpose, usage scenario, output details, pairing advice, and technical constraints. It is front-loaded with the main action, and the technical specifics are appended without redundancy. No filler or tautology.

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

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

No output schema exists, but the description explicitly explains the return format (top-N passages with character offsets and similarity scores) and mentions the truncation flag for oversized inputs. Combined with rich parameter semantics and behavioral context, the description fully equips an agent to invoke 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 coverage is 100%, but the description adds meaningful layer: 'text' is the document you already pulled, 'query' is natural-language with concrete examples, and 'limit' is top-N passages. It also reveals output semantics (offsets, similarity scores) that enrich parameter understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using the specific verb 'search' with the resource 'inside a fetched record'. It distinguishes itself from siblings by emphasizing it operates on text already pulled, whereas other tools like ask_pipeworx or search_datasets likely handle external or broader queries.

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: when the record is too big to cram into the prompt. It also provides a clear alternative/pairing with ask_pipeworx_grounded, advising to ground over relevant passages instead of the whole document. This gives concrete contextual guidance and differentiates from alternatives.

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

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

Discloses account requirements, phone verification, 10/day cap, and feed behavior, adding value beyond annotations. Minor omission: webhook channel not mentioned in the main description but covered in schema.

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?

Dense but efficient; front-loaded purpose, all sentences provide value. Could benefit from bullet points but remains readable.

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

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

Covers account prerequisites, delivery options, and return value, but omits webhook from the main description and doesn't detail the full response format; nevertheless, it's largely complete.

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

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

Schema has 100% coverage, and description supplements with concrete examples for each subscription type (e.g., items:['5.02'], topic:'fed'), enhancing parameter understanding.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream, with specific examples of supported types. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides context that a Pipeworx OAuth account is required and explains delivery channels, implying use for continuous monitoring. However, it doesn't explicitly state when to use this instead of pulling via recent_alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context beyond annotations: it details return format ('category-bucketed example questions'), content ('exact tool + argument shape'), and source ('drawn from the live catalog'). This is useful without over-explaining.

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 average but well-structured, front-loading example queries and then explaining behavior and usage. Each sentence adds value, and the list of categories is informative. It could be slightly condensed, but the length is justified by the richness of context provided.

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

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

Given a single optional parameter, strong annotations, and no output schema, the description is complete. It explains what the tool returns, how to invoke it, when to use it, and even gives example topics. There is no missing information that would prevent an agent from using the tool correctly.

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

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

The input schema already documents the 'topic' parameter with 100% coverage, including the list of allowed categories and the behavior when omitted. The description repeats this information and adds only a few examples ('finance', 'pharma', 'betting'), which is helpful but not essential. 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 clearly states the tool's purpose: it suggests example questions for onboarding, listing specific example queries and describing what it returns. It distinguishes itself from sibling tools like discover_tools and ask_pipeworx by positioning itself as the 'onboarding entry point' and explicitly mentioning meta-tools.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to vary usage (no arguments for full spread, or pass a topic to focus), which gives clear context for appropriate invocation.

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

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

The description adds significant behavioral context beyond the annotations: it reveals that ownership is enforced and that the row is deactivated rather than deleted, keeping historical events available via recent_alerts. This goes well beyond the readOnly/destructive hints.

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

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

The description is two sentences long, front-loaded with the main action, and every word provides value. 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 simple single-parameter mutation with no output schema, the description covers essential aspects: purpose, ownership, and side effects. It omits return values and error scenarios, but the core behavior is well specified, making it 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?

The schema fully documents the only parameter ('id') with 100% coverage, so the description does not need to add parameter details. The description's reference to 'by id' adds no new semantic meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('Cancel'), a specific resource ('subscription'), and the method ('by id'). This distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

The description provides clear context for use: cancel an existing subscription by its id. It does not explicitly mention alternatives or when not to use the tool, but the ownership constraint gives implicit guidance. No exclusions are given, but the tool is the obvious counterpart to subscribe.

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. The description adds substantial behavioral context beyond that: it explains the structured vs. grounded routing, the verdict set, and the crucial distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source found). This is highly valuable and consistent with annotations.

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

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

The description is long but information-dense; it front-loads with common user phrases and use cases, then covers pipeline, return values, and failure semantics. Every sentence adds critical information, though it might be slightly verbose for a 2-parameter tool. Still, the structure is logical 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?

Despite no output schema, the description clearly explains expected return values (verdict, actual value, citation, reasoning) and failure modes (could_not_verify with error structure, unsupported). It also explains the routing behavior for different claim types, making the tool fully understandable without additional documentation.

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

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

The input schema already describes both parameters with 100% coverage. The description adds extra semantic value, especially for tolerance_pct: it explains that it overrides the wording-implied tolerance, gives a use case (hallucination detection), and notes the default cap at 5. This goes beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources, with explicit examples of trigger phrases. It distinguishes itself from sibling research tools by focusing specifically on claim verification and by explicitly describing the two pipelines (SEC fast path vs. grounded pipeline), making it unmistakable.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear call-to-action. It does not name alternative sibling tools for exclusion, but the description states it replaces 4–6 sequential calls, implying it's the go-to for claim checks. Could be improved by explicitly saying when to use a different tool (e.g., deep research), but the guidance is strong.

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