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?

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds valuable behavioral context: it routes to other tools, fills arguments, returns structured answers with citations, works on every tier, and is fast. It also notes it handles news routing. No contradiction with annotations.

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

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

The description is longer than average but every sentence provides unique value: preference guidance, scope, examples, and alternatives. It is front-loaded with the key instruction and logically structured, making it easy to skim. A minor redundancy exists in listing many example queries, but the overall structure is effective.

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

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

Despite lacking an output schema, the description explains the output format (structured answer with citation URIs) and covers the tool's role, scope, usage cues, and sibling tools. It also addresses specific domains (SEC, FDA, FRED, etc.) and provides a fallback plan for more specialized needs, making the description complete for the tool's complexity.

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

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

The schema describes all six parameters as aliases for the natural-language question, with 100% coverage. The description reinforces the expected input by providing examples and stating that the tool 'fills arguments', which clarifies that the user only supplies a question. This adds practical meaning beyond the schema.

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

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

The description clearly states the tool routes questions to one of 5,529 tools across 1,455 verified sources, fills arguments, and returns a structured answer with citation URIs. It distinguishes itself from ask_pipeworx_grounded and deep_research by specifying when each should be used.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides concrete guidance on when to step up to ask_pipeworx_grounded or deep_research. It also lists trigger phrases and examples for when to use the tool.

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

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

The description adds valuable context beyond the annotations: it discloses the experimental nature, that candidate routing improvements are enabled live during tests, and that it currently matches ask_pipeworx. It also explicitly says 'Falls back to nothing — this IS a full working router,' clarifying that it is not a lightweight fallback. This is useful behavioral information.

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

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

The description is four sentences long and each sentence serves a purpose: stating it's a beta, noting the current inactive candidate state, giving usage instructions, and confirming full functionality. It is slightly verbose but not wasteful.

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

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

The description thoroughly covers the beta relationship and usage instructions, but it does not describe the actual return value or response structure beyond referencing 'same response shape' as ask_pipeworx. Since there is no output schema, an agent encountering this tool independently would not know what the response contains.

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 covers all six parameters at 100%, documenting five aliases (q, text, input, query, prompt) plus the primary 'question' parameter. The description only says 'same arguments' and adds no meaning beyond the schema, so it does not enhance parameter understanding.

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

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

The description explicitly states this is a 'universal router' with the same 5,529 tools, arguments, and response shape as ask_pipeworx, making its function clear. It also distinguishes it from the stable ask_pipeworx by labeling it as the beta/experimental version, so it stands apart 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?

It gives direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that when no candidate is active it matches ask_pipeworx exactly, which helps decide when to use it. However, it does not explicitly state when not to use it (e.g., if stability is required), so it 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?

The description reveals substantial behavioral context beyond annotations: it promises to use 'ONLY what the tool result contains,' details the exact return schema (answer, evidence, refusal_reason, etc.), and lists possible refusal reasons. It also discloses the cost implication of one extra LLM call, which is not inferable from annotations.

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

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

The description is front-loaded with the core purpose and then efficiently packs valuable details. Every sentence contributes: return format, refusal reasons, usage guidance, and cost comparison. There is no fluff, and the length is justified by the complexity of the tool's behavior.

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

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

The description is fully complete given the absence of an output schema. It describes the success and refusal response structures explicitly, explains when refusals occur, and provides cost/use-case context. The tool's integration with ask_pipeworx's routing is also clarified, ensuring the agent knows exactly what to expect.

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

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

The schema already has 100% description coverage with the 'question' parameter and aliases. The description adds no parameter-specific meaning beyond what the schema provides. Baseline of 3 applies because the schema fully documents parameters, and the description's mentions of 'fills arguments' refers to internal routing, not the tool's own 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 purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the verb (answer with grounding), the resource (data from 5,529 tools across 1,455 sources), and explicitly distinguishes it from sibling ask_pipeworx. The tool's unique behavior of extracting answers solely from tool results and providing evidence/refusal reasons is 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?

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative for casual lookups: 'prefer ask_pipeworx for casual lookups.' This clearly defines when to use this tool versus its sibling.

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

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

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?

Annotations already declare readOnly, openWorld, idempotent, non-destructive hints, but the description goes far beyond: it discloses the findings packet structure (verbatim evidence, confidence, source, fetched_at), contradictions[], citation_uri fetchability guarantees, semantic excerpting, and expected latency (15-60s, up to 90s for thorough). This is comprehensive behavioral disclosure.

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

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

The description is long but every sentence carries unique, decision-relevant information. It is not a wall of filler—each clause adds a specific caveat or behavior. However, it is a single dense paragraph that could benefit from bullet points or clearer sub-structuring, so it is not maximally 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?

