Arcgis Glasgow

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the description doesn't need to re-assert safety. The description adds valuable behavioral context: the default model is free (Workers AI Llama-3.3-70b), passing `_apiKey` incurs direct Anthropic costs, and it discloses that the key is forwarded to api.anthropic.com. This goes beyond the annotations and helps the agent understand external dependencies and cost implications.

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 first sentence captures the core purpose and output, while the second sentence adds operational details without waste. Every clause serves a purpose: default model, cost note, return format, and use-case enumeration. It avoids fluff and is well organized.

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

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

Despite lacking an output schema, the description explicitly lists the per-model return structure ('{score, confidence, signals, raw_response}') and mentions a combined view. It covers the main behavioral aspects (read-only, external calls, cost), and the annotations cover safety. Given the moderate complexity and the presence of sibling tools, the description 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains which model is used by default ('Default model is Workers AI Llama-3.3-70b (free)'), clarifies that the `_apiKey` is passed through to Anthropic ('BYO key — you pay Anthropic directly'), and gives examples for the `entity` field. This enriches the schema's documentation without redundancy.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb ('probe'), names the resource (LLMs), and specifies the output (visibility scores). It also distinguishes itself from sibling tools like ask_pipeworx (conversational queries) and scan_competitor_ai_presence by focusing on multi-model AI visibility scoring.

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

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

The description provides concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to probe Anthropic) and clarifies the default model behavior. However, it does not explicitly state when not to use this tool or name alternative tools for related tasks, so it's not a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds valuable context about the tool's internal behavior: it routes to other tools, fills arguments, returns citations with stable URIs, mentions it handles breaking news via news feeds, and works on every tier. It doesn't disclose failure modes or edge cases, but overall it provides substantial transparency beyond annotations.

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

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

The description is appropriately sized given the tool's complexity. It is front-loaded with the core directive ('PREFER OVER WEB SEARCH'), then systematically covers how it works, when to use it, examples, and escalation paths. Every sentence serves a distinct purpose, and the structured flow makes it easy to parse.

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

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

