Arcgis Palmbeach

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

Adds crucial behavioral detail beyond annotations: the free default model, optional Anthropic probe with BYO key, direct customer billing, and per-model response structure. These cost and auth implications are not captured by the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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?

Four sentences, front-loaded with purpose, then default behavior, return format, and use cases. Every sentence earns its place with 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 absence of an output schema, the description covers the return shape, default behavior, optional model configuration, cost/auth implications, and typical use cases. It is sufficiently complete 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?

All four parameters have detailed schema descriptions (100% coverage), so the description need not repeat them. It adds no additional parameter-level semantics beyond summarizing the default model and API key purpose, which the schema already documents fully.

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

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

The description opens with a specific action ('Probe one or more LLMs...score visibility') and clearly defines the resource (business/brand/product/topic) and output (0-100 score per model). It distinguishes itself from sibling Q&A tools by emphasizing per-model scoring and a combined view.

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?

States concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default and optional model behavior. However, it does not explicitly name alternative tools or exclusion criteria, despite overlapping with siblings like scan_competitor_ai_presence.

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 that the tool routes questions, fills arguments, and returns structured answers with citation URIs. No contradictions with annotations (read-only, idempotent, non-destructive). Does not mention potential latency or failure modes, but the core behavior is transparent.

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

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

The description is highly repetitive: 'PREFER OVER WEB SEARCH' appears twice, 'START HERE' twice, and the list of domains is redundantly phrased. It could be reduced by 50% without losing information. This hurts readability and violates the 'every sentence earns its place' ideal.

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 verbosity, the description provides rich context: it names sibling tools and when to use them, clarifies the tool handles live news, and explains the output format. No output schema exists, but the description compensates by mentioning structured answers with citations. It is complete enough for an agent to decide when to invoke it.

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

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

The schema covers all six parameters with descriptions, and the main 'question' field notes aliases. The description adds minimal extra semantic value beyond the schema, though it does provide examples of questions. Schema coverage is 100%, 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 answers questions about current or historical data across many domains, and explicitly lists example topics. However, the purpose is obscured by repetitive promotional language ('PREFER OVER WEB SEARCH', 'START HERE') that could be condensed.

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?

Excellent guidance on when to use this tool versus alternatives: it explicitly says to prefer it over web search, and directs users to ask_pipeworx_grounded for evidence-backed answers and deep_research for broad questions. Also clarifies it handles live news.

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, the description discloses that behavior may change when candidates are tested, that no candidate is currently active so it matches the stable version exactly, and that it does not fall back to anything else—it is a fully working router. This is transparent about the experimental nature and current state.

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

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

The description is three concise sentences with no fluff. It front-loads the purpose, then provides usage guidance and behavioral transparency in a well-organized manner.

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

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

For a tool with a simple parameter set and no output schema, the description provides enough context for an agent to invoke it correctly: it explains what it does, when to use it, and how it behaves. No critical information is missing.

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

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

The schema provides 100% coverage with a description for the 'question' parameter and aliases. The tool description adds no additional parameter semantics beyond what is already in 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 that this is a universal router identical to ask_pipeworx but with experimental routing improvements. It specifies the tool's function (routing to 5,801 tools) and distinguishes it as the beta version of the stable sibling.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' giving direct guidance on when to choose this over the stable alternative. It also explains that results are compared against the stable router, clarifying its purpose as an experimental testbed.

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 fully discloses that the tool fetches data via internal routing, extracts answers only from the tool result, and returns an explicit refusal with a reason when the data does not directly answer. Combined with the readOnlyHint and idempotentHint annotations, the behavior is transparent and not contradictory.

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

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

The description is well-structured but somewhat verbose, with repeated emphasis on 'only what the tool result contains' and the tool count/routing detail. It remains scannable and includes essential trade-off information, though a slightly tighter wording would improve focus.

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 a sufficient mental model: it explains the internal routing, the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), and the refusal cases. It lacks a full output schema, but the textual return structure and usage context are complete enough for an agent to understand expected behavior without ambiguity.

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

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

The schema already documents all six parameters as aliases for the single 'question' field with 100% coverage. The description adds no further parameter-specific semantics, so a baseline score of 3 is appropriate given the schema's completeness.

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

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

Clearly states its purpose as a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing itself from ask_pipeworx by its grounded extraction behavior. The verb 'asks' and the answer/evidence return structure make the tool's function 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?

Provides explicit guidance on when to use this tool (when answers will be quoted, cited, or acted on and facts must not be invented) and when to prefer the alternative (casual lookups via ask_pipeworx). Also notes the extra LLM call cost as a trade-off, which is practical routing advice.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals critical runtime behaviors: resolver confidence levels (high/medium/low/none), low-confidence short-circuit status, closed-market path, parent-event extraction for partitions, and cancellation-rule parsing (refund_50_50, resolves_no_on_cancel, etc.). It also warns about audited losses from flat-50¢ void settlements, which is exactly the kind of context annotations don't provide. No contradictions with annotations.

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

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