Given the tool's complexity and no output schema, the description fully covers return format, limitations, alternatives, authentication, timing, citation behavior, and depth semantics. It leaves no critical gap that an agent would need to guess about, making it complete for invocation and expectation-setting.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by elaborating on the depth parameter's behavior in the research flow: gap recovery for standard, lead-chasing for thorough, contradiction scans, and paid status for thorough. This enriches the schema's already-detailed per-depths explanations without redundancy.

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

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

The description states precisely what the tool does: grounded multi-source research across 1455 structured data sources, decomposing questions into facets and routing them to 5,529 tools in parallel. It clearly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, with examples of appropriate multi-part research questions.

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

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

Explicit 'when to use' and 'when not to' guidance is provided. It says to use ask_pipeworx for single lookups and breaking/current-news topics, and mentions that deep_research returns empty gaps[] for unstructured topics. It also notes account requirements and which depth levels are paid, giving clear alternatives.

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

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

Annotations 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?

Beyond the read-only/idempotent/non-destructive annotations, the description discloses behavioral details: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; patents soft-fail due to API sunset; GDELT-to-GNews fallback; and returns specific fields like 'up to 5' recent filings with URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph but front-loaded with user-phrase examples, then clearly enumerates the output components and caveats. Every sentence contributes useful information; however, it could be improved with line breaks or bullet lists for readability. Still, it is appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description thoroughly details return values: cik, company_name, recent_filings with URIs, fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash), patents, news fallback chain, and LEI. It also covers limitations (US public company only, no names) and the single-entity scope, making it complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%: both 'type' and 'value' are fully described in the schema, including the ticker/CIK formats and the 'names not supported' caveat. The description repeats this information rather than adding new semantic meaning, so it earns the baseline score of 3 for high schema coverage.

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

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

The description clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call,' using a specific verb (profile) and resource (US public company via ticker/CIK). It distinguishes itself from sibling tools by explicitly saying to prefer it over chaining single-pack SEC/XBRL/news lookups.

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

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

Provides explicit use cases with example queries, states 'ALWAYS PREFER' over single-pack lookups, and gives exclusion criteria: names are not supported, and if the user only has a name, 'use resolve_entity first.' This is clear when-to-use and when-not-to-use guidance with 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 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 readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds substantial context beyond those annotations: it details the response elements (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type/subtype), explains the two compatibility_warning cases, and discloses that spreads are 'mathematically meaningless' when temporal_alignment is false. This is exceptional behavioral transparency.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and each subsequent section adds dense, useful operational detail. It could be trimmed slightly, but every sentence earns its place by explaining edge cases and response semantics that would otherwise be undocumented.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It covers raw probabilities, spread calculation, compatibility warnings, temporal alignment, and skipped-category counters. It also addresses edge cases like non-equivalent bet shapes and semantically unrelated events, making it unusually complete for a read-only analytics tool.

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

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

The schema has 100% description coverage for all three parameters, giving a baseline of 3. The description adds value by explaining the mode semantics: topic auto-fetches matching events, and the explicit parameters override the mapped side. It also lists valid topic values and provides examples, going slightly beyond the schema's property 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' immediately identifying the tool's function and scope. It clearly distinguishes itself from any single-venue or generic arbitrage tool by emphasizing cross-venue comparison and the two modes (topic vs explicit ticker/slug). This is a specific, actionable description with a clear verb-equivalent and resource.

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

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

The description clearly explains the two usage modes: pre-mapped topic shortcuts and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also provides cautionary guidance: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not name sibling alternatives explicitly, but it gives enough when-to/when-not-to-use context to guide an agent.

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?

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds valuable context beyond annotations: identifiers are labelled with source, unresolved identifiers are explicitly listed, and GLEIF/OpenFIGI enrichment degrades gracefully without failing the call. It does not include a concrete example output, so a small gap remains.

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?

Well-structured with sections for supported types and degradation behavior, and the example utterances front-load purpose. It is longer than necessary ('replaces 2-3 manual lookups' is somewhat promotional), but that length is earned.

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

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

Despite lacking an output schema, the description explains what is returned per type, how unresolved identifiers are handled, and what happens when upstream services are unavailable. Omission of exact return structure is acceptable given the complexity, but a small example would make 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?

Schema covers 100% of parameters with examples, so the baseline is 3. The description enriches semantics slightly by explaining that 'type=company' returns a multi-source identity spine and 'type=drug' returns RxCUI/ingredient/brand, but this is more about return behavior than parameter syntax.

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 ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and provides multiple example paraphrases ('What's the ticker for…', 'find the CIK for…'). It clearly differentiates from sibling tools like entity_profile by focusing on identifier mapping rather than profile data.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. It also details input forms per type, but does not name alternatives or explicitly state when not to use this tool.

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

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

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.