Arcgis Victoria

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

The description adds significant behavioral context beyond annotations: default model is free, Anthropic requires BYO key (cost implication), returns per-model {score, confidence, signals, raw_response} plus combined view. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description does not contradict them.

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

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

The description is two well-structured sentences. The first sentence states purpose and output, the second adds key details on defaults and return format. Every sentence earns its place with no waste.

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 4 parameters (all documented in schema), no output schema, and no nested objects, the description provides a useful summary of return shape (per-model + combined view) and special behavior (free vs paid). It is adequate but could optionally detail the combined view structure.

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

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

Schema coverage is 100% with all parameters described. The description reinforces that default model is free and _apiKey is for Anthropic, but does not add meaning beyond the schema. Baseline score of 3 is appropriate since the schema carries 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 clearly states the tool probes LLMs for awareness of an entity and scores visibility (0-100) per model. It specifies the verb 'probe' and 'score', the resource 'LLMs' and 'visibility', and distinguishes from sibling tools like scan_competitor_ai_presence and entity_profile by its multi-model scoring approach.

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 usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model usage and optional API key for Anthropic. While it does not explicitly state when not to use or contrast with siblings, the context is clear enough for an agent to decide 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 already declare readOnly, openWorld, and idempotent hints. The description adds behavioral context about routing, filling arguments, returning pipeworx:// citation URIs, and being fast/works on all tiers. This goes beyond the annotations, though it doesn't discuss potential failure modes or rate limits.

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

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

The description is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and efficiently organizes guidance into use cases, examples, and alternatives. While somewhat long, every sentence serves a purpose without redundancy.

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

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

For a complex routing tool with no output schema, the description is remarkably complete: it covers scope, examples, alternatives, default status, and return format (structured answer with citations). This fully equips the agent to invoke it appropriately.

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; each parameter (mostly aliases) is described, and the main 'question' parameter explains its natural language use and aliases. The description adds examples of queries but no additional parameter semantics, so the baseline 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 function: it routes factual questions to 5,417 tools across verified sources and returns structured answers with citations. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

The description explicitly says to prefer this over web search for factual questions, provides trigger phrases and examples, and specifies when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). 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?

Beyond the annotations (read-only, idempotent, etc.), the description discloses crucial behavioral traits: it is a live beta with candidate routing improvements enabled during tests, currently matches ask_pipeworx exactly because no candidate is active, and is a full working router with no fallback. This transparently sets expectations for possible behavioral drift when candidates are tested.

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 tool's identity, and efficiently covers purpose, current state, usage, and reliability. Each sentence adds distinct value—identity/scope, live status, and usage guidance—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 beta router of this complexity, the description covers the essential context: what it is, how it relates to ask_pipeworx, when to use it, and its current operational state. It defers response shape and tool list to ask_pipeworx, which is acceptable given the sibling reference, though standalone output details are not provided.

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 complete documentation for the single 'question' parameter and its aliases (100% coverage). The description adds no parameter-specific meaning beyond noting 'same arguments' as ask_pipeworx, which is redundant with the schema. Annotations and schema carry the semantic load, so a baseline of 3 is appropriate.

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

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

The description immediately and specifically identifies the tool as 'Beta version of ask_pipeworx' and characterizes it as an 'identical universal router' with the same 5,417 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and sibling tools by explicitly noting the experimental routing improvements and its role as the 'experimental edge.'

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 this tool: 'Use it exactly like ask_pipeworx when you want the newest routing,' and names the stable router as the comparison baseline. It does not explicitly say when not to use it, but the context clearly implies that stability-seeking users might prefer ask_pipeworx, so the guidance is strong though not exhaustive.

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 critical behaviors beyond annotations: it returns evidence as a verbatim quote, provides an explicit refusal with specific refusal_reason values, and states it costs an extra LLM call. This is valuable context not covered by 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 longer than two sentences but every part is functional: purpose, routing, return structure, refusal handling, use cases, and cost trade-off. It is front-loaded with the key concept, though it could be tightened slightly by omitting the enumerated refusal_reason list which is also visible in the return explanation.

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

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