The description is long but highly structured with CAPS section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Every sentence carries operational information—there is no filler or repetition. Deducting one point for overall length; at ~600 words it demands careful reading, but it earns it.

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 does the heavy lifting of describing return values: result.market fields, result.analysis fields, evidence keys, resolver contract, parent_event, news fallback fields. It also documents blocking error states and safety mechanisms, so the agent knows exactly what to expect and what to check before sizing. This makes the tool usable 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 description coverage is 100%, so the tool description doesn't need to restate parameter formats. It does add some context (e.g., what 'market' can be, and fan-out illustrations for 'depth') but these largely mirror the schema. Therefore, a baseline 3 is appropriate; the description adds no new parameter-level semantics.

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

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

The first sentence states a specific action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges by emphasizing a one-call, category-driven evidence fan-out. The classifiers and fan-out examples further scope its purpose.

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

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

The description explicitly directs when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides category-specific fan-out examples (e.g., BTC bet → coingecko + fred + gdelt+gnews) to guide selection. However, it never mentions when not to use it or points to an alternative sibling, so it stops 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?

It discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), specific metrics per type, handling of off-calendar fiscal years, sorting by primary metric, and returns paired data with citation URIs. This goes well beyond the annotations (readOnly, idempotent) by explaining actual operational behavior and edge cases.

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 each sentence earns its place: trigger phrases, preference guidance, type-specific data, sorting behavior, and return format. Despite being longer than a minimal description, it is well-structured and front-loaded with the most critical usage patterns.

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 stating it returns paired data and citation URIs, and notes results are sorted. It covers entity count limits, data sources, fiscal-year handling, and replacement of many sequential lookups. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and already describes type and values with examples. The description adds the specific data each type pulls (e.g., 10-K revenue for companies, FAERS counts for drugs) and clarifies ticker/CIK vs drug name formats, enriching the meaning beyond the schema, although the schema already covers the basics.

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

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

The description clearly states a side-by-side comparison of 2–5 companies or drugs in one parallel call, using explicit trigger phrases ('Compare X and Y', 'X vs Y'). It distinguishes itself from sequential single-pack lookups by emphasizing parallel execution, which sets it apart from sibling tools like entity_profile.

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

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

The description provides concrete query examples ('which is bigger / better / larger / more profitable') and explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives clear when-to-use guidance and hints at alternatives without ambiguity.

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

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

The description thoroughly discloses behavior beyond the readOnly/openWorld/idempotent annotations: it explains the hop-based iteration, gap recovery, contradiction scanning, semantic excerpting (not head-truncation), citation_uri resolvability, and the failure mode of returning empty gaps[] for non-catalog topics. No contradiction with annotations; readOnly and idempotent are fully consistent with a research/query tool.

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

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