For a highly complex meta-tool with no output schema, the description is remarkably complete. It explains the return format (structured answer with pipeworx:// citation URIs), its role as default entry point, domain coverage (SEC filings, FDA, FRED, patents, etc.), and how to step up to grounded or deep research. This properly sets expectations for the agent in most scenarios.

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

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

The schema covers 100% of parameters, but the description enriches the meaning of the 'question' parameter by offering a wide array of examples ('current US unemployment rate', 'Apple's latest 10-K', etc.) and clarifying that aliases like q, query, prompt are accepted. This helps an agent understand what constitutes a valid query.

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 what the tool does: routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with citations. It distinguishes from siblings (ask_pipeworx_grounded, deep_research) and uses a specific verb ('routes', 'returns') with a well-defined 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?

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides trigger phrases ('what is', 'look up', etc.), and gives examples. It also specifies when not to use it and directs to alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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 having annotations that declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds valuable context beyond the annotations: it explains the live comparison against the stable router, that candidates are retired based on outcome evidence, and that it currently matches ask_pipeworx exactly. This is transparent about the experimental nature and fallback behavior ('Falls back to nothing'). The description does not contradict annotations; it complements them.

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

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

The description is a single paragraph but contains multiple distinct pieces of information: beta status, identical toolset, testing harness, current equivalence to stable, usage direction, and fallback behavior. It is information-dense but not wasteful. Each sentence earns its place, though the last sentence about falling back to nothing is slightly repetitive given the context. Overall, it is appropriately sized and front-loaded with the key fact that it's a beta.

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 is a thin wrapper around ask_pipeworx, the description captures the essential context: what it is, how it differs from stable, current state, and usage. No output schema exists, but the description mentions 'same response shape' as ask_pipeworx, which is sufficient. The only gap is not explaining what the router does functionally (e.g., what kind of questions it handles), but this is inherited from ask_pipeworx and the sibling name makes it inferable.

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 schema already documents six aliases for the single 'question' parameter. The description adds no additional parameter semantics beyond saying 'same arguments' and 'same response shape' as ask_pipeworx. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx that is an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge where routing improvements are tested. However, it relies on the sibling name 'ask_pipeworx' for clarity and does not fully describe what the router accomplishes beyond that.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also conveys when it is equivalent to the stable version (no candidate active) and contrasts with ask_pipeworx as the experimental alternative. However, it doesn't explicitly state when NOT to use it or name alternatives beyond ask_pipeworx.

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, but the description goes beyond by detailing the extraction mechanism (uses ONLY what the tool result contains), the exact return shape with evidence and refusal_reason variants, and the extra LLM call cost. This adds substantial behavioral context beyond the structured 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 dense yet concise: four sentences covering purpose, routing, return behavior, refusal handling, usage guidance, and cost trade-off. Every sentence adds necessary information 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?

Despite lacking an output schema, the description fully explains the return values (answer, evidence, confidence, source, etc.), refusal reasons, and the single extra LLM call cost. It also covers when to use it vs. ask_pipeworx, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with all six parameters described as aliases for 'question' and clearly explained. The description adds that the question is used to route and fill arguments for another tool, but this is implicit from the schema's 'question in natural language' and does not materially 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 clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It differentiates from the sibling ask_pipeworx by emphasizing grounded extraction only from tool results and explicitly noting 'Same routing as ask_pipeworx' but with a stricter answer-bound behavior.

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

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

Explicit usage guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This names the alternative and clear when-to-use vs. when-not-to-use.

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

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

Annotations only declare safe read-only, idempotent, non-destructive behavior. The description goes far beyond that by disclosing the fan-out architecture, resolver contract with confidence levels, parent-event extraction, news fallback details (_fallback_attempted/_fallback_failed_reason), blocking status routes for low-confidence or closed markets, spread illiquidity warnings, and resolution-rule risk (e.g., refund_50_50). This is exceptional behavioral disclosure that gives the agent a clear mental model of what happens and what could go wrong.

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 caps-lock section headers and front-loaded purpose. Every sentence contributes useful information for a complex tool with no output schema. It could be slightly tightened—fan-out examples are extensive—but overall the density is justified by the tool's complexity and the need to convey resolver contracts, safety statuses, and risk warnings.

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 must explain return shapes, statuses, and edge cases—and it does comprehensively. It covers result.market, result.analysis, result.evidence, resolver contract fields, parent_event extraction, news fallback fields, low-confidence short-circuit, closed-market status, wide-spread tradeability, and resolution-rule risk. For a 3-parameter tool with such rich output, this is complete and empowers correct invocation and interpretation.

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

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

Schema description coverage is 100%, so all three parameters are already documented: market (slug/URL/question), depth (quick/thorough), and include_raw (false recommended). The description does not add materially new parameter semantics beyond what the schema provides; it largely restates the accepted input forms and uses fan-out examples that are more behavioral than parameter-specific. Baseline of 3 is appropriate because the schema carries the parameter documentation load.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by framing this as a comprehensive research/evidence-gathering tool, not just an edge calculator. The input formats and output shape are concrete and actionable.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides rich guidance on interpreting results, like checking market_match_confidence before trusting analysis and checking cancellation_rule before sizing bets. However, it does not explicitly name alternatives or exclusions (e.g., when NOT to use this and use polymarket_arbitrage instead), so it falls short of a full 5.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses concrete behaviors: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). It also notes the parallel-call optimization, adding significant value beyond the annotation 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 information-dense without fluff. Each sentence earns its place: triggers, usage preference, per-type details, sorting behavior, return format, and efficiency claim. It is front-loaded with the core purpose and structured logically, making it easy to parse.

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

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

For a tool with two modes of operation and no output schema, the description provides comprehensive context: what is compared, which metrics are pulled, how results are ordered, what output format looks like, and how fiscal years are handled. It also addresses the bounded input size (2–5). This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already covers parameter basics (enum for type, array constraints for values) with 100% coverage. The description adds richer semantics by explaining what each type retrieves (e.g., 'LATEST 10-K revenue + net income + cash + long-term debt' for companies, 'FAERS adverse-event counts...' for drugs) and gives concrete examples. This goes beyond the schema but does not fully describe every edge case, so a 4 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 ('compare') and resource ('companies or drugs') and clearly scopes it to side-by-side comparison of 2–5 entities in one parallel call. It lists example natural-language triggers and explicitly contrasts with sequential single-pack lookups, which distinguishes it 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8–15 sequential lookups. This provides a clear directive for when to use the tool and implicitly highlights why it's superior for comparison tasks, though it doesn't name specific alternative tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals account requirements, paid tier for 'thorough', return packet contents (gaps[], contradictions[], hop, citation_uri), latency expectations (15-60s, up to ~90s), and semantic excerpting behavior. No contradiction with annotations exists.

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

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

The description is long but front-loaded with the most critical constraint (account required) and every sentence provides unique operational information. It could be better organized into clear sections, but the density is justified given the tool's complexity.

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

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

With no output schema, the description fully specifies the return findings packet, gaps[], contradictions[], citation_uri, hop field, and expected latency. It also explains fallback behaviors and limitations, making the tool's behavior and results completely clear for an agent.

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

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

Schema coverage is 100% with detailed descriptions for both 'question' and 'depth'. The description reiterates depth behaviors and adds that 'thorough' requires a paid plan, but this is a minor operational note. The description does not meaningfully augment the schema's already rich parameter documentation.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with open-web search and single-lookup tools, distinguishing it from siblings like ask_pipeworx. The verb 'research' plus the resource scope makes the purpose unmistakable.

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

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

Explicitly specifies when to use ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also provides a sign-in requirement with a fallback: 'If you are not signed in, use ask_pipeworx 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 and idempotent behavior. The description adds value by disclosing the return format ('top-N most relevant tools with names, descriptions, and full input schemas') and noting that results are ready to call directly with no second schema lookup, which is useful behavioral context beyond annotations.

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

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

The description is front-loaded with the core purpose, uses a compact list of covered data domains, and each sentence contributes to understanding the tool's behavior and use. The domain list is lengthy but informative, and the overall structure is clear and efficient.

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

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

Given the tool's simplicity and fully described schema, the description covers when to use it, what it returns, and the depth of results. With no output schema, the explicit description of return format (top-N with full schemas) gives the agent sufficient expectations for invocation and follow-through.

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

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

The input schema has 100% description coverage, including aliases and limits. The description does not add significant parameter-level semantics beyond what the schema already provides; it repeats the 'describing the data or task' idea but offers no new detail. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Find tools') and enumerates the domains it covers (SEC filings, FDA drugs, FRED, etc.), which clearly distinguishes it from sibling tools like search_datasets or validate_claim. The purpose is unambiguous and identity is well-defined.

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 usage context ('Use when you need to browse, search, look up, or discover what tools exist') and tells the agent to 'Call this FIRST' when many tools are available, which strongly signals precedence over other search tools. It doesn't explicitly name alternatives, but the 'first' guidance effectively directs selection.

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

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

Beyond the read-only/idempotent annotations, the description discloses behavioral details: the USPTO API sunset with soft-fail behavior, GDELT→GNews fallback, the 'up to 5' filing limit, and the sorted fundamentals output. It does not over-explain or contradict annotations.

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

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

The description is dense but well-organized, using a single paragraph with clear lists. It front-loads with user intents and then covers outputs and limitations. While lengthy, every sentence contributes necessary information for such a complex multi-source tool.

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

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

With no output schema, the description fully enumerates all return fields (CIK, company_name, recent_filings, fundamentals, patents, news, LEI), specifies limits and source fallbacks, and covers input restrictions. It is self-sufficient for an agent to understand and invoke the tool.

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

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

The input schema already provides full descriptions for both parameters, including examples ('AAPL', '0000320193') and the note that names are unsupported. The description repeats this information without adding new semantic detail, so the baseline 3 for 100% schema coverage 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 opens with concrete query examples and explicitly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by specifying it should be preferred over chaining single-source 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?

It clearly instructs when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells users with only a name to use resolve_entity first, providing a clear exclusion.

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, readOnlyHint=false, and idempotentHint=true, so the description's 'Delete' is consistent. It adds the 'clear sensitive data' context and pairing note, but does not disclose additional behavioral details such as behavior for nonexistent keys or side effects. This provides some value beyond annotations, warranting a 3.

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

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

The description is two sentences, front-loaded with the action, and every phrase contributes value—purpose, usage conditions, and tool relationships. No redundancy or unnecessary words.

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

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

For a single-parameter delete tool with strong annotations (destructive, idempotent) and no output schema, the description fully covers purpose, usage, and relationships. The context signals confirm low complexity, so no further information is 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?

The input schema has 100% coverage with 'Memory key to delete' directly describing the key parameter. The description adds 'previously stored memory' context but no extra syntax or format details beyond the schema. Baseline 3 applies because the schema carries the semantic load.

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 action: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and the mention of pairing with remember and recall distinguishes it from complementary tools by establishing its unique destructive role.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, but does not explicitly state when not to use the tool or name alternative 'instead' tools, so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds valuable context by disclosing the process (fetches, extracts, emits) and the exact output format ('single text blob ready to drop at site-root/llms.txt'), which goes beyond the annotations.

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

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

The description is three concise sentences: main purpose, process/output, and use cases. Each sentence adds distinct value, with no filler or repetition.

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

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

For a two-parameter tool with full schema coverage and no output schema, the description is complete: it explains the input URL, the optional max_links, the emitted markdown format, and the intended deployment location. 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 coverage is 100%: both 'url' and 'max_links' have clear descriptions. The tool description does not add parameter-specific detail beyond what the schema provides, 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 starts with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL.' It clearly explains what the tool does (fetches page, extracts title/description/key links, emits markdown) and stands distinct from any 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?

It lists concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use. It does not name explicit alternatives or exclusions, but the use cases are specific 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 already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by detailing the response contents (fields, geometry type, record count, capabilities), giving agents a clear expectation of what the tool returns. No behavioral traits are hidden, and there is 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 one compact sentence that front-loads the action and resource, then packs the key output details into a clean list. Every word earns its place; no filler or redundancy.

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

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

For a simple single-parameter read tool, the description is sufficiently complete: it states the tool's purpose, lists the returned information, and benefits from strong annotations and schema coverage. It doesn't mention potential errors (e.g., invalid URL) or rate limits, but these are not critical for a read-only schema fetcher.

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

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

The input schema already provides 100% coverage for the single 'url' parameter, including an example and format hint. The description simply repeats 'by url' without adding extra detail about URL construction, validation, or edge cases. Baseline score of 3 is appropriate because the schema handles the burden.

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' and identifies the resource as 'an ArcGIS Feature/Map Service layer's schema'. It enumerates the exact outputs (fields, geometry type, record count, capabilities), making it clear this is a metadata inspection tool distinct from data querying siblings like query_layer.

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 no guidance on when to use this tool versus alternatives. While it implies using it when you need schema information, it doesn't mention that query_layer should be used for actual data retrieval, nor does it note any prerequisites or exclusions. Sibling tools like query_layer and search_within exist, but the description doesn't help choose between them.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the exact return format and the self-scoping nature ('caller's'), which helps the agent anticipate the tool's output. No contradiction exists.

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

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

The description is two concise sentences, front-loaded with the verb and resource, then gives the return fields and usage context. Every clause adds information with no padding or repetition.

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

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

Given the tool's simplicity (one optional parameter) and no output schema, the description is complete: it explains the return values, the default scope (active only), and the intended use cases. Nothing important is missing for a list tool.

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

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

Schema description coverage is 100% because the single parameter include_inactive has a description in the schema. The tool description does not add parameter-specific details, but the baseline of 3 applies as the schema carries the full burden.

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 ('List') and clearly identifies the resource ('the caller's active subscriptions'). It also enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count), which distinguishes it 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?

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implicitly contrasts with subscribe/unsubscribe, giving the agent actionable 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?

With all annotations set to false, the description carries full behavioral disclosure. It reveals that filing without an account returns a claim_token, that the token can be used later to check resolution status, that rate-limiting is 5 per identifier per day, that it is free, and that the team reads digests daily. This goes beyond what annotations provide and sets clear expectations for side effects.

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 efficiently structured, front-loading the core purpose and then covering usage, exclusions, token behavior, and rate limits in a logical flow. Every sentence contributes, though a few could be trimmed without losing value. Still, it remains highly readable and well-organized.

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

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

Despite having no output schema, the description fully covers the tool's purpose, usage triggers, exclusion criteria, token-based follow-up, rate limits, and integration context with Pipeworx. For a feedback tool with 4 parameters and nested objects, the description provides all necessary operational details. It is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage context for parameters, particularly claim_token ('pass it back later... to read whether it was fixed') and message ('Describe the issue in terms of Pipeworx tools/packs—don't paste the end-user's prompt'). This elevates the parameter semantics above the baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by focusing on feedback rather than research or queries. The purpose is immediately 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 explicitly enumerates when to use the tool: for bugs, feature requests, data gaps, and praise. It also provides a clear exclusion rule—'if the tool came from a different MCP server... file it with that server instead'—and names the alternative action. This is exemplary usage 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 cover read-only/idempotent safety. The description adds meaningful operational context: self-aggregating from CF analytics-engine, no PII, and cache freshness (5min-1h). This goes beyond the static 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 front-loaded with the core purpose, followed by bulleted use cases and a compact footer on provenance/caching. Every sentence adds 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 single-parameter read-only tool with no output schema, this description covers purpose, inputs, use cases, data source, privacy, and cache behavior. It is fully sufficient for an agent to decide and invoke the tool.

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

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

Schema covers 100% of the single 'window' parameter, so baseline is 3. The description adds semantic guidance on shorter vs longer windows, helping the agent choose the right enum value, which warrants a 4.

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

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

Description clearly states it 'Returns the top tools, top packs, and total call volume' over a window, with a specific resource and verb. It also distinguishes itself from sibling tools by focusing on aggregate AI-agent call patterns ('what other AI agents are calling on Pipeworx').

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 'Useful for' section explicitly lists three concrete scenarios (discovering hot data sources, confirming canonical choice, checking use-case alignment). It does not name alternative tools or exclusion criteria, so it falls short of a 5.

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

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

Beyond annotations (readOnlyHint, etc.), the description reveals complex internal behavior: defaults, partition placeholder filtering, semantic similarity threshold (≥0.30 Jaccard), and fill check with realizable vs theoretical edge, advising 'do not trade it' if realizable_edge_pp ≤ 0. 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?

Despite length, the description is well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check). Every sentence adds critical information—no filler. Front-loaded with the primary purpose.

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

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

Given no output schema, the description compensates by specifying response fields (opportunities[] with gap_pp, suggested_trade, etc.) and covers edge cases like placeholder fraction >20% returning null. It also references the sibling tool for custom sizing, completing the usage picture.

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 only gives brief parameter descriptions, but the tool description adds deep semantics: event mode walks child markets and runs partition checks; topic mode searches related events, flattens markets, and runs comparator on the union. Concrete examples and mode recommendations are provided, far exceeding schema info.

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

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

Description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', a specific verb+resource+method. It clearly distinguishes from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly instructs when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also names an alternative for custom sizing: 'use polymarket_fill_risk'.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond that: caching at KV level, response structure by_segment, diagnostics, and warnings like 'your edge may already be in the price.' 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?

Despite being long, the description is densely informative and well-structured with headings (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence adds value, and core purpose is front-loaded.

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

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

For a complex tool with 9 parameters and no output schema, the description covers response structure, diagnostics, model families, configuration knobs, and caching. It is exceptionally complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the 'TRADEABLE-EDGE KNOBS' section and detailing nuances like min_partition_leg_kelly (parent-level Kelly is always 0, so min_kelly doesn't apply). This adds genuine value over the schema.

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

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

The description clearly states a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings by detailing three model families and its purpose as a discovery tool for 'what should I bet on today.'

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 frames when to use it: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides exclusions (e.g., Fed bets excluded from ranking) and tradeable-edge knobs that act as usage 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 establish read-only, idempotent, and non-destructive behavior, but the description adds substantial context: 60-day snapshot TTL, dependence on when snapshotting was enabled, that decay numbers use daily closes net of default slippage, and that gaps in snapshot_dates indicate days no scan occurred. This goes far beyond the annotation hints and helps the agent set expectations about data completeness and interpretation.

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

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

Though lengthy, the description is well-organized into purpose, args, RESPONSE structure, and LIMITS. Each sentence carries meaningful information, and the purpose is front-loaded. The structured breakdown of output fields (tracked, expired, snapshot_dates) makes it easy for an agent to know what to expect.

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 clearly enumerates the response fields: tracked[] with trend/decay metrics, expired[] with lifespan, and snapshot_dates[]. It also covers operational limits (TTL, snapshot start) and the meaning of gaps. This is complete for an agent to invoke and interpret results correctly, especially given the tool's moderate 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 input schema already covers 100% of parameters with descriptions, including defaults and clamps. The description's 'Args: days (lookback, default 14, max 30), window (snapshot family, default "1wk")' essentially repeats this information without adding new semantic nuance beyond what the schema provides. Thus, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from 'daily polymarket_edges snapshots', and explicitly states the question it answers: 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges (which likely surfaces current edges) by focusing on historical persistence and decay analysis.

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 when to use the tool by contrasting a 'fresh wide edge' with a '3-week-old wide edge' and noting the latter is 'wide for a reason nobody is willing to take'. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide this is for historical edge trend analysis rather than live edge discovery.

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

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

While annotations already indicate a safe read-only operation (readOnlyHint=true, destructiveHint=false), the description goes well beyond them by detailing behavior: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and exposes basket-mode internals (per-leg fill detail, thin_legs, forced_directional_risk). It also surfaces a critical behavioral risk: partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations exists.

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

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

The description is fairly long but front-loaded with the core purpose. It is well-structured with clear labels for SINGLE-MARKET and BASKET modes, and each sentence carries substantive information. While it could be trimmed slightly, the length is proportionate to the tool's complexity (two modes, multiple parameters, risk behavior). It earns a 4 rather than a 5 because some redundancy exists (e.g., size_usd semantics are repeated in schema and description), but it remains highly readable.

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

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

This tool has no output schema, so the description must explain return values—and it does comprehensively for both modes. It covers parameter interpretation, mode selection, return fields, edge cases (thin_legs, forced_directional_risk), and the operational context (when to use before arbitrage/edge trades). Given the tool's complexity (4 optional params, two modes, no output schema), the description is exceptionally complete without requiring the user to guess behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that one of market or event is required, which the schema (all optional parameters) does not convey. It also reinforces the meaning of size_usd in both modes ('max spend on buys, target proceeds on sells' and 'settlement notional S (shares per leg; each share pays $1)') and explains the default side behavior for baskets. This adds semantic nuance beyond the schema, justifying a 4 rather than a 3.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool's role from siblings like polymarket_arbitrage and polymarket_edges by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' The two modes (single-market and basket) are explicitly named and detailed, leaving no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500—theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position.' It also clarifies mode selection by explaining that market is for single-market mode and event is for basket mode, and describes the distinction between single-market and basket parameter semantics. This is clear, actionable usage guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It discloses the response structure (leg-by-leg prices, spread), safety fields (compatibility_warning with two specific cases), temporal_alignment semantics, and skipped_cross_type/subtype counters. It even explains when spreads are mathematically meaningless. This adds substantial transparency beyond the annotations.

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

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

The description is long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, but it is verbose and dense with jargon (e.g., 'range_bucket point-in-time vs cumulative_threshold touch-anywhere'). It is front-loaded with the purpose, but could be slightly 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?

Without an output schema, the description carries the full burden of explaining the return values and edge cases. It covers the response fields, compatibility warnings with two distinct cases, temporal alignment, and skipped counters. It also warns about the rarity of tradeable spreads, making it highly complete for a complex tool. This is a strong example of comprehensive documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the mode logic: 'topic' is a pre-mapped shortcut, and explicit kalshi_event_ticker/polymarket_event_slug override the mapped sides. This clarifies how the parameters interact, which is beyond the schema descriptions. However, it doesn't add syntax or format details beyond what the schema already provides, so a 4 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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly states what the tool does and distinguishes it from siblings like polymarket_arbitrage (which likely deals with Polymarket internal arbitrage) and polymarket_edges. It also elaborates on two modes, reinforcing a focused 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 provides clear usage context by explaining the two modes (topic shortcuts vs. explicit pairings) and when each is appropriate. It also gives a strong caveat: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which sets expectations. However, it does not explicitly name alternative tools or state when not to use this tool versus others, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavior by stating 'Returns attribute rows (and geometry)' and demonstrates a sampling approach. 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?

Four short sentences, front-loaded with the main purpose. Each sentence delivers a distinct piece of information (purpose, parameters, return, and tip) with no redundancy or filler.

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

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

For a 6-parameter tool with no output schema, the description covers the essential aspects: what it queries, key parameters, return content, and a practical sampling strategy. It does not mention error handling, but the rich annotations and full schema coverage compensate.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the description's restating of 'SQL-like where' and 'comma-separated out_fields' adds little beyond the schema. The sampling tip is a usage guideline rather than parameter semantics.

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

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

The description clearly states the tool's action: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It specifies the resource (layer) and differentiates from siblings by mentioning 'from search_datasets' and focusing on attribute fetching.

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 by linking to search_datasets and gives a concrete usage tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly name alternative tools or state when not to use this tool, so no exclusions are given.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses scoping behavior detailed by 'anonymous IP, BYO key hash, or account ID', and clarifies the two operational modes (get-value vs. list-all). This adds meaningful behavioral context beyond the 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 compact and front-loaded. The first sentence captures the core purpose, followed by usage context, scoping, and sibling tool relationships. Every sentence adds value with no redundancy.

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

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

Given the simple parameter set (one optional string), rich annotations, and no output schema, the description fully covers purpose, usage, scoping, and integration with related tools. It answers likely agent questions about when and how to invoke the tool, making it complete for its 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?

With 100% schema coverage, the baseline is 3. The description goes further by providing concrete examples of key values (target ticker, address, research notes) and reinforcing that omitting the key lists all entries. This enriches the semantic meaning of the 'key' parameter without duplicating schema data.

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 dual purpose: retrieve a previously saved value or list all saved keys when the key is omitted. It specifies the verb 'retrieve' and 'list' with a concrete resource (memory values), and distinguishes it from siblings by explicitly referencing 'remember' and 'forget'.

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

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

The description provides explicit use cases: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes'. It also explains when to use it ('without re-deriving it from scratch') and how it relates to alternative tools ('Pair with remember to save, forget to delete'), offering clear context and an implicit exclusion.

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

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

Annotations already indicate safe read-only behavior, and the description adds valuable behavioral details: the return payload structure (source, citation_uri, raw event), mark_read semantics, and feed persistence. It doesn't contradict annotations and enhances understanding beyond the 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 sentences, front-loaded with the purpose, and every sentence adds value—purpose, return fields, filters, mark_read effect, and alternative endpoint. No wasted words or redundant restatements of the title.

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 provides necessary return value information (source, citation_uri, raw payload). It also covers filtering and polling behavior. It does not mention unread_only, but that parameter is fully described in the schema; overall coverage is adequate for the tool's simplicity.

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

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

With 100% schema coverage, the baseline is 3, but the description adds enrichment: it gives a concrete type example ('sec_8k'), specifies ISO format for 'since', and explains the effect of mark_read on future calls. This goes beyond the schema's terse parameter descriptions.

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

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

The description opens with a specific verb 'Pull fired events' and identifies the resource as 'your subscription feed,' making the tool's purpose immediately clear. It also differentiates from siblings like list_subscriptions (which lists subscriptions) and recent_changes by focusing on alerts/events from subscriptions.

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

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

The description provides practical usage context: it explains polling works fine, offers an alternative HTTP endpoint for scripts, and clarifies filtering and mark_read behavior. It doesn't explicitly name sibling alternatives, but the context is clear enough that an agent would know when to use this tool versus others for reading alerts.

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

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds valuable behavioral context: it fans out to SEC EDGAR, GDELT/GNews with fallback rules, and USPTO with a soft-fail due to API sunset. It also explains the return structure (changes[], total_changes, citation URIs) beyond what annotations provide. 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 but front-loaded with example queries and core purpose. It packs in sources, fallbacks, parameter formats, return details, and an alternative tool—all relevant. Each sentence earns its place, though a slight trim could improve focus.

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

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

Despite having no output schema, the description fully explains return values (changes[] grouped by source, total_changes, citation URIs). It covers external API dependencies, failure modes, parameter options, and when to use a sibling tool, making it complete for an agent to invoke correctly.

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

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

While schema coverage is 100%, the description enriches parameter meaning with concrete examples: `since` accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring; `value` is exemplified with 'AAPL' and CIK '0000320193'. This goes beyond mere schema descriptions.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months' and provides concrete example queries like 'What's new with X' and 'updates on Acme'. It also explicitly differentiates from the sibling entity_profile, which retrieves static profiles, making the 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 gives explicit use cases through example queries and states when to use an alternative: 'Use entity_profile instead when you want the static profile...' This provides clear when-to-use and when-not-to-use guidance, plus the fallback behavior for news sources.

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

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

Annotations already indicate a non-read-only, idempotent write operation. The description adds valuable behavioral context beyond annotations: memory is scoped by the agent's identifier, and persistence varies by authentication status (persistent for authenticated users, 24 hours for anonymous sessions). This helps the agent understand the retention semantics. It doesn't explicitly discuss overwrite behavior, but idempotentHint already covers that.

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

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

The description is concise and well-structured. Three sentences deliver the core purpose, usage triggers, persistence model, and companion tools without redundancy. It is front-loaded with the verb 'Save' and each sentence adds necessary information.

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

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

For a simple tool with only two parameters and no output schema, the description is remarkably complete. It covers what the tool does, when to use it, how memory persists, and how to interact with related tools. Combined with the schema and annotations, the agent has all necessary context to use the tool correctly.

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

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

The input schema already fully documents both parameters (key and value) with examples and descriptions, so the schema coverage is 100%. The description adds only that the pair is scoped by the agent's identifier, which is useful context but does not significantly alter parameter understanding. Baseline 3 is appropriate since the schema handles parameter semantics.

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

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

The description clearly states the tool's purpose: saving data for later reuse across conversations or sessions. It distinguishes itself from sibling tools by explicitly pairing with recall and forget, and it gives concrete examples of when to use it (resolved ticker, target address, user preference, research subject).

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with practical examples. It also explains persistence conditions (authenticated vs. anonymous) and names companion tools (recall, forget), giving the agent clear decision-making context for when to invoke 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 (readOnlyHint, idempotentHint, destructiveHint) already establish safety, and the description adds valuable behavioral details beyond that: unresolved identifiers are explicitly marked under `unresolved`, LEI/FIGI enrichment degrades gracefully with EDGAR results still returned, and internal cascading is disclosed. No contradiction with annotations.

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

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

The description is front-loaded with examples and a clear purpose statement, and each section (company, drug, degradation) adds essential information. However, it is verbose and the company type description is a dense run-on sentence; could be more scannable with bullet points, preventing a 5.

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

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

With no output schema, the description carries the burden of explaining return behavior, which it does by listing returned identifiers, source labels, unresolved handling, and graceful degradation. It does not specify exact response structure or pagination, but it provides enough 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 both parameters. The description adds helpful examples (AAPL, 0000320193, ozempic) and clarifies what resolution returns for each type, but much of this mirrors the schema. It earns a 4 for reinforcing input formats and linking them to expected outputs, though the schema does the heavy lifting.

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

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

The description opens with concrete query examples then clearly states the verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes from siblings via 'Use FIRST whenever you have a name but need an ID,' making its role as an initial lookup explicit.

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 an explicit when-to-use instruction ('Use FIRST whenever you have a name but need an ID') and details supported types and accepted input formats. However, it does not explicitly state when-not-to-use or name alternatives beyond implying that other tools consume these identifiers, so it falls short of a 5.

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

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

The description discloses behavioral details beyond the annotations, such as probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized entities. It also specifies the return fields (score, confidence, signal density). This adds value beyond the readOnlyHint and idempotentHint annotations, making the tool's operation transparent.

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

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

The description is concise and well-structured: three sentences that front-load the core purpose, then explain the process and use case. Each sentence adds meaningful information without redundancy.

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

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

For a multi-entity comparison tool, the description covers purpose, process (probing with ai_visibility_check), ranking behavior, and expected output fields. With full schema coverage and clear annotations, no critical information is missing 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 description coverage is 100%, with each parameter (models, _apiKey, context, entities) fully described in the schema itself. The description does not add parameter-specific information beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the mechanism (probes each entity with ai_visibility_check), the ranking behavior, and the output (ranked list with score, confidence, signal density). This distinguishes it from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic comparison).

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

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

The description provides a clear usage context: 'Useful for competitive AI-marketing audits' with a concrete example ('does Claude know about us as well as our competitors?'). However, it does not explicitly state exclusions or mention alternatives, though the sibling tool list and the phrase 'side-by-side' imply 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses partial failure behavior, the 5-30s first-measurement latency from bundlephobia, and the sources_failed field. This adds meaningful operational context without contradicting any annotations.

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

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

The description is well-structured and front-loaded with the core purpose, then usage, returns, limitations, and failure handling. Every sentence earns its place; no fluff or redundancy despite being slightly long for a composite tool.

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

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

For a complex tool with no output schema, the description thoroughly covers return summary fields, per-advisory detail, links, alternative versions, ecosystem constraints, timeout behavior, and partial failure semantics. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal new meaning beyond restating defaults and the npm ecosystem context; it mostly reinforces what the schema provides. 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 purpose: a composite 'should I add this npm package' check that combines deps.dev and bundlephobia data. It specifies the verb ('scan'), the resource ('npm package'), and the unique composite nature, distinguishing it from any 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?

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small"...' It also gives a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' pointing to an alternative for non-npm packages.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive hints, so the safety profile is covered. The description adds value by listing the exact return fields (name, summary, record_count, owner/org, Feature Service URL), which tells the agent what to expect, and clarifies that results are open geospatial datasets.

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

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

Two sentences with no filler: the first states the action and scope, the second lists return fields and the next-step workflow. Every clause 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 search tool with no output schema, the description covers purpose, input scope, return structure, and follow-up action. It lacks explicit handling for edge cases like pagination or empty results, but given the simple parameter set, this is a complete enough description.

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

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

The input schema already provides 100% coverage, describing query, limit, and org_id with examples. The description's mention of keyword search aligns with the query parameter but adds no new syntax or format details 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 identifies the tool as a search over Glasgow City Council GIS open geospatial datasets by keyword, listing specific dataset categories. It also distinguishes itself from sibling tools by noting that the returned Feature Service URL should be passed to query_layer/layer_info, making its role in the workflow explicit.

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

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

The description provides explicit downstream guidance: after finding a dataset, pass its URL to query_layer or layer_info. This positions search_datasets as the discovery step, with clear context on when to use it versus the sibling tools that operate on a specific dataset.

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 substantial behavioral details beyond the annotations: it describes the embedding model (BGE-base-en), the windowing strategy (500-char overlapping windows), the return format (character offsets and similarity scores), and the 200K character cap with truncation flagged. This goes well beyond the readOnly/openWorld/idempotent hints and gives the agent a clear model of what will happen.

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, each earning its place: the first defines the core action, the second gives usage rationale, the third connects to a sibling tool, and the fourth provides technical constraints. It is front-loaded with the primary purpose and wastes no 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?

With no output schema, the description must explain what the tool returns, and it does: 'top-N passages with character offsets and similarity scores.' It also covers limits (200K char cap, truncation flag) and parameter expectations. For a 3-parameter tool, this is a complete and self-contained description.

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

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

The schema already covers 100% of parameters, so the baseline is 3. The description adds value by giving concrete examples for the 'text' parameter ('e.g. a SEC 10-K body, an article, a long tool result') and framing it as 'text you already pulled.' It also adds the truncation nuance for the text parameter. This is more than baseline but not a complete overhaul, hence a 4.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings by explaining it operates on text already pulled, and it explicitly pairs with ask_pipeworx_grounded for a different workflow. The purpose is unambiguous and 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names an alternative workflow with ask_pipeworx_grounded, showing how this tool fits into a larger pipeline. This provides clear when-to-use and context for alternatives, though it doesn't state explicit exclusions, it implies them (small records should just be put in the prompt).

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

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

Annotations already indicate non-read-only, idempotent, non-destructive behavior. The description adds substantial context: account requirements, anonymous/BYO limitations, phone verification, SMS caps, and email/sms delivery specifics. It even mentions webhook auto-disable in the schema. No contradictions with annotations.

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

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

The description is dense but every sentence provides critical information. It could be more structured with bullets, but for a tool with multiple types and delivery options, the length is justified and the main purpose is front-loaded.

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

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

Given the tool's complexity and lack of an output schema, the description covers prerequisites, supported types, delivery channels, return value, and limitations. It provides enough detail for an agent to correctly select and invoke the tool, even leaving webhook details to the schema where appropriate.

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 goes far beyond: it provides concrete examples for each subscription type (e.g., items:['5.02'] = officer change) and delivery channel constraints (phone verification, 10/day cap). This significantly enriches the schema's bare parameter descriptions.

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

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

The description clearly states the verb ('Create'), the resource ('subscription'), and the target ('live-data event stream'), distinguishing it from sibling tools like unsubscribe or list_subscriptions. It also enumerates supported subscription types, 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 provides clear context: it creates subscriptions, requires an OAuth account, and explains that the feed is pulled via recent_alerts or a registry URL. It doesn't explicitly contrast with sibling tools like list_subscriptions, but the usage context is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: the response structure (category-bucketed examples), the ability to focus by topic, and that it draws from a live catalog of thousands of tools. This goes well beyond the annotations without contradicting them.

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

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

The description is long but well-structured and front-loaded with common user queries. Each sentence contributes useful information: purpose, output, usage modes, and when to use it. It could be slightly trimmed, but every part 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?

The description fully covers what the tool does, how to call it, what it returns, and when to use it. With no output schema, it transparently describes the output format (category-bucketed questions with tool and argument shapes). The annotations cover safety and idempotency, so nothing critical is missing.

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

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

Schema coverage is 100% for the optional `topic` parameter, but the description adds value by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omission gives a cross-category spread. This enhances the schema's basic description.

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

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

The description clearly states the tool's function: it is 'the onboarding entry point' that 'returns category-bucketed example questions' with the exact tool and argument shape. This distinguishes it from siblings like discover_tools and ask_pipeworx by focusing on guided suggestions rather than direct answers.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes how to invoke with no arguments or with a topic. It does not explicitly state when not to use it, but the context and alternatives (e.g., meta-tools) are clear enough.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds critical behavior: ownership enforcement ('you can only cancel your own subscriptions'), the deactivation mechanism ('the row is deactivated (not deleted)'), and the impact on historical events ('stay available via recent_alerts'). This fully explains the non-destructive, idempotent nature without contradicting annotations.

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

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

Two sentences, front-loaded with the core action. The details (ownership, deactivation, recent_alerts) are relevant and add depth without wasting words. No redundant information or filler.

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

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

For a single-parameter tool with no output schema, the description covers all essential aspects: the action, the input constraint (ownership), the state change (deactivation), and the impact on related data (recent_alerts). It is sufficiently complete for an agent to invoke the tool correctly and anticipate results.

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

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

The schema covers the parameter fully ('Subscription id (uuid) returned by subscribe'), so baseline is 3. The description adds the ownership constraint ('you can only cancel your own subscriptions') which clarifies that the id must belong to the calling user. This extra semantic context justifies one point above baseline.

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

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

The description uses a specific verb ('Cancel') with a clear resource ('a subscription') and identifies it by 'id'. It clearly distinguishes itself from sibling tools like subscribe (create) and list_subscriptions (list) by focusing on the cancellation action.

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

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

The description provides clear context on when to use the tool (when you have a subscription id you own and want to cancel it) and implies constraints (ownership, deactivation vs. deletion). It does not explicitly name alternative tools, but the effect description ('deactivated not deleted') helps the agent reason about consequences. Lacks explicit 'when not to use' guidance, so not a 5.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description goes far beyond that by disclosing the two-pipeline architecture (SEC EDGAR/XBRL fast path vs. grounded fallback), the exact verdict vocabulary, citation behavior, and the critical error semantics for could_not_verify ("the check did not happen... must not be shown as one"). This is exemplary 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 longer than average but every section serves a purpose: user-phrasing triggers, routing logic, verdict semantics, and caller warnings. It is front-loaded with examples and clearly structured, though a couple of phrases (e.g., "natural-language claim verification against authoritative sources") are slightly repetitive. Dense but efficient overall.

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 explains what callers receive: the verdict list, actual value with citation, and reasoning. It also covers the nuanced failure modes (could_not_verify vs. unsupported) and the routing decision for company-financial vs. other claims. Given the tool's complexity, this is a complete and well-rounded specification.

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

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

Schema coverage is 100% for both parameters, and the description adds real meaning with concrete claim examples and explains the tolerance_pct default and its purpose ("set 1–2 for hallucination detection"). While the schema already describes the parameters well, the description's added context about tolerance overriding claim wording and the fast-path delta math provides extra value beyond the schema.

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

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

The description opens with explicit natural-language triggers ("Is it true that…", "fact check") and states its core function: natural-language claim verification against authoritative sources. It also differentiates itself from siblings by specifying the company-financial SEC path vs. general grounded pipeline and by noting it replaces 4–6 sequential calls, making the tool's role unmistakable.

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

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

The description clearly states when to use the tool ("Use whenever the agent needs to check whether something a user said is factually correct") and explains routing rules for financial vs. other claims. It also gives important caller guidance about verdict meanings (could_not_verify vs. unsupported). However, it doesn't explicitly name a sibling tool as an alternative or state when NOT to use this tool, so it's not quite a 5.

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