Given no output schema, the description fully explains return values and failure modes. It covers selection criteria, behavior, cost, and output format, making it complete for an agent to decide when and how to 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 coverage is 100% with all parameters being aliases for the single 'question' parameter. The description adds no parameter-specific detail, but the schema already fully documents each alias. This meets the baseline without adding extra 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: a hallucination-resistant answer mode that extracts answers using only tool-returned data. It explicitly distinguishes from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding extraction and refusal 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 provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' It names the alternative and gives a clear rule for when to choose this tool 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?

The description discloses extensive behavioral traits beyond annotations, including fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, market status handling, and cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and supplemented with critical operational context.

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

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

The description is verbose and densely packed with information over multiple paragraphs. While it front-loads the core purpose, the extensive detail on classifiers, examples, response shapes, and edge cases could be better structured for conciseness. It earns its length but sacrifices brevity.

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

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

Given the tool's complexity (multiple classifiers, fan-out, varied response scenarios), the description is remarkably thorough. It covers all critical aspects: market matching, parent events, news fallback mechanisms, safety features, illiquidity, cancellation rules. Without an output schema, the description adequately addresses return values and edge cases.

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

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

All three parameters (market, depth, include_raw) have schema descriptions, but the description adds significant meaning: input types for market, default and effect for depth, and a detailed explanation for include_raw (response size trade-offs). This enriches semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question), the process (resolve, classify, fan-out), and output (evidence packet + comparison). This is a specific verb+resource with detailed scope, distinguishing it from siblings by its unique functionality.

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 scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly state when NOT to use this tool or suggest alternatives among the sibling tools, which would improve 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: for type='company' it pulls latest 10-K financials from SEC EDGAR/XBRL with off-calendar fiscal year handling; for type='drug' it pulls FAERS adverse events, FDA approvals, trial counts; results are sorted by primary metric; returns paired data with citation URIs. No contradiction.

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

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

The description is moderately lengthy but packs useful information in a structured way using example phrases and bullet-like enumeration. Every sentence adds value; it is not overly verbose. Could be slightly more concise, but effective.

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

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

Despite lacking an output schema, the description adequately covers return values (paired data + citation URIs). It explains the two data types, entity count limits, and efficiency advantage. No missing critical information for a tool of this complexity.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by providing examples of values (tickers/CIKs for company, drug names) and constraints (2-5, maxItems 5). It also explains the data sources per type.

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

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

The description begins with example phrases like 'Compare X and Y' and 'X vs Y', clearly indicating the tool's purpose. It states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This specific verb+resource description distinguishes it from siblings like entity_profile (single entity lookup).

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides example use cases (comparing, ranking, head-to-head). It does not explicitly list when not to use, but the context is clear enough to guide the agent.

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

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

Beyond the readOnly/idempotent hints, the description discloses account gating, internal decomposition/parallel routing, output schema ('findings packet: verbatim evidence + confidence + source + fetched_at + citation'), gap reporting ('explicit gaps[] ... never invented'), contradiction scanning for standard/thorough, semantic excerpting, and expected latency (15-90s). This rich context makes execution behavior predictable and creates no contradiction with annotations.

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

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

The description is a dense, info-packed paragraph with no wasted words—every sentence contributes (account, alternative tools, methodology, output shape, gaps, depth behaviors, latency). However, it is quite long and could benefit from bullet points or section breaks to aid scannability, especially for an agent parsing key decision signals quickly.

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 values, and it does thoroughly (findings packet fields, citation URIs, gaps[], contradictions[], hop field). It also covers edge cases (unsigned-in users, breaking-news topics) and performance characteristics, leaving no major gaps for a complex tool.

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

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

The schema already covers both parameters at 100%, including detailed enum descriptions. The description adds the critical constraint that 'thorough' requires a paid plan and reinforces that 'question' may be broad/multi-part. This is meaningful extra context but not drastically more than the schema's own depth explanation.

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: 'Grounded multi-source research across Pipeworx's 1405 STRUCTURED data sources' and immediately contrasts with sibling tools (e.g., 'this is NOT open-web search', 'For a single lookup use ask_pipeworx'). It also provides concrete example questions ('compare X and Y's regulatory + financial exposure'), making the tool's scope 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 says when to use this tool ('Best for broad/multi-part questions over structured data'), when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'), and gives a clear fallback for unsigned-in users ('If you are not signed in, use ask_pipeworx instead'). It also explains depth-level selection and prerequisites (paid plan for 'thorough').

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. The description adds important behavioral details: returns top-N relevant tools with full input schemas and curated examples, ready to call without a second lookup. No contradictions.

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

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

The description is concise and well-structured: it states the purpose upfront, lists domains, explains the return format, and gives usage guidance. 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?

Given no output schema, the description adequately explains the return value (top-N tools with names, descriptions, schemas, examples) and usage context. It could mention default limit (20) but the schema does, so completeness is high.

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

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

The input schema covers 100% of parameters with descriptions for each, including aliases. The description lists the same aliases, which adds minimal value beyond the schema. However, the schema includes example values, so the description's contribution is limited.

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

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

The description clearly specifies 'Find tools by describing the data or task' and lists concrete domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that either provide direct answers or perform other actions.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' giving strong usage context. It does not include explicit when-not-to-use scenarios, but the directive is clear.

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, etc. The description adds operational context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), soft-fails for patents, and returns specific fields like recent_filings with URIs. No contradiction with annotations.

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

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

Description is fairly long but well-structured: starts with example queries, then primary purpose, then details of sources and return fields, then caveat about name resolution. Every sentence adds value, though could be slightly tighter.

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

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

Despite no output schema, the description lists all return fields (cik, recent_filings, fundamentals, patents, news, LEI). Covers data sources, fallback behavior, and prerequisites. Fully adequate for a read-only info tool with rich annotations.

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

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

Schema coverage is 100%, baseline 3. Description adds nuance: value must be ticker or zero-padded CIK, names not supported. Also clarifies type is only 'company' for now. Provides usage examples and constraints beyond 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 it provides a 'full cross-source profile of a US public company in ONE parallel call'. It uses specific verbs ('research', 'brief me', 'profile') and distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name resolution.

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 tells when to use: when user asks for a 'holistic view'. Also tells when not to use: if only a name is provided, instructs to use resolve_entity first. Mentions that patents part may fail after May 2025, setting expectations.

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 denote destructive and idempotent; description adds usage context but not deeper behavioral details like permanence or cascading 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?

Two sentences, front-loaded with action, minimal waste.

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

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

Covers purpose, usage, and pairing; lacks error handling or behavior on missing key, but sufficient for a simple 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 covers key parameter fully; description reiterates but adds no new 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?

Clearly states it deletes a memory by key, and with siblings 'remember' and 'recall', its role is distinct.

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 describes when to use (stale context, task done, clear sensitive data) and pairs with related 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?

Annotations already declare safe read-only, idempotent, non-destructive behavior. The description adds process details (fetches page, extracts title/description/links, emits markdown) and output format (single text blob for site-root/llms.txt), which goes beyond annotations without contradicting them.

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

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

Extremely concise: two sentences and a bullet list. Front-loaded with core purpose. Every sentence adds value with no repetition or fluff.

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

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

Given low complexity (2 params, no output schema, no nested objects), the description fully covers what the tool does, what it produces, and where to use the output. No gaps 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%, so schema already documents both parameters well. The description does not add new semantic information beyond what is in the schema, meeting the baseline expectation.

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

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

Clearly states it generates an llms.txt file for any URL, specifically for AI crawlers. The verb 'generate' matches the tool name, and the resource is well-defined. Among siblings, no other tool has similar functionality, so it distinguishes itself.

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 lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. Provides context for when to use, but does not mention when not to use or alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds specific return content (fields, geometry type, count, capabilities), providing full transparency. No contradiction.

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

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

Single sentence, front-loaded with the verb 'Get' and resource, compact and efficient. No redundant information.

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

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

For a single-parameter tool with comprehensive annotations, the description covers all essential outputs (fields, geometry type, count, capabilities). No output schema needed as description suffices.

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 a clear description of the 'url' parameter. The tool description does not add extra parameter details beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves schema info (fields, geometry type, record count, capabilities) from a layer URL. It uses specific verbs and resources, distinguishing it from sibling tools like 'query_layer' which likely query data.

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

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

Usage is implied from the description: use to get metadata. However, no explicit guidance on when to use vs alternatives (e.g., 'query_layer') or when not to use. The context suggests differentiation but lacks explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe behavior. The description adds value by listing the exact return fields and clarifying that only active subscriptions are returned by default, with an optional include_inactive parameter. No contradictions.

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

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

Two sentences, no wasted words. The first sentence defines the action and output; the second provides usage context. Well-structured and front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It explains purpose, return fields, default filter (active), and practical use cases (review, find id to cancel). Nothing essential 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% with a clear description for the single optional parameter 'include_inactive'. The description does not add any new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clearly states the verb 'List' and resource 'the caller's active subscriptions'. Specifies the exact return fields (id, type, params, etc.), distinguishing it from siblings like subscribe/unsubscribe which modify 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?

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear context and alternative behaviors, implicitly contrasting with subscribe/unsubscribe.

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 all annotations being false, the description discloses important behavioral traits: rate limited to 5 per identifier per day, free and doesn't count against tool-call quota, the team reads digests daily, and feedback affects roadmap. This goes well beyond the annotations.

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

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

The description is a single dense paragraph that could be more scannable with bullet points, but every sentence carries essential information. It is front-loaded with the core purpose and uses compact phrasing like 'broken, missing, or needs to exist' to convey a lot in few 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 feedback submission tool with no output schema, the description fully covers the necessary context: what it does, when to use, what to include, the scope restriction, rate limit, and cost. The agent has all information needed to invoke it correctly.

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

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

Schema description coverage is 100% and already explains each parameter's meaning. The description adds an important guideline for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also clarifies the scope of the context object by stating 'ONLY for tools served by this Pipeworx connection.' This adds value beyond the schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also distinguishes itself from sibling tools by emphasizing it is feedback for the Pipeworx team, not a data retrieval or research tool.

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

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

The description explicitly provides when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well'), and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). This gives clear guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds caching details (5min-1h), data source (CF analytics-engine), and privacy (no PII). 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?

Five sentences with clear front-loading: first sentence states core functionality, then bullet-pointed use cases, followed by data source and caching info. No 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?

Tool has low complexity (one optional param, no nested objects). Description covers purpose, return items, windows, caching, and privacy. Without an output schema, it could specify the exact structure of the returned top tools/packs list, but the current detail is sufficient for an agent to interpret the response.

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

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

Schema has 100% coverage for the single parameter 'window' with enum and description. The description adds value by explaining the trade-off between short and long windows ('surfaces what's hot right now vs steady-state demand'), which goes beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over time windows. It specifies the verb 'returns' and the resource 'what other AI agents are calling on Pipeworx'. This distinguishes it from siblings like 'ask_pipeworx' or 'discover_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?

Three explicit use cases are given (discovering hot data sources, confirming canonical tool, aligning with common needs). It does not include when not to use it or alternatives, but the context is sufficient given the sibling tool list.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds substantial behavioral context: semantic anchor for cross-event pairing, partition filter logic, fill check mechanics, and response structure. 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 quite long but well-structured with clear sections for each mode. Every sentence adds value, though slightly more verbose than necessary. Front-loads the core purpose and alternatives well.

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

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

Given the complexity of the tool (multiple modes, fill check, semantic anchor) and lack of output schema, the description comprehensively explains the response structure and all key behaviors. An agent has sufficient information 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?

Although schema coverage is 100%, the description adds significant meaning beyond parameter names. It explains what each parameter does, provides example values, describes the different modes and their outputs, and clarifies recommended usage.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and details their specific functions. This differentiation is crucial given sibling tools like polymarket_edges and polymarket_edge_tracker.

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

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

Explicitly guides the agent: 'Call with NO args for a trending_scan', recommends event mode for specific markets, and topic for cross-event scanning. Also warns against trading when fill check shows non-realizable edge, providing clear when-not situations.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context beyond annotations: detailed model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation with slippage and Kelly sizing, caching behavior (1h KV cache keyed on knobs), and diagnostic outputs. 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 very detailed and well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). However, it is quite verbose, containing many specific numeric thresholds and technical details that could be trimmed for conciseness. While informative, it sacrifices brevity.

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 (9 parameters, no output schema), the description is remarkably complete. It explains the response structure (top-level by_segment, fed_candidates, _diagnostics), every field in the opportunities (edge_pp_net, kelly_fraction, market stats, 24h move warning), and the role of each knob. No significant gaps for an agent to 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% (all 9 parameters documented in input schema). The description adds meaningful context for many parameters, such as explaining min_liquidity and max_spread_pp as 'Tradeable-edge filters' and detailing min_partition_leg_kelly's role. This adds value beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and explicitly says it is 'Built for 'what should I bet on today''. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by highlighting its three-model-family approach and focus on Pipeworx-based edge detection.

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

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

The description gives explicit guidance on when to use the tool ('discover opportunities without paging hundreds of markets') and includes constraints like Fed bets being excluded and Knobs for filtering. However, it does not directly compare to sibling tools or state when NOT to use this tool in favor of an alternative, which keeps it from a top score.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant detail: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), computation of trend and decay, and limitations (60-day TTL, daily closes, not intraday). 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 verbose but every sentence contributes meaning. It front-loads the core question and provides structured return fields. Could be slightly more concise, but overall efficient for the complexity.

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

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

With no output schema, the description fully explains the response format (tracked[], expired[], snapshot_dates[]) with field details. It also covers limits (60-day TTL, snapshot start) and computation nuances. Complete for a complex telemetry tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying default and max for days, and explaining the meaning of window families ('1wk'). It also gives a concrete example of window values, aiding understanding beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It explicitly answers the key question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical behavior rather than raw edges.

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

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

The description provides clear context on when to use the tool: to differentiate between fresh and persistent edges. It implies usage for historical trend analysis but does not explicitly state when not to use or name alternatives. The sibling tool list gives context but description lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context like walking the ladder, returning verdicts (clean/degraded/cannot_fill), and warning about forced directional risk from partial fills. No contradiction.

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

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

The description is lengthy but well-structured with bold headings for SINGLE-MARKET and BASKET modes. It is efficient given the complexity of the tool, though could be slightly more concise with bullet points.

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

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

No output schema is provided, so the description must and does thoroughly explain return values for both modes, including detailed fields like top_of_book, vwap_fill_price, slippage_pp, and per-leg fill detail. It also covers risk 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?

Schema coverage is 100%, baseline 3. The description adds value by explaining default behavior for side in basket mode and different interpretations of size_usd for single-market vs basket, plus clamping limits.

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

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

The description clearly states that the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It details both single-market and basket modes with specific actions and return values, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risks of not using it, such as thin books and partial fills converting arb into directional positions.

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 goes far beyond by detailing compatibility_warning with two distinct cases, temporal_alignment, skipped_cross_type/subtype counters, and when spreads are meaningless. 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 dense but well-structured, front-loading the main purpose and then detailing modes, response fields, and safety warnings. Every sentence adds value, though some sections (e.g., skipped counters) could be slightly more streamlined.

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

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

Given the complexity of the tool and absence of an output schema, the description fully covers the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It ensures an agent understands the rich output without needing additional documentation.

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

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

Schema coverage is 100% with proper descriptions. The description adds value by listing the 10 pre-mapped topics for the topic parameter and providing examples for explicit parameters. It clarifies the relationship between topic and explicit modes, aiding parameter selection.

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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage which focus on internal markets. Two modes are explicitly defined, adding specificity.

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 explains when to use each mode (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics currently return compatibility_warnings, advising against assuming tradeability. However, it does not explicitly name alternative tools for cases where this tool is unsuitable.

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 readOnlyHint, idempotentHint, destructiveHint, covering safety. Description adds that it returns attribute rows and geometry, and mentions defaults, but does not detail auth needs or rate limits.

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

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

Two concise sentences with an example hint. No waste, every sentence adds value: states purpose, key parameters, and a usage tip.

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, description mentions returns 'attribute rows (and geometry)' which is adequate for a query tool. Lacks details on pagination or error handling, but overall sufficient given annotations and schema coverage.

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

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

Schema coverage is 100% with each parameter described. The description reinforces SQL-like nature and gives example usage, but adds limited additional meaning beyond 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 states the tool queries an ArcGIS Feature/Map Service layer by URL, specifying SQL-like parameters. It distinguishes from siblings like search_datasets (for discovery) and layer_info (for metadata) by focusing on data retrieval.

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 hints like using where='1=1' and out_fields='*' for sampling, but does not explicitly state when to use this tool over siblings. The context implies after finding a layer via search_datasets, this tool queries its data.

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?

Description adds beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and behavior when key omitted. Annotations already indicate read-only and idempotent; description confirms and adds scope info. No contradictions.

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

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

Three sentences, front-loaded with action, no wasted words. Every sentence earns its place.

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

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

Given low complexity (1 param, no output schema), description covers purpose, usage guidance, behavioral scope, and pairing with siblings. Fully sufficient for an agent.

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

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

Only one parameter with 100% schema coverage. Description repeats schema info ('omit to list all keys') and adds context about origin ('previously saved via remember'). Meets baseline for well-covered schema but adds minor value.

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

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

Description uses specific verbs 'retrieve' and 'list' with clear resource 'value previously saved via remember' and 'all saved keys'. Distinguishes from sibling tools '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?

Explicitly describes when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Provides examples of use cases. Mentions pairing with remember/forget but does not explicitly state 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 already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details beyond annotations, such as the effect of setting 'mark_read:true' to update read status for subsequent calls, and the format of returned data. No annotation contradiction.

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

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

The description is concise (4 sentences) with no wasted words. The first sentence immediately states the main purpose, followed by details on return values and filtering options. It is well-structured and front-loaded.

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

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

Given no output schema, the description adequately outlines the returned fields (source, citation_uri, raw payload). It covers the 5 optional parameters and their effects. One minor gap: it doesn't specify how 'limit' interacts with 'mark_read', but overall it is sufficiently complete for a simple retrieval 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?

All 5 parameters have descriptions in the schema (100% coverage), but the description adds context beyond the schema: it explains that 'mark_read' flags events as read to affect future calls, and that 'since' is an ISO timestamp. This enhances understanding of parameter interactions.

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 specific verbs ('Pull fired events') and clearly identifies the resource ('subscription feed'). It details the returned fields (source, citation_uri, raw payload), setting it apart from sibling tools like 'list_subscriptions' or 'recall'.

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

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

The description explicitly states that polling works fine and mentions an alternative endpoint ('GET registry.pipeworx.io/alerts.json') for scripts and dashboards, guiding when to use the tool vs. external access. However, it does not explicitly contrast with sibling tools like 'list_subscriptions' or 'subscribe'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context about data sources, fallback logic, parameter formats, response structure, and the patent API sunset issue. No contradiction.

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

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

The description is well-organized with example queries upfront, followed by functional details. While every sentence adds value, it could be slightly more concise without losing clarity.

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 the returned structure (changes[] grouped by source, total_changes count, citation URIs). It also addresses edge cases (patent soft-fail, fallback) and provides clear usage guidance. Highly complete.

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

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

Schema description coverage is 100%, but the description adds extra meaning: relative date formats like '7d', '3m', '1y', typical monitoring window '30d' or '1m', and that 'value' accepts ticker or CIK. This goes beyond the schema.

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

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

The description clearly states the tool returns a change feed for a company in a time window, covering SEC filings, news, and patents. It uses specific verbs and resources, and distinguishes from the sibling tool '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 provides example queries, explains when to use this tool versus 'entity_profile', and outlines fallback behavior (GDELT→GNews) and limitations (patent soft-fail).

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

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

The description adds significant behavioral context beyond annotations: key-value scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. It also clarifies that the operation is idempotent (overwriting same key) and not destructive, consistent with annotations.

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

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

The description is four concise sentences, each adding value. It is front-loaded with the core purpose, then provides usage guidance, behavioral details, and paired tools. No wasted words.

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

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

The description is complete for a simple key-value store with no output schema. It explains persistence, scoping, and pairing with recall/forget. It could mention the return value (likely confirmation or the stored value) but is sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds usage examples (e.g., keys like 'subject_property', values as text) but does not provide additional semantic meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the action ('save'), resource ('data'), and scope ('across this conversation or across sessions'). It distinguishes from sibling tools like recall 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 explicitly tells when to use the tool: 'when you discover something worth carrying forward'. It provides concrete examples (resolved ticker, target address, user preference) and pairs with recall/forget for alternative actions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that each call 'cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups,' which explains internal complexity 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 well-structured with examples, use-case statement, and detailed type breakdowns. It is comprehensive without being verbose, though slightly more could be trimmed (e.g., the repeated citation URI phrasing).

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

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

Despite no output schema, the description fully explains return values for each supported type (e.g., ticker + CIK + company_name + citation URI for company; RxCUI + ingredient + brand + citation for drug). It covers all parameter meanings and usage, leaving no gaps for the agent.

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

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

Schema coverage is 100%, but the description greatly enriches meaning by providing examples for each supported type (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company) and explaining what is returned for each type, which the schema alone does not detail.

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 clear examples like 'What's the ticker for…' and explicitly states it resolves names to canonical identifiers. It distinguishes from sibling tools by recommending use 'FIRST whenever you have a name but need an ID.' Supported entity types and their outputs are clearly listed.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to invoke. It does not explicitly exclude scenarios or name alternatives, but the unique purpose is well-defined.

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, idempotentHint), the description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This provides valuable context that annotations alone do not cover.

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: two sentences plus a parenthetical use-case example. It is front-loaded with the primary action and purpose. No redundant or unnecessary content.

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

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

Given the tool's complexity (4 params, no output schema), the description covers process (probes, ranking), output structure (ranked list with fields), and use case. Annotations cover safety. The description is complete for an agent to understand 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?

All parameters have schema descriptions (100% coverage), but the description adds meaning by explaining the first entity is treated as the 'subject' and the rest as competitors, and that models defaults to workers-ai. This goes beyond the schema, clarifying how parameters interact.

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 verb (Compare) and the resource (AI visibility). It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility and ranking.

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: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It implies when to use this tool vs single-entity checks, but does not explicitly state when not to use or name alternatives beyond the implication.

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 as readOnly, idempotent, etc. Description adds that partial failures degrade gracefully, bundlephobia can take 5-30s on first measurement, and sources_failed will list if it times out. Also details return structure.

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?

Description is dense but well-organized; front-loaded with core purpose. Slightly verbose but every sentence adds value.

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

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

Despite no output schema, description lists all return fields (summary, advisories, links, versions). Covers limitations, timing, and partial failure handling. Complete for a composite 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 parameters. Description adds that scoped packages like @types/node are accepted for 'package' and that 'version' defaults to latest when omitted.

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 a composite check for npm packages combining deps.dev and bundlephobia data, with specific verb+resource. It distinguishes from siblings which are unrelated tools.

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

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

Explicitly says 'Use whenever an agent asks is X safe/popular/small or what does adding lodash cost me'. Also clarifies NPM ecosystem only, with alternatives for other ecosystems mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the return structure (name, summary, record_count, owner/org, url) and downstream guidance, but no additional behavioral traits like rate limits or pagination. This is adequate given the annotation coverage.

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-load the purpose and resource, then provide a concise list of return fields and a usage hint. Every sentence earns its place with no extraneous information.

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

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

Given 3 parameters with 100% schema coverage, no required params, and no output schema, the description provides the necessary output structure and usage guidance. It is complete for an agent to use the tool effectively.

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 detailed property descriptions for query, limit, and org_id. The description does not add new parameter semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Search') and resource ('City of Victoria GIS open geospatial datasets'), and lists example categories like parcels and zoning. It distinguishes from sibling tools by mentioning downstream tools (query_layer and layer_info) for further use.

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 explains that the result includes a Feature Service url to be passed to query_layer or layer_info, providing a clear usage flow. It does not explicitly exclude other sibling tools but gives a strong implicit recommendation.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds embedding model (BGE-base-en), similarity measure (cosine), window size (500-char overlapping), character cap (200K chars) with truncation flag, and output details (offsets, scores). No contradictions.

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

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

The description is a single well-organized paragraph, front-loaded with the core action, then usage guidance, output features, pairing information, and technical details. Every sentence adds value with no fluff.

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

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

Given the tool's complexity (semantic search, pairing with another tool, technical constraints) and absence of output schema, the description fully covers purpose, parameters, usage, behavior, limitations, and related tools. It is complete.

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

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