The description is information-dense and front-loaded with the most important differentiators, but it is quite long and contains some redundancy (e.g., repeated emphasis on 'not open-web search', repeated contrast with ask_pipeworx, repeated mention of gaps[]). Still, every sentence earns its place in conveying behavioral nuance; only minor tightening would improve it.

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 — multi-hop research, depth tiers, contradiction handling, citation resolvability, excerpting behavior — the description is remarkably complete. It covers expected latency, output characteristics (contradictions[], hop fields, citation_uri), failure modes (empty gaps[]), and second-hop behavior. No output schema exists, so the description carries the full burden, and it succeeds.

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 question (natural language) and depth (enum with descriptions). The description adds meaning beyond the schema by explaining what each depth level does in practice (hop counts, gap recovery, contradiction scans, paid tier for thorough) and by clarifying that 'question' is meant to be broad/multi-part since decomposition is the tool's point. Coverage is 100% and the description enriches both parameters.

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 verb (deep research), resource (Pipeworx's structured data catalog), and scope (multi-facet, multi-hop question answering). It explicitly distinguishes itself from sibling tools like ask_pipeworx and names what it is NOT (open-web search), leaving no ambiguity about purpose.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions; prefer ask_pipeworx for single lookups and for breaking/current-news or colloquial topics. It also explains depth levels (quick/standard/thorough) and expected latency, so an agent knows exactly when to select 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety surprises. The description adds useful context: returns top-N tools with full schemas and curated examples ready for direct invocation, and lists covered domains. It does not contradict annotations.

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

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

Concise and well-structured: front-loaded purpose, then usage, then return details, then strategic guidance. The domain list is long but purposeful. No fluff or redundancy with the schema.

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 fully explains the return value: top-N tools with names, descriptions, full input schemas, and curated examples, ready to call directly. It also provides critical usage strategy with 'Call this FIRST' and a domain scope, making it complete for an agent to decide when and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a list of searchable domains (SEC filings, FDA drugs, BLS jobs, etc.) and example query forms, helping agents understand how to formulate the `query` parameter. This goes beyond the schema's generic 'natural language 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 'Find tools by describing the data or task' with a specific verb and resource. It differentiates itself from siblings by framing itself as a discovery/meta-tool, explicitly listing covered domains and positioning itself as the first step when many tools are available.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear contexts for use and subtly distinguishes from direct-answer 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?

Even though annotations already declare readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral context: it fans out across specific sources, soft-fails on the sunset USPTO endpoint, treats empty sections as expected 'no data' rather than bugs, and explains that private companies return resolved:false with a notes line. This goes well beyond what annotations or schema 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 long and runs as one dense paragraph, but the front-loaded user examples and 'ALWAYS PREFER' guidance are immediately actionable. Every subsequent clause earns its place by describing output fields, source behavior, failure semantics, and expected empty cases, so the length reflects the tool's complexity rather than padding.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates top-level fields, per-source semantics, source failure reporting, input resolution, and the private-company case. The agent has enough to invoke the tool correctly and interpret its results for diverse inputs.

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, and the description adds meaningful nuance: both type values behave identically, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR's company-name match. It mostly reinforces the schema, but the examples and resolution behavior add practical guidance beyond the raw field definitions.

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

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

The description opens with concrete user phrasings and states the exact resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from single-pack SEC/XBRL/news lookups and from sibling research tools by emphasizing the holistic, parallel, cross-source scope.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This gives the agent an actionable selection rule and names the alternative pattern to avoid, which is exactly the kind of when/when-not guidance this dimension asks for.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds only the context of clearing sensitive data; 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?

Two sentences with the action verb front-loaded and no wasted words; the pairing advice is a useful addition.

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 destructive tool with annotations covering safety, the description fully covers purpose, usage, and context; output schema not needed.

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

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

Schema description coverage is 100% with 'Memory key to delete' describing the key parameter; the description adds no additional parameter details, so baseline 3 is appropriate.

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

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

States 'Delete a previously stored memory by key' with a specific verb+resource, clearly distinguishing it from sibling tools remember and recall.

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

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

Explicitly provides when-to-use guidance ('when context is stale, the task is done, or you want to clear sensitive data') and names alternatives ('Pair with remember and recall').

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral details: it fetches the page, extracts specific elements, and outputs a single text blob in standard llms.txt format. It does not mention edge cases like invalid URLs or rate limits, but it goes beyond the minimum.

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

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

The description is front-loaded with the main purpose, follows with process, and then lists use cases. It is slightly longer than strictly necessary but every sentence earns its place. The bullet list is useful and not redundant.

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?

This tool is simple: 2 params, no output schema, no nested objects. The description covers purpose, process, output format, and use cases. It is complete enough for an agent to select and invoke the tool correctly. Lacks error-handling details but not critical for a read-only generator.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description adds context by explaining the overall process ('extracts title/description/key links') but does not provide additional parameter-specific meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file'), and clearly states what it does: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This distinguishes it from siblings like scan_competitor_ai_presence, which focuses on auditing AI presence rather than generating a file.

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 concrete use cases: getting a client's site indexed, drafting llms.txt for a project, or auditing a competitor. It implies when to use the tool but does not explicitly state when not to use it or mention alternatives. Clear context but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds meaningful behavioral context by specifying the exact outputs (fields, geometry type, record count, capabilities) and limiting scope to schema retrieval, which is consistent with annotations. No contradiction.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then lists the returned items. Every word contributes value without redundancy.

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

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

Given only one parameter, rich annotations, and no output schema, the description adequately covers return values (schema fields, geometry type, count, capabilities). It is complete for the tool's simplicity and leaves no critical gaps.

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

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

Schema has 100% coverage for the single `url` parameter, clearly describing it as a Feature/Map Service layer URL. The description's 'by url' adds no new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Get' with a clear resource: 'an ArcGIS Feature/Map Service layer's schema'. It enumerates exactly what's returned (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that likely retrieve data rather than metadata.

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

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

The description implies usage for schema inspection but does not explicitly state when to use this tool versus alternatives like query_layer or search_within. There is no mention of exclusions or preferred context, so guidance is only implied by the tool's purpose.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing the response fields and implying that only active subscriptions are returned by default, which complements the schema's include_inactive parameter. It does not mention potential pagination or large result sets, but for a simple list tool this is adequate.

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

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

The description is compact and front-loaded: the primary action in the first clause, followed by the return fields and a practical use case. Every sentence earns its place with no redundant content.

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

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

For a list tool with one optional parameter and no output schema, the description is complete: it explains the return fields, the default behavior, and when to use it relative to sibling tools. Annotations cover safety, and schema covers parameters, leaving no significant gaps.

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

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

The single parameter include_inactive is fully described in the schema (100% coverage), including its default behavior. The tool description does not add any semantic information 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 with a specific verb ('List') and resource ('the caller's active subscriptions'), and lists the exact return fields (id, type, params, created_at, etc.), making it easy to distinguish from sibling tools like subscribe 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?

Explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This clearly contrasts with adding subscriptions (subscribe) and cancelling (unsubscribe), providing practical guidance on when this tool is appropriate.

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

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

Annotations are all false, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for reading resolution, the fact that digests are read daily, and that it's free and doesn't count against quota. It also states behavioral scope (only Pipeworx tools). These are significant behavioral traits beyond the schema and annotations, adding real transparency about side effects and constraints.

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 (9 sentences) but every sentence earns its place: purpose, when-to-use, exclusion, claim_token usage, rate limit, and quota impact. It is front-loaded with the main action and structured logically. While it could be slightly tightened, it avoids redundancy and remains highly scannable.

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

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

For a tool with 4 parameters (one nested object) and no output schema, the description explains the key response element (claim_token) and how to use it for follow-up. It also mentions rate limits and scope. Minor gap: it doesn't clarify what happens when filing with an account (whether a claim_token is still returned) or what the immediate response looks like, but overall it covers the essential context for correct usage.

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 extra semantics beyond the schema: it explains how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and gives content guidance for the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This lifts the score above baseline because it clarifies usage nuances not evident in the schema alone.

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

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

The description opens with a clear statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and identifies the resource (Pipeworx team). This is further distinguished from siblings by explicitly limiting scope to Pipeworx connection tools and stating exclusions (other MCP servers). No other sibling tool handles feedback, so it is clearly differentiated.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use condition: tools from other MCP servers should be filed elsewhere. Additional guidance on what to include (describe in terms of Pipeworx tools/packs, don't paste user prompt) and how to use claim_token is provided, making alternatives and exclusions 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This gives the agent insight into data freshness and composition beyond the safety 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 efficient, with a short lead sentence, a bulleted list of use cases, and a final transparency note. No redundant filler, though the use-case list could be slightly tighter.

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 optional parameter and no output schema, the description covers return contents, use cases, data source, and caching. It even hints at the output shape ('just (pack, tool, count)'), making it 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 single 'window' parameter is fully documented in the schema with enum values and a description of trade-offs. The tool description repeats this information but adds no new parameter-level semantics, so baseline 3 applies.

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

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

States it returns top tools, top packs, and total call volume over a recent window, using the specific verb 'returns' and naming the resource. This clearly distinguishes it from sibling discovery/search tools by focusing on aggregate call volume.

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

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

The description explicitly lists three use cases with 'Useful for', including discovering hot data sources and confirming canonical tools. However, it does not name alternative tools or state when not to use it, so it provides clear context but no exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds extensive behavioral detail: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check with realizable_edge_pp ≤0 meaning 'do not trade it', and reporting of skipped_low_similarity and placeholders_filtered. This far exceeds the minimal baseline and enriches the agent's understanding of edge cases.

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

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

The description is long but every sentence serves a purpose. It is front-loaded with the core purpose, then logically structured into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) that group related details. No fluff or redundancy; the density is justified by the tool's complexity.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers return values: opportunities[] fields, partition_check breakdown, and fill check outputs. It also addresses failure modes (realizable_edge_pp ≤0, placeholder fractions) and actionable guidance ('do not trade it'). The agent has enough context to use the tool correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial value: it gives concrete examples for `event` ('fed-decision-may-2026' or a full URL) and `topic` ('Strait of Hormuz traffic returns to normal'), explains the behavioral difference between modes, and clarifies what each mode does with the parameter. This goes well beyond restating the schema.

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

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

The description opens with a clear verb-object-method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings by naming the specific detection techniques and enumerating three modes (trending_scan, event, topic), which immediately clarifies scope and uniqueness.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends which mode to choose for a specific market, explains when cross-event mode is advantageous, and even references polymarket_fill_risk as an alternative for custom sizing.

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 declaring read-only/idempotent/non-destructive, the description adds rich behavioral context: the three response segments, model families (crypto_price lognormal barrier, news_momentum GDELT ratio), edge calculation net of slippage, Kelly caps at 0.25, 24h-move warning, tradeable-edge knobs, caching behavior (1h KV level), and diagnostics for empty segments. This far exceeds annotation coverage without contradiction.

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

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

The description is front-loaded with a clear purpose and organized into identifiable sections (TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). However, it is extremely dense and includes long parenthetical asides (e.g., per-sport alpha values, gate relaxation history from prior Run 8) that could be trimmed for readability. Every sentence adds value, but the length and complexity reduce conciseness.

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

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

This tool has no output schema, so the description carries full responsibility for explaining the return shape. It thoroughly describes top-level fields (by_segment, fed_candidates/fed_note, _diagnostics), why segments might be empty, caching, and the meaning of tradeable-edge knobs. For a complex tool with 9 optional parameters, the description is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter semantics by explaining the 'TRADEABLE-EDGE KNOBS' (min_liquidity, max_spread_pp) and the interaction between min_kelly and min_partition_leg_kelly (partition arbs return parent kelly=0, so min_kelly never filters them). It also clarifies category_filter through the explanation of the three response segments. While not every parameter is individually discussed, this additional context goes beyond the schema.

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

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

The description opens with a clear, specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on discovery ('what should I bet on today') rather than arbitrage or tracking.

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 states the intended use case ('what should I bet on today') and that it avoids paging hundreds of markets, which tells agents when to reach for this tool. However, it does not explicitly name alternative tools or provide when-not-to-use conditions, aside from noting Fed bets are excluded from ranking. This is clear context but lacks direct exclusions or alternatives.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses substantial behavioral details: snapshots are written only on cache-miss, gaps mean nobody scanned that day, history depth is bounded by a 60-day TTL, decay is computed from daily closes net of default slippage (not intraday), and expired items include closed/resolved/arbed-away opportunities. This significantly exceeds what annotations provide.

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

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

The description is front-loaded with the purpose and question, then organized into Args, RESPONSE, and LIMITS sections. It is dense but every segment earns its place—the illustrative trade comparison, response field semantics, and TTL/cache caveats are all operationally relevant, making the length justified rather than redundant.

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 shape: tracked[], expired[], and snapshot_dates[], including derived fields like trend, decay_pp_per_day, lifespan_days, and the median lifespan as a 'competition clock.' It also covers coverage gaps, history depth limits, and the slippage basis for decay, making the tool completely understandable for invocation.

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

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

Schema coverage is 100%: both `days` and `window` already carry descriptive schema text including defaults, clamps, and allowed families. The description adds context that `days` controls lookback across snapshots and `window` is the snapshot family, but this doesn't materially exceed the schema's own parameter descriptions, matching the baseline for high schema coverage.

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

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

The description opens with 'Edge persistence and decay telemetry' and explicitly frames the tool's core question: 'how long has this edge existed and is it shrinking?' It names the specific resource ('daily polymarket_edges snapshots') and differentiates it from sibling polymarket_edges by focusing on temporal persistence and decay rather than current edge values.

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

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

Clear context is provided: use this tool when you need to know whether an edge is new or aging, illustrated by the 'fresh wide edge vs. 3-week-old wide edge' contrast. It doesn't explicitly name sibling alternatives or give 'when not to use' exclusions, but the intended use case is clear from the question it answers.

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/non-destructive, and the description adds substantial behavioral detail beyond that: it discloses that the tool 'walks the ladder', returns specific verdicts (clean|degraded|cannot_fill), interprets size_usd differently for buys vs sells, and highlights risk leg behavior (thin_legs, forced_directional_risk). No contradiction with annotations is present.

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

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

Though long, the description is tightly organized and front-loaded. It begins with the core purpose in one line, then uses clear section labels (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) to structure the content. Every sentence adds functional value, from return fields to risk warnings. The density is justified by the tool's two-mode complexity.

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

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

With no output schema present, the description compensates by enumerating all key return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers prerequisites, defaults, and failure modes, making it highly actionable.

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

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

While the schema covers all four parameters at 100% detail, the description adds critical semantics beyond the schema: the 'one of market or event' requirement, mode-specific side behavior (sell_yes = capture overround, buy_yes = capture underround, auto default), and the precise meaning of size_usd in basket mode (settlement notional, shares per leg). This is exactly the kind of interpretive guidance that helps an agent invoke correctly.

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

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

The description opens with a precise, specific statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the resource (Polymarket order books), the action (checking fill risk vs theoretical edge), and distinguishes two distinct modes (single-market and basket). It also differentiates from sibling tools by naming polymarket_arbitrage and polymarket_edges, 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?

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequence of not using it ('partial basket fills convert an arb into an unhedged directional position'), effectively providing a 'why' and 'when not to skip' guidance. It names the relevant sibling tools as alternatives/context.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds substantial behavioral context: compatibility warnings can be non-empty even when pairs are returned, temporal_alignment null does not mean aligned, unknown legs are never paired, Kalshi fees are not modeled, and skipped-cross counters expose dropped comparisons. This goes far 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?

The description is front-loaded with a clear purpose and uses labeled sections such as TWO MODES, RESPONSE, and SAFETY FIELDS. It is quite long and repeats a few points, like the identical matcher in both modes and the in-EITHER-mode qualifier, but the density is mostly justified by the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, safety fields, failure modes, and interpretation pitfalls. It covers top_spreads_pp, compatibility_codes, temporal alignment semantics, fee caveats, and skipped counters, making the tool fully actionable for an agent.

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

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

The schema already covers all three parameters with examples and override semantics, so the baseline is high. The description adds value by explaining that both modes run the same token-overlap matcher and that the same disclosures apply to custom pairings, which is useful operational meaning not present in the schema.

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

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

The description clearly states the resource and action: a cross-venue spread between Kalshi and Polymarket for the same resolving question, with two concrete modes. It does not explicitly name a sibling alternative, so differentiation from tools like polymarket_arbitrage is implied rather than stated.

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

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

The description gives explicit guidance on when to use the topic shortcuts versus custom ticker/slug pairings, and warns that pre-mapped topics are not automatically tradeable. It does not compare this tool against sibling tools, but within its own scope it clearly explains usage context and limitations.

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 that it 'Returns attribute rows (and geometry)', which goes beyond the structured data by clarifying the return format. 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?

Two concise sentences: first summarizes purpose and key parameters, second offers a concrete usage tip. No wordiness, information is front-loaded and every sentence earns its place.

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

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

For a query tool with 6 parameters and no output schema, the description covers the core functionality well, including return of rows/geometry and a sampling suggestion. It could mention error behavior or pagination quirks, but these are partially covered by the schema's limit/offset descriptions.

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. Description adds minimal param semantics: 'SQL-like' for where, 'comma-separated' for out_fields, but these nuances are already hinted in schema examples. The description doesn't significantly enhance 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 'Query an ArcGIS Feature Service / Map Service layer by its url', identifying the specific verb, resource, and connection to search_datasets. It distinguishes itself from sibling tools like layer_info by focusing on data querying rather than metadata.

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?

Gives clear context: use when you have a URL from search_datasets and want to retrieve data. Includes a useful sampling tip ('where="1=1" + out_fields="*"') but lacks explicit exclusions or alternative tool mentions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping info ('Scoped to your identifier') and the listing behavior when key is omitted, which goes beyond the schema. However, it doesn't cover return format or edge cases, so not a 5.

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

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

Four short sentences, front-loaded with the main action, each serving a distinct purpose (function, usage, scope, alternatives). No fluff.

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

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

For a 1-param, 0-required tool with strong annotations, this description is complete: it covers purpose, usage context, scope, and complementary tools. No output schema needed as nothing to explain.

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% (the only parameter key has a description). The description repeats the omit behavior but adds no new parameter syntax. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This specific verb-resource pair distinguishes it from siblings like remember and forget, which are explicitly named.

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

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

It provides explicit use cases: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also points to alternatives: 'Pair with remember to save, forget to delete.' This gives clear when-to-use and alternative framing.

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 a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the readOnlyHint=true annotation, creating a serious inconsistency about whether the tool mutates state.

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 purpose, and every clause provides useful information: return payload, filters, mark_read behavior, and an alternative endpoint. No redundancy or fluff.

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

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

Without an output schema, the description does well to outline the returned fields (source, citation_uri, raw event payload). It also covers filtering, mark_read implications, polling, and an external mirror. However, the annotation contradiction undermines reliability and completeness.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds minor value through an example type ('sec_8k') and clarifies that mark_read affects future calls, but these are small enhancements over the schema descriptions.

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

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

The description opens with a specific verb ('Pull') and a clear resource ('fired events from your subscription feed'), immediately distinguishing this from siblings like list_subscriptions or recent_changes. It also elaborates on the returned payload, reinforcing its unique 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?

Provides practical context: filter by type/since, set mark_read, and it states polling works fine while offering an alternative HTTP endpoint for scripts. It does not explicitly name sibling alternatives or say when not to use this tool, but the 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?

Annotations (readOnlyHint, idempotentHint, openWorldHint) already establish safety, but the description goes further by disclosing internal behavior: parallel fan-out to SEC, GDELT/GNews, and USPTO; GDELT preference with GNews fallback; and USPTO soft-fail due to PatentsView API sunset. It also mentions the return format (changes[], total_changes, citation URIs) beyond what annotations provide, giving the agent a clear mental model.

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

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

The description is a single dense sentence, front-loaded with natural-language query examples, followed by the source fan-out logic and a clear pointer to an alternative tool. Every clause delivers essential information—sources, fallbacks, input format, output shape, and sibling distinction—without wasted words.

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

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

Given the tool's multi-source complexity and the absence of an output schema, the description adequately covers what it returns ('structured changes[] grouped by source + total_changes count + citation URIs') and how it behaves under failures (GNews fallback, USPTO soft-fail). It also clarifies that the operation is a single parallel call, which is critical for runtime expectation. No obvious gaps remain for practical use.

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

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

The schema already provides full descriptions for all three parameters (type, since, value), and the description's examples ('2026-04-01', '7d', '30d', 'AAPL', '0000320193') mirror the schema text almost exactly. Since schema coverage is 100%, the description adds limited new parameter-level meaning, though it does reinforce typical usage ('Use 30d or 1m for typical monitoring').

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' and frames it with concrete user queries like 'What's new with X' and 'updates on Acme'. It also distinguishes itself from the sibling tool entity_profile by comparing feed versus static profile, making its purpose unambiguous.

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

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

The description gives direct usage guidance: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains the fan-out strategy and fallback logic (GDELT→GNews on rate limits/5xx), which helps an agent decide when this tool is appropriate and what behavior 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?

Beyond the annotations (idempotent, non-destructive, readOnly=false), the description discloses critical behavior: key-value pairs scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24h) sessions, and the pairing with recall/forget. This is substantial added context not present in the annotations.

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

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

The description is three sentences, each earning its place: purpose, usage guidance with examples, and persistence details. It is front-loaded with the core purpose and remains concise without redundancy.

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

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

For a simple 2-parameter write operation with no output schema, the description is complete. It covers what to store, when to use it, persistence behavior, and companion tools. No additional context is needed 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?

The input schema already provides detailed descriptions for both parameters, including examples for key and value, so schema coverage is 100%. The description adds no new parameter-level semantics beyond the general context of storing reusable information. 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 'Save data the agent will need to reuse later' with scope across conversations and sessions. It distinguishes itself from siblings by explicitly pairing with recall and forget, making its purpose distinct among the many tools.

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

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

It provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward...' and gives concrete examples. It also names alternatives ('Pair with recall to retrieve later, forget to delete'), so the agent knows when to use the companion tools instead.

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

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

Despite rich annotations (readOnly, openWorld, idempotent), the description adds substantial non-obvious behavior: ambiguous matches return figi_candidates rather than asserting, unresolved identifiers are listed under `unresolved`, GLEIF/OpenFIGI enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. This goes well beyond what annotations alone could convey.

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

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

The description is long and dense, but nearly every clause adds operational value: examples, edge cases, degradation behavior, and identifier-source labeling are all relevant for correct use. It is not a model of brevity, but the structure with supported types and inline caveats keeps the information scannable.

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

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

With no output schema, the description carries full responsibility for explaining return behavior, and it does: identifiers are source-labelled, unresolved items appear in an `unresolved` field, ambiguous instruments return `figi_candidates`, and drug lookups return RxCUI plus brand/ingredient with citation. Input formats, edge cases, and degradation behavior are all covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance beyond the schema: it instructs callers to pass the entity name only, warns against including trailing security-class words for bonds, and clarifies the ISIN-to-LEI resolution path. This materially improves the chance of correct 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?

Description clearly states the tool resolves user-spoken names into canonical identifiers required by other tools, with a specific verb, resource, and supported entity types. It distinguishes itself from profile or comparison tools by emphasizing it is the identifier-resolution step, and includes concrete examples that make the purpose immediately recognizable.

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

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

Explicit guidance says to 'Use FIRST whenever you have a name but need an ID,' and the supported types plus accepted input formats are spelled out. It does not explicitly name sibling tools as alternatives or state when not to use it, but the usage context is clear enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it probes each entity, ranks by score, and returns a ranked list with specific output fields (score, confidence, signal density). This goes beyond the raw annotation hints, but could mention rate limits or error 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 deliver the core purpose, mechanism, use case, and return format without unnecessary words. Every clause earns its place, and the key verb and resource appear in the first clause, making it front-loaded and scannable.

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

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

With no output schema, the description correctly takes on the burden of explaining the return value ('ranked list with score, confidence, signal density per entity'). It also covers the purpose, underlying mechanism, and a concrete example use case. It doesn't discuss edge cases like invalid entity counts or API key errors, but these are minor for a read-only comparison tool.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, including the special 'first entry treated as subject' rule. The description reinforces 'your brand + N competitors' but doesn't add new semantic details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check (single-entity probe) and compare_entities by detailing the ranking and most/least recognized output, so an agent knows exactly what this tool produces.

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 concrete use case ('competitive AI-marketing audits') and quotes an example question. It also mentions that it probes with ai_visibility_check, implicitly differentiating from that single-entity alternative. However, it doesn't explicitly state when NOT to use it or compare to other sibling tools like compare_entities.

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 read-only/idempotent annotations, the description discloses partial failure degradation, a 5-30s bundlephobia latency on first measurement, the sources_failed field, and the full list of returned fields.

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

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

The description is front-loaded with the core purpose, then usage guidance, return summary, and limitations. Every sentence adds value for a dense composite tool; 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?

With no output schema, the description fully covers return fields, failure modes, timing, and scope limits. For a tool of this complexity, it leaves no operational gaps.

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

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

Schema already describes both parameters fully (package name, scoped packages accepted, version defaults to latest). The description does not add meaningfully beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies a specific composite check (adding an npm package) with a concrete verb phrase ('fans out across deps.dev... and bundlephobia'), and the return value summary distinguishes it from sibling tools like scan_competitor_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?

Explicitly states when to use ('Use whenever an agent asks...') and provides an alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already establish read-only, idempotent, open-world behavior. The description adds value by specifying the output fields (name, summary, record_count, owner/org, Feature Service url) and the open-data scope, which goes beyond the structured annotation data.

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-loads the action and resource, then states the return value and next steps. No wasted words; every phrase adds meaningful information.

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

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

For a search tool with optional parameters, no output schema, and annotations covering safety, the description is effectively complete. It explains what is searched, what is returned, and how to use the result, making it self-sufficient for an agent.

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

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

All three parameters (query, limit, org_id) have descriptions in the input schema covering 100% of them. The description's mention of 'keyword' only paraphrases the query parameter without adding any new semantic detail. Baseline of 3 is appropriate given full schema coverage.

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

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

The description uses a specific verb ('Search') and resource ('Palm Beach County GIS open geospatial datasets'), names concrete dataset categories (parcels, addresses, zoning), and clarifies its role by pointing to query_layer/layer_info for further use of the returned URL. This clearly distinguishes it from sibling tools.

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

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

The description gives clear context: it is for keyword discovery of GIS datasets. It also advises passing the returned Feature Service URL to query_layer/layer_info, which serves as a next-step guideline. However, it does not explicitly state when NOT to use this tool or mention alternatives beyond those two.

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

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

Annotations already mark it read-only and non-destructive, and the description adds substantial beyond-annotation behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and offset/score return details. This fully informs the agent of expected mechanics and edge cases.

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 tightly packed with purpose, usage, technical detail, and limitations, with no filler. It is front-loaded with the core action and immediately states the value proposition, making it easy to scan and act on.

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

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

Despite no output schema, the description explicitly states what is returned (top-N passages with character offsets and similarity scores). It also covers algorithm, windowing, truncation, and the companion tool, making it complete for a semantic search tool with rich annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the text/query semantics and gives an example query, but it does not add meaning beyond the schema descriptions. No penalty and no extra credit 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 opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It immediately distinguishes this tool from siblings like ask_pipeworx or search_datasets by emphasizing it operates on already-fetched text, and it names the output (top-N passages with offsets and scores).

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also mentions pairing with ask_pipeworx_grounded for a fetch-then-ground workflow, which provides useful context. However, it does not explicitly list when not to use (e.g., small records), so it misses the full 'when-not' piece for 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?

Despite annotations already indicating a non-read-only, non-destructive mutation, the description adds substantial behavioral context: OAuth requirement, feed-always-on behavior, SMS verification and caps, webhook signing secret returned only once, and auto-disabling after failures. No contradictions with annotations.

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

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

The description is long but densely packed with necessary information, organized by subscription type and delivery channel. The first sentence states the core purpose immediately, and each subsequent clause adds unique value without redundancy.

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

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

For a complex tool with nested objects and no output schema, the description covers return value, authentication requirements, type-specific parameters, delivery options, validation rules, and failure behavior. It is fully 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?

Schema coverage is 100%, but the description enriches every parameter with concrete examples and constraints (e.g., sec_8k item codes, polymarket_edge topic, fred_series series_id, delivery channel specifics, phone verification). It adds meaning well beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb+resource+outcome: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes subscribe from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 on when to use the tool (creating subscriptions) and details prerequisites like a Pipeworx OAuth account and verified SMS phone. However, it does not explicitly contrast with alternatives such as unsubscribe or list_subscriptions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive; the description adds meaningful context about the return structure (category-bucketed example questions with exact tool + argument shape) and the live catalog source. It doesn't contradict annotations and enriches understanding of 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 front-loaded with the tool's purpose and key usage guidance, making it approachable. The list of example queries is useful but somewhat verbose, and the single-dense-paragraph structure could be tightened. Still, every section contributes to understanding.

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

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

For an onboarding tool with no output schema, the description fully covers what it does, what it returns, how to use it, and when to use it. It also mentions the live catalog and links to related tools, making it complete for its role.

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

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

The input schema already provides full coverage for `topic` (including the allowed values and default behavior). The description only adds a few illustrative examples ("finance", "pharma", "betting") and restates the omission guidance, adding marginal value beyond the schema.

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

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

The description explicitly states the tool's role as "the onboarding entry point for an agent that just connected and wants to know what is worth asking" and lists concrete example queries. It also distinguishes itself from siblings by referencing meta-tools (ask_pipeworx, entity_profile, compare_entities) and positioning this as the first stop.

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 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 customize via the optional `topic` parameter, including omission for a broad overview.

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

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

Beyond annotations, the description reveals crucial behavior: the row is deactivated (not deleted) and historical events remain available via recent_alerts. Ownership enforcement is also disclosed, adding context not present in structured metadata.

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

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

The description is three short sentences, front-loaded with the primary action, then adding crucial nuances. No filler or repetition; every sentence carries meaningful information.

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

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

For a single-parameter mutation tool, the description covers the action, constraints (ownership), and post-condition (deactivation with retained history). Annotations handle idempotency and non-destructiveness, making this complete.

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

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

Schema coverage is 100% and the only parameter 'id' is already well-described as a subscription UUID returned by subscribe. The description adds no extra semantic detail beyond restating 'by id', so the baseline 3 applies.

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

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

The description states a specific verb ('Cancel') and resource ('a subscription by id'), clearly distinguishing its purpose from sibling tools like 'subscribe' and 'list_subscriptions'. The ownership enforcement further clarifies 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?

It explicitly states a key condition: 'you can only cancel your own subscriptions', which serves as a when-not restriction. The note about deactivation and historical events also helps an agent decide whether this tool is appropriate.

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

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

The description goes far beyond annotations by detailing the SEC EDGAR + XBRL fast path vs. grounded pipeline, defining verdicts, and explaining the critical meaning of could_not_verify and unsupported. It also warns that could_not_verify must not be shown as evidence, which is essential caller guidance.

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

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

The description is long but well-organized and front-loaded with the purpose and use case. Each section (trigger phrases, path detail, verdict list, warnings) adds necessary information, though some trimming could make it more concise.

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 thoroughly covers return values (verdicts, actual value, citation, reasoning), error semantics, and coverage boundaries. It also complements annotations by explaining openWorld behavior and the fallback pipeline.

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 (claim and tolerance_pct) with 100% coverage. The description adds extra nuance by suggesting tolerance_pct 1–2 for hallucination detection and explaining how claim wording implies tolerance, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It includes trigger phrases like 'Is it true that…' and 'fact check', and distinguishes it from general Q&A tools by focusing on factual correctness. This makes it unambiguous and differentiates it from siblings.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the two processing paths (financial vs. other claims). It provides clear context but does not explicitly name alternative tools or state when not to use it.

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