Schema coverage is 100% with good descriptions for all parameters. The description does not add significant new semantic information beyond the schema; it reinforces purpose but provides no critical extras. 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 performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and output details (passages with offsets and scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description explicitly says to use when the record is too big for the prompt and mentions an alternative approach using ask_pipeworx_grounded for grounding. This provides clear when-to-use and alternative 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 indicate idempotentHint=true and destructiveHint=false. The description adds significant behavioral context: it creates a mutable subscription, returns an id, details delivery channels (feed, email, SMS, webhook) with constraints (10/day cap, webhook signing secret), and notes the requirement for a Pipeworx OAuth account. No contradictions.

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

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

The description is a single paragraph that front-loads the main purpose. It covers all necessary details without excessive verbosity, though the nested examples make it slightly longer than necessary. Still, it earns its space.

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

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

Given the tool's complexity (multiple subscription types, nested params, delivery channels), the description is comprehensive. It explains each type's params, delivery options, constraints, and important notes (OAuth, phone verification). No output schema exists, but the description explicitly states the return value (subscription id).

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

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

Input schema has 3 parameters with 100% description coverage. The description adds meaningful examples and constraints for each type-specific params object (e.g., sec_8k items, polymarket_edge topic) and delivery options (webhook signing, SMS verification). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 context on when to use the tool (setting up subscriptions for specific types like sec_8k, polymarket_edge, etc.) and mentions requirements (Pipeworx OAuth account, phone verification for SMS). It does not explicitly state when not to use it, but the covered conditions are clear.

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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context: returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. No contradictions.

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

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

The description is slightly long but front-loaded with common user questions and purpose. Every sentence adds meaningful information, and the structure is clear. A minor trim could improve conciseness without losing value.

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

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

Given the annotations (read-only, idempotent, open-world) and single-parameter schema, the description is fully complete. It explains the return format, parameter behavior, and use cases, leaving no ambiguity despite the lack of an output schema.

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

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

Schema coverage is 100% (one parameter fully described). The description adds value by explaining the optional topic parameter's purpose (focus area) and the effect of omitting it (full spread list), listing example values. This goes beyond the schema's minimal 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 returns category-bucketed example questions to help users explore Pipeworx capabilities. It lists alternative user intents (e.g., 'give me ideas', 'getting started') and distinguishes itself from siblings as the onboarding entry point.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do', provides two invocation patterns (no arguments vs. with topic), and mentions learning meta-tools. This gives clear when-to-use guidance versus siblings.

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

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

Description adds ownership enforcement and deactivation (not deletion) beyond annotations (idempotentHint, destructiveHint). No contradiction with annotations.

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

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

Two sentences, each adding essential information: action then constraints. No 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 simple 1-param tool with annotations and no output schema, description covers purpose, ownership constraint, and deactivation effect. Lacks details on error handling but adequate.

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

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

Schema covers 100% of parameter descriptions (id is required and described as 'Subscription id (uuid) returned by subscribe'). Description adds minimal extra context about ownership over id.

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

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

Clearly states 'Cancel a subscription by id' – specific verb and resource. Distinct from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement (you can only cancel your own subscriptions), which guides proper usage and implies 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?

Disclosures beyond annotations: describes dual backend (financial vs other claims), return values (verdict, value, reasoning), and that it replaces multiple steps. Annotations already indicate read-only, idempotent, non-destructive, and open-world. No contradictions. Description adds useful behavioral context.

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

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

Front-loaded with purpose and examples, then explains behavior and return format. Some redundancy (e.g., listing query patterns twice) but overall efficient and well-structured. Slightly longer than minimal, but every sentence adds value.

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

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

No output schema, so description must describe return value—it does so clearly (verdict, actual value with citation, reasoning). Covers both claim types, explains tolerances, and mentions the tool replaces multiple steps. Fully sufficient for the given complexity.

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

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

Schema coverage is 100%, and the description adds significant value: explains tolerance_pct overrides implied tolerance, default derived from wording (capped at 5%), and provides claim examples. This fully compensates for the schema's brief descriptions.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with specific examples of user queries. It distinguishes between financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), making the purpose unambiguous and differentiating it from siblings.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of claim patterns and mentions it replaces multiple sequential calls. Could be improved by explicitly mentioning when not to use or suggesting alternative tools for non-claim queries.

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