Arcgis Adamscounty

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

Adds meaningful behavioral context beyond annotations: default model selection, BYO API key with direct billing to Anthropic, and the per-model return structure. This is exactly the kind of extra context agents need to understand cost and authentication implications.

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

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

Three sentences, front-loaded with the core function, then default behavior, return format, and use cases. No redundant wording.

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

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

For a read-only probe tool with full schema coverage, the description explains the return shape, cost behavior, and use cases. No output schema is needed because the description covers the key result fields.

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 all parameters, but the description adds the concrete default model name ('Workers AI Llama-3.3-70b') and reinforces the dependency between `models` and `_apiKey`, helping the agent reason about configuration.

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

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

The description opens with a specific action ('Probe one or more LLMs for what they know...') and clearly defines the output (visibility score 0-100 per model). It distinguishes itself from sibling tools like ask_pipeworx by focusing on visibility scoring rather than Q&A, and mentions concrete use cases.

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

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

Provides clear context for when to use ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly mention alternatives or exclusions relative to sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and repeatability. The description adds useful context: the tool routes to one of 5,563 tools, fills arguments automatically, and returns 'structured answer with stable pipeworx:// citation URIs'. However, it doesn't clarify whether this is always synchronous, or behavior when no source matches, but annotations plus description provide strong transparency.

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

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

The description is moderately long but well-structured: begin with preference, then capabilities, with usage patterns, examples, and escalation paths. Each sentence adds information. Minor redundancy in listing multiple example domains, but overall earns its length.

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

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

No output schema exists, but the description mentions 'structured answer with stable pipeworx:// citation URIs', providing some return format insight. Sibling tools and escalation paths are clearly referenced. The high schema coverage (100%) and annotations reduce missing context. A clear specification of the exact response structure (e.g., JSON fields) would make it complete, but it's still strong.

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 all parameters are already explained in the schema. The description adds value by explaining the primary parameter's natural language nature, listing alias names, and providing three concrete examples. This reduces ambiguity beyond what the schema alone offers.

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 specifies the verb 'ask' and the unique resource 'Pipeworx', and clearly distinguishes it from web search by listing specific data domains (SEC filings, FDA drugs, etc.). It contrasts with sibling tools like ask_pipeworx_grounded and deep_research, establishing a clear use case.

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 ('PREFER OVER WEB SEARCH') and provides clear examples of query types. It also specifies when NOT to use it, directing to ask_pipeworx_grounded for verbatim evidence and deep_research for broad multi-part questions, offering a complete decision framework.

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 valuable context: candidate routing improvements are enabled live when under test, no candidate is active now, it matches ask_pipeworx exactly, and it is a full working router with no fallback. 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 informative and well-structured, front-loading key information (beta, identical, candidate routing) and then explaining current status. It is slightly verbose but every sentence adds value. Could be tighter but still 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?

Given the complexity (6 alias parameters, no output schema, rich annotations), the description covers the beta nature, current state, usage guidance, and behavioral traits. It does not explain return format, but since it matches ask_pipeworx exactly, that is implied. Lacks error handling details but adequate for selection.

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 6 parameters, all aliases for 'question', with 100% schema description coverage. The description does not add any additional meaning beyond what the schema already provides. Baseline 3 is appropriate since schema covers all parameters.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,563 tools, arguments, and response shape. It explicitly distinguishes from its sibling ask_pipeworx by noting candidate routing improvements and current exact match. Specific verb+resource with sibling differentiation.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It implies when not to use (stable routing) and clarifies fallback behavior ('falls back to nothing — this IS a full working router, just the experimental edge').

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, destructiveHint. The description adds significant behavioral context: it costs an extra LLM call, returns a structured response with evidence and refusal reasons, and uses only the tool result (no external knowledge). 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 well-structured, front-loading the core purpose and use case. It covers behavior, return format, refusal reasons, cost, and alternatives in a compact, information-dense manner. Every sentence contributes value without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return format including fields like answer, evidence, confidence, source, and refusal reasons. It also explains the mechanism (picks from 5,563 tools across 1462 sources) and when to use alternatives. The tool is complex, but the description prepares the agent thoroughly.

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

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

Schema description coverage is 100% with clear descriptions for each parameter alias. The description adds context about the question being used for routing and fetching, but the schema already covers the parameter semantics adequately. A score of 3 is appropriate as the description adds marginal value beyond the schema.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results. It distinguishes from sibling ask_pipeworx by specifying it's for when answers must be quoted or cited, and explicitly lists use cases like financial verdicts, legal claims, etc.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also gives when-not-to-use: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off of one extra LLM call. This is exemplary.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals critical behavioral details: parallel fan-out, resolver contract with confidence levels, status codes for low-confidence or closed markets, news fallback handling, illiquid spread warnings, and cancellation rule parsing. This is substantial extra 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 very long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the core purpose, but could be trimmed for conciseness without losing essential 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 there is no output schema, the description thoroughly explains return values, resolver contract, parent event extraction, news fields, safety statuses, and resolution rules. It even covers edge cases like de-indexed markets and flat-50¢ void settlements, making it highly complete 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?

Schema description coverage is 100%, and the parameter descriptions already cover the market input format, depth default, and include_raw behavior. The description adds examples and fan-out scenarios but does not significantly extend parameter semantics beyond what the schema provides.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', with a specific verb and resource. It also gives explicit use cases ('should I bet on X') that distinguish it from sibling tools focused on arbitrage or edge tracking.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear context for when to use the tool. It does not explicitly state when not to use it or name alternative tools, which keeps it slightly below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds substantial context: it specifies data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. No contradictions with annotations; it enriches safety and operational understanding.

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

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

The description is longer than average but each clause provides useful information: usage patterns, data sources, sorting behavior, and return format. It is front-loaded with example queries and uses emphasis to highlight the key preference instruction. Slightly dense, but no wasted 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 no output schema, the description explains return values ('paired data + pipeworx:// citation URIs'), includes relevant edge-case behavior (off-calendar fiscal years), and quantifies efficiency gains (replaces 8–15 lookups). It fully addresses the complexity of a comparative lookup 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 the entity type param with specific metric mappings (company vs drug) and giving concrete format examples for the values array (tickers vs drug names). This goes beyond what the schema states, earning 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 specifies the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sequential single-pack lookups by naming the alternative pattern and providing concrete user-phrase examples (X vs Y, rank these companies).

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 ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides a clear alternative to avoid. It also differentiates between company and drug use cases with specific data sources and metrics, guiding the agent's selection.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds extensive behavioral context: account requirement, paid plan for 'thorough', decomposition into facets, parallel routing, return format (findings packet with evidence, confidence, source, citation, gaps[], contradictions[]), timing (15-60s, up to ~90s), second-hop mechanics, fetchable citations, and semantic excerpting. 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 fairly long but every sentence serves a purpose, from prerequisites to behavior to return format. It is front-loaded with the critical account requirement and alternative tool. A minor reduction in redundant phrasing could improve conciseness, but given the tool's complexity, the length is justified.

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 exceptionally complete given the tool's complexity. It covers prerequisites, usage guidelines, parameter semantics, behavioral nuances (hop iteration, gap recovery, contradictions), return format, timing, and limitations. No output schema is provided, but the description compensates by detailing the findings packet structure. The annotations provide safety hints, and the description fills all remaining gaps.

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

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

Schema coverage is 100%, and the description adds significant value beyond the schema. The 'depth' parameter is elaborated with specific behaviors (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+iterative chase+contradictions). The 'question' parameter is clarified as accepting broad/multi-part natural language. This provides actionable understanding the schema alone lacks.

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 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in a single call, using a specific verb and resource. It distinguishes itself from siblings like ask_pipeworx (single lookup) and mentions when not to use it (e.g., for breaking news).

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

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

Explicitly provides when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also explains the tier requirements and second-hop iteration behavior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations by disclosing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' It could mention pagination or error behavior, but given the annotation coverage, this is strong.

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

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

The description is three sentences with no wasted words. It front-loads the core purpose, then immediately follows with usage context and return behavior. Every sentence earns its place, making it both concise and well-structured.

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 account for return values, and it does: it specifies names, descriptions, schemas, and curated examples. It also provides strong usage context and domain examples. It lacks edge-case handling (e.g., zero results), but for a discovery tool with solid annotations, this is nearly complete.

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

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

Schema description coverage is 100%, with all six parameters documented (including aliases and defaults). The description adds no extra parameter-level meaning; it only reiterates that query is a natural language description, which the schema already states with examples. Baseline 3 is appropriate because the schema carries the full load.

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

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

The description uses a specific verb+resource structure: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by being the discovery/meta-tool, listing concrete domains it covers (SEC filings, FDA drugs, etc.), and stating it returns tool options. This makes its purpose unambiguous and differentiated.

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

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

The description explicitly instructs when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context, though it does not explicitly state when not to use it (e.g., when you already know the exact tool), so it misses the 'when-not' clause for a perfect 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?

Even though annotations already declare the tool as read-only, idempotent, and non-destructive, the description adds substantial behavioral context: it fans out across multiple sources, returns specific data structures with URIs, handles patent API sunset by soft-failing, uses a GDELT→GNews fallback for news, and requires ticker/CIK rather than name. This goes beyond what annotations provide.

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

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

The description is long but densely packed with essential details. It front-loads the main use case and key examples, followed by output breakdown and edge cases. Every sentence earns its place, though it could be slightly tightened without losing 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 tool with no output schema, the description thoroughly covers what is returned (CIK, filings with URIs, fundamentals, patents, news, LEI), the order of recent filings, the patent sunset issue, and the fallback chain for news. It also notes the parallel call nature and the unsupported name input, making the tool's behavior clear enough 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?

The input schema already describes both parameters well, including the enum for 'type' and the ticker/CIK format for 'value'. The description adds concrete examples ('AAPL', '0000320193') and clarifies the constraint that names are not supported, which is also in the schema but reinforced with a redirect to resolve_entity. This adds a bit of 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: building a full cross-source profile of a US public company in one parallel call. It lists specific output components (CIK, filings, fundamentals, patents, news, LEI) and distinguishes itself from sibling tools by recommending it over chaining single-pack lookups for holistic requests.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells users to use resolve_entity if only a name is available, since names are not supported, and explains the patent API soft-fail behavior.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the key-based deletion mechanism and the rationale (clearing sensitive data), but does not disclose additional behavioral traits such as return values, error handling for missing keys, or whether deletion is permanent. No contradiction with annotations exists.

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

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

The description is three short sentences: the first states the core action, the second gives usage guidance, and the third mentions relationships with sibling tools. Every sentence earns its place with no superfluous words.

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

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

The tool is simple (one required parameter, no output schema). The description covers purpose, usage scenarios, and sibling context, while the schema covers the parameter. It does not specify behavior for missing keys or return format, but these are minor gaps for a straightforward delete operation.

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

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

Schema description coverage is 100% with the property description 'Memory key to delete', and the tool description also mentions 'by key'. No additional meaning is added beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall (which store and retrieve memories). The action and target are unambiguous.

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

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

Provides explicit when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but does not state when not to use the tool or list alternative tools for similar purposes.

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 useful process details: it fetches the page, extracts title/description/key links, and outputs a text blob. This goes beyond the annotations, though it does not disclose potential failure modes or rate limits, which would push it to 5.

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

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

The description is three sentences, front-loaded with the primary action and output, and every sentence provides useful information. It is concise and well-structured without wasted words.

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

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

For a simple tool with two parameters and no output schema, the description sufficiently explains the output (a single text blob) and use cases. It is complete enough for an agent to know what to expect, especially since annotations and schema cover safety and parameters.

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 both url and max_links clearly documented. The description does not add extra semantic detail about the parameters themselves, so it meets the baseline for high coverage but does not enhance 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 function: generating a production-ready llms.txt file for any URL, with specific steps (fetches, extracts, emits). It is specific with a verb and resource, but does not explicitly distinguish itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence, so it misses the top score.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt, and auditing competitor sites. It gives clear context on when to use the tool, but does not mention when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by outlining the specific outputs (fields, geometry type, record count, capabilities), which goes beyond the annotation hints and gives a clear picture of what the tool returns.

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, concise sentence that front-loads the action and includes specific return details. Every word earns its place, with no fluff or redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description provides a complete picture of what the tool does and what it returns. The listed outputs (fields, geometry type, record count, capabilities) are sufficient for an agent to know what to expect.

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

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

The input schema has 100% coverage with a clear description of the 'url' parameter, including an example. The tool description merely restates 'by url' without adding any new semantics, so it does not exceed the baseline for good schema coverage.

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

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

The description clearly states the tool's function: retrieving an ArcGIS Feature/Map Service layer's schema by URL, and specifies the exact details returned (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like query_layer, which presumably query data rather than metadata.

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

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

The use case is implied by the description: when you need schema information for a layer, use this tool. However, there is no explicit guidance about when to use this versus alternatives, nor any mention of prerequisites or contexts where it should not be used.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context by specifying the caller-scoped nature ('the caller's active subscriptions') and the exact return fields, which goes beyond what annotations provide. No contradictions with annotations.

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

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

The description is two sentences: the first states the purpose and return fields, the second gives usage guidance. Every word earns its place with no redundancy or irrelevant details.

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 no required params and no output schema, the description is complete: it states scope, what it returns (specific fields), and when to use it. Safety is covered by annotations, and the schema handles the one optional param. 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% since the only parameter include_inactive has a clear description in the schema. The tool description adds the word 'active' which aligns with the default behavior but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'List' with the resource 'the caller's active subscriptions,' clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the exact fields returned, leaving no ambiguity about the tool's purpose.

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

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

The description provides explicit use cases: 'to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it, but it doesn't mention when not to use it or explicitly name alternative tools, though the use cases implicitly distinguish it from 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?

With all annotation hints false, the description carries the full burden and delivers: it reveals the claim_token flow for anonymous filing and later status checks, the daily digest reading, the 5-per-day rate limit, and the fact that it's free and doesn't count against quota. These are concrete operational behaviors beyond what the schema or annotations convey.

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

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

The description is front-loaded with purpose and usage triggers, then covers exclusions, content rules, and token mechanics. It's slightly wordy (e.g., the roadmap-signal sentence is motivational rather than operational), but every sentence contributes a distinct fact and it avoids repetition.

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

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

The tool has a nested context object and no output schema, so the description needs to cover response behavior. It explains the claim_token return and later consumption, but doesn't explicitly state what a successful filing returns when an account is present (e.g., a status string). Given the sibling tools are all distinct and the use cases are fully enumerated, this is a minor gap rather than a critical one.

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 descriptions already cover 100% of parameters, giving the baseline of 3. The description adds genuine value by explaining the claim_token workflow with a concrete example ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies that no account is needed, which the schema's field descriptions do not state.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes from sibling research/query tools by scoping to bug, feature/data_gap, and praise reports. It also explicitly excludes tools from other MCP servers, which none of the siblings address.

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?

Uses explicit 'Use when...' triggers for bug, feature/data_gap, and praise, and clearly says 'ONLY for tools served by this Pipeworx connection.' It provides an alternative ('file it with that server instead') and a heuristic for identifying Pipeworx tools, which is rare and highly actionable.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable behavioral context: it is derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This non-obvious information about data provenance and freshness goes beyond the annotations.

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

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

The description is moderately long but each sentence earns its place: core function, use cases, data provenance, and caching. The bulleted 'Useful for' structure improves scannability. Slightly verbose but not bloated.

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, low-complexity tool with no required parameters and no output schema, the description is remarkably complete. It covers purpose, return content (tools, packs, volume), use cases, data source, no-PII guarantee, and caching behavior, leaving little ambiguity about what to expect.

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

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

Schema coverage is 100% for the single 'window' parameter, which the schema already explains well (24h/7d/30d, shorter vs longer windows). The description merely restates the window options without adding meaningful detail beyond the schema's own description, so baseline 3 is appropriate.

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

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

The description explicitly states what the tool does: it reports what other AI agents are calling on Pipeworx, including top tools, top packs, and total call volume over a window. This is a specific verb+resource combination that clearly distinguishes it from sibling tools 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?

The 'Useful for' section lists three concrete scenarios (discovering hot data sources, confirming canonical tool choice, aligning use cases), providing clear context on when to use the tool. However, it does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, but the description goes far beyond by disclosing internal logic: monotonicity checks, partition sums, Jaccard similarity filtering, placeholder exclusion, and the fill check against live CLOB depth. It also warns when not to trade ('realizable_edge_pp ≤ 0... do not trade it'), which is critical behavioral context. No contradiction with annotations.

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

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

The description is long, but every sentence carries useful information and it is organized with CAP headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the core purpose and then details modes. It could be tightened, but the length is justified given the complexity of the tool.

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

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

For a complex tool with no output schema, the description thoroughly covers invocation, modes, output structure (opportunities[], partition_check, fill check), filtering behavior, and limitations. It also references related tools and gives actionable trade guidance. It is fully self-contained for an agent to select and invoke correctly.

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

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

Even though the schema has 100% description coverage for both parameters, the tool description adds substantial semantic value: it provides concrete example slugs ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), clarifies that full URLs are accepted, and explains how each mode behaves differently with the parameter. This clarifies usage far beyond the schema.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings like polymarket_fill_risk (explicitly referenced) and outlines three distinct modes (trending, event, topic), each with a clear purpose. The purpose is unambiguous and well-scoped.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets and topic for cross-event scanning, and even directs users to polymarket_fill_risk for custom sizing. This gives clear selection criteria and 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?

The description goes far beyond annotations by revealing implementation details such as 'Cached 1h at the KV level keyed on all knobs', the internal logic of model families, and the fact that 'partition arbs always return kelly_fraction_half=0 at the parent level by design.' It also discloses the 24h-move warning and diagnostic output. No contradiction with annotations; readOnlyHint is consistent with the read-only nature described.

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

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

The description is long and dense, but every sentence carries actionable detail, organized logically with section labels and bullet-like lists. The opening sentence is a bit of a run-on, but the structure helps navigation. It earns its length given the tool's complexity, though it could be slightly trimmed for faster parsing.

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 compensates by detailing the response top-level structure: 'by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note ... and _diagnostics.' It explains the three segments, per-opportunity fields, and the meaning of diagnostic counters. Combined with the parameter guidance, the description leaves no critical gaps.

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

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

Despite 100% schema coverage, the description adds significant meaning to every parameter. For instance, slippage_pp is contextualized with 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade,' and min_partition_leg_kelly is explained in relation to why min_kelly doesn't apply. The 'TRADEABLE-EDGE KNOBS' section directly enriches parameter understanding.

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

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

The description opens with a clear, specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This directly addresses what the tool does and doesn't leave room for misunderstanding. It also distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on Pipeworx-driven opportunity discovery.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides practical filtering guidance via the 'TRADEABLE-EDGE KNOBS' and warns about the unreliability of Fed signals. However, it doesn't explicitly compare to sibling tools or state when NOT to use this tool, missing a clear exclusion clause.

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

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

The description richly discloses behavioral traits beyond the annotations (readOnly, openWorld, idempotent, non-destructive): response structure, TTL limits, data availability gaps, signed edge values, and decay calculation methodology. This is far more than typical and fully covers the tool's inner workings.

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

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

The description is long but well organized with labels (RESPONSE, LIMITS) and clear sections for args, response fields, and limitations. Every sentence carries specific information, avoiding fluff, though it could be tightened in places.

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 and a complex telemetry tool, the description provides a complete picture: it defines tracked vs. expired opportunities, explains trend values, describes snapshot_dates gaps, and notes limitations (TTL, snapshot enablement start, daily vs. intraday). This is sufficient for an agent to understand the tool's full behavior and outputs.

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 thoroughly describes both parameters with defaults and ranges (coverage 100%). The description's mention of Args mostly restates schema content without adding new meaning. However, it does contextualize 'window' as a 'snapshot family', which is a slight enhancement.

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

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

The description uses a specific verb-object combination: 'Edge persistence and decay telemetry' built from snapshots, and directly answers the question 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from siblings by focusing on the temporal dimension of edges, not just current 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?

The description provides clear context for when to use the tool (when edge age matters, as freshness vs. decay changes trade risk), but does not explicitly name alternatives or when-not-to-use scenarios. Sibling names like polymarket_edges and polymarket_arbitrage are present, so some implicit differentiation exists.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context beyond this: it walks the CLOB ladder, returns a verdict, warns about forced_directional_risk, and explains that partial fills convert an arb into an unhedged position. This is valuable risk-related behavior not inferable from annotations alone.

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

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

The description is long but front-loaded with purpose and uses CAPS to separate modes. Every sentence adds operational detail (defaults, return fields, risk warnings). It could be broken into sections, but it is efficient given the tool's complexity, so it earns its length.

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

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

There is no output schema, so the description must enumerate return values, and it does for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, capture_ratio, thin_legs, etc. for basket). It also explains the risk implications and prerequisites, making it complete 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 description coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: the 'REQUIRES one of market or event' constraint, mode-specific interpretation of side, and the distinction between single-market spend/proceeds vs basket settlement notional. This goes beyond simple parameter listing, though not by a huge margin.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges), making the tool's purpose unambiguous and differentiated.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged positions), giving clear context and 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing edge-case behaviors: compatibility_warning triggers, matched_pairs:0 scenarios, temporal_alignment semantics, and skipped_cross_type/subtype counters. It transparently states that spreads are meaningless when temporal alignment is false. 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 lengthy but well-structured with uppercase section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and clear field references. Some redundancy exists (the 'pre-mapped ≠ tradeable' point is repeated), but the density of important caveats justifies the length.

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

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

With no output schema, the description compensates by explaining the response structure: leg-by-leg prices, matched spread.top_spreads_pp, compatibility_warning conditions, and skipped counters. Given the tool's complexity (cross-venue mapping with multiple edge cases), this is a thorough and complete description.

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

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

Schema coverage is 100% for all three parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the 'topic' shortcuts as pre-mapped macros, and clarifies that explicit tickers override the mapped side. It also gives examples of valid values, adding context to the raw schema.

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

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

The description opens with a clear statement of the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then explains the two modes and explicitly frames the output as a comparison across venues, which differentiates it from sibling tools like polymarket_arbitrage that likely operate within a single venue.

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 strong usage context: it explains the two modes (pre-mapped topic vs explicit pairings), what the compatibility_warning means, and warns that most pre-mapped topics are not actually tradeable. However, it does not explicitly mention alternative tools or provide 'when not to use this tool' guidance beyond the caveat that pre-mapped does not guarantee a spread.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is clearly established. The description adds that it returns attribute rows and geometry, and that the query is SQL-like, which is useful behavior context. No contradictions with annotations.

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

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

Two sentences, front-loaded with the core purpose, then parameter overview, then return type and a practical tip. Every word earns its place; no fluff or repetition.

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

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

The tool is moderately complex with 6 parameters and no output schema. The description covers the essentials: what it queries, key parameters, return content (rows and geometry), and a concrete usage pattern. It lacks explicit error handling or pagination restatement (though offset is in schema), but overall it is sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: it groups parameters into an SQL-like interface, explains the sampling pattern using where and out_fields together, and clarifies the url should come from search_datasets. This goes beyond the schema's individual parameter descriptions.

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

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

Description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL. It names specific parameters and distinguishes this from sibling tools like search_datasets (which finds datasets) and layer_info (which describes metadata). The verb 'query' and resource 'layer by its url' are precise.

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

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

The description implies the intended workflow: use this after search_datasets to query a specific layer. It provides a concrete sampling tip (where="1=1" + out_fields="*"). However, it does not explicitly state when not to use this tool versus alternatives like search_within or layer_info, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context beyond these: the ability to list all keys by omitting the argument, scoping to the user's identifier (anonymous IP, BYO key hash, account ID), and the read-only nature of looking up prior context. This gives a fuller picture of the tool's behavior without contradicting 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?

Three sentences, front-loaded with the core action, then usage context, then scoping/pairing. Every sentence contributes meaningful information with no fluff. Excellent structure.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the retrieval and listing modes, the scoping mechanism, the typical use case, and how it fits with sibling tools. No critical behavior is left undocumented.

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

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

Schema coverage is 100% (the single 'key' parameter is well-documented). The description reinforces this by explaining the optional nature of the key and the list-all behavior, and provides concrete examples of key meanings (ticker, address, research notes). This adds value beyond the bare schema without being redundant.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys'. It identifies the resource (saved values/keys) and distinguishes itself from siblings like remember and forget, which are for saving and deleting, respectively.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier' and contrasts with re-deriving from scratch. It also mentions companion tools (remember, forget) to complete the workflow, though it does not explicitly name an alternative retrieval tool or provide 'when-not-to-use' 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?

Annotation Contradiction: The annotations declare readOnlyHint=true, but the description explains that mark_read:true flags events as read and affects subsequent calls, which implies a state-modifying side effect. This directly contradicts the read-only annotation, so the description and structured metadata are inconsistent.

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

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

The description is concise and front-loaded, with every sentence serving a purpose: scope, return payload, filtering, mark_read effect, and polling/alternative access. Slightly dense but not bloated.

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

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

With no output schema, the description adequately explains return values (source, citation_uri, raw event payload), filtering behavior, mark_read semantics, and polling suitability. It provides a complete picture for selecting and invoking the tool, apart from the annotation contradiction.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful beyond-schema details: a concrete type example ('sec_8k'), the ISO timestamp relationship for since, and the behavioral consequence of mark_read for future reads. This exceeds the baseline.

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

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

The description opens with 'Pull fired events from your subscription feed,' which uses a specific verb and resource. It clearly distinguishes recent_alerts from siblings like recent_changes or list_subscriptions by focusing on fired subscription events.

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

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

It provides clear context that this is for polling subscription feed alerts and notes that the same feed is accessible via a URL for scripts/dashboards. However, it does not explicitly state when to prefer this over sibling tools like recent_changes or list_subscriptions, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnly=true and idempotent=true, so the bar is lower, but the description goes further: it explains the parallel fan-out to multiple APIs, the GDELT→GNews fallback on rate-limit/5xx, and the PatentsView API sunset causing a soft-fail. These are rich behavioral details that help an agent anticipate outcomes without invoking the tool.

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

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

The description is longer than average, but every sentence carries useful information: source details, fallback logic, date formats, output shape, and an explicit alternative tool. The opening examples and the closing entity_profile call-out earn their place; it could be tightened but is not padded.

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

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

This is a complex tool with multiple data sources, fallback behavior, and no output schema. The description covers input formats, source-specific caveats (including a sunsetting API), return structure (changes[] grouped by source, total_changes, citation URIs), and when to use a sibling tool. It is fully actionable for an agent.

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

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

Input schema covers 100% of parameters, so baseline is 3, but the description adds value by giving concrete examples for `since` (ISO "2026-04-01", relative "7d", "30d", "3m", "1y") and recommending "30d" or "1m" for typical monitoring. It also clarifies `value` as ticker or zero-padded CIK, which supplements the schema's generic descriptions.

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

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

The description opens with example queries then states 'change feed for a company in the last N days/weeks/months in ONE parallel call', clearly identifying the verb and resource. It lists the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with entity_profile, distinguishing it from a sibling 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?

It provides concrete user intents ("What's new with X" / "latest on Y") and explicitly says 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains the GDELT→GNews fallback and when each source is used, giving an agent clear selection criteria and 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. No contradiction with annotations; extra specifics beyond annotation hints.

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

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

The description is concise and well-structured: purpose in the first sentence, followed by usage guidance, storage details, and sibling references. Every sentence provides distinct value with no redundancy, and the most important information is front-loaded.

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

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

For a simple write tool with a high-coverage schema and detailed annotations, the description covers behavior (scoping, retention), usage, and related tools. It does not need to explain return values (no output schema) and provides all necessary context for correct invocation.

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

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

Schema description coverage is 100%, with clear descriptions for 'key' and 'value'. The description adds semantic nuance by noting 'scoped by your identifier', which clarifies key namespacing and complements the schema's examples. This goes slightly beyond the baseline schema coverage.

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

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

The description uses a specific verb ('Save data') and clearly identifies the resource (data to reuse later across conversation/sessions). It distinguishes itself from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete', making the purpose explicit and differentiated.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples. Provides clear alternatives (recall, forget) and contextual behavior (authenticated vs anonymous sessions), giving complete guidance on usage.

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 valuable behavioral context: graceful degradation when external sources are unavailable, cascading multiple lookups internally, how unresolved identifiers are handled (explicitly under `unresolved`), and that ISINs resolve to legal entities via GLEIF. 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 a single dense paragraph that front-loads key examples and usage guidance. It efficiently packs a lot of detail (supported types, identifier sources, degradation) without unnecessary words. A slightly more structured format (e.g., bullet lists for types) could improve scannability, but it remains concise and informational.

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 entity types, multiple identifier sources, graceful degradation) and the absence of an output schema, the description covers all essential aspects: what the tool does, what identifiers are resolved for each type, how unresolved identifiers are reported, and behavior under partial failures. An agent can confidently invoke the tool based on this description.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches the 'value' parameter by specifying additional accepted formats like ISIN and giving a concrete example ('CH0038863350'), and clarifies the behavior for different types (company vs drug). This adds meaning beyond the schema's basic 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 uses specific verbs like 'resolve' and gives concrete examples of user queries. It states the tool's purpose clearly: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID.'

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 strong guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It lists example queries that trigger this tool. However, it does not explicitly mention when not to use it or point to specific alternatives like entity_profile for when you already have an ID, though the context of sibling tools and the phrase 'replaces 2-3 manual lookups' imply efficiency.

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?

All safety traits are already covered by annotations (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description nevertheless adds significant behavioral context: it reveals the tool orchestrates calls to ai_visibility_check, ranks results by score, and returns per-entity metrics. This informs the agent about dependencies, side-effects (external probes), and the nature of the output, going beyond what annotations alone convey.

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

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

The description is four sentences, each serving a distinct purpose: state the operation, explain the mechanism, provide the use case, and list the return structure. It is front-loaded with the core purpose and contains zero filler or repetition. It is concise while packing substantial 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 tool with no output schema, the description fully covers what the agent needs: what it does, how it works (multi-entity comparison via probing), when to use it, and what it returns (ranked list with score, confidence, signal density). The annotations and schema cover safety and parameter details. Given the moderate complexity, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic context by framing the 'entities' parameter as 'your brand + N competitors,' which aligns with the schema's note about the first entry being the subject. This enriches understanding of parameter intent, elevating the score above baseline, though the schema already fully describes each parameter.

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

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

The description opens with a clear, specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It explicitly distinguishes itself from the sibling ai_visibility_check by framing this as a multi-entity comparison that internally probes each entity with that tool. It also states the output (ranked list with score, confidence, signal density), leaving no ambiguity about what the tool does.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example question. It implies the alternative by mentioning it probes entities with ai_visibility_check, but does not explicitly state when NOT to use this tool (e.g., for single-entity checks) or name alternatives. This is clear context but lacks explicit when-not/alternatives, so it earns a 4 rather than a 5.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It discloses that the tool fans out across multiple external services, explains partial failure behavior, explicitly mentions a 5-30s timeout for first measurements, and introduces the 'sources_failed' field. This is rich behavioral context that annotations cannot convey.

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

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

The description is a dense but well-structured paragraph. It opens with the core purpose and then systematically adds details (data sources, use case, return fields, ecosystem limitation, failure handling) without redundancy. Every sentence earns its place; no 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?

There is no output schema, so the description carries the full burden of explaining return values. It enumerates the exact summary fields, per-advisory details, links, and alternative versions. It also covers the main edge case (bundlephobia timeout) and the ecosystem restriction. For a composite tool with no output schema, this 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?

The input schema already fully documents both parameters (package, version) with clear descriptions, including scoped package support and default version behavior. The description adds no new parameter-level semantics beyond implying npm-specific context, so the baseline of 3 is appropriate.

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

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

The description opens with a clear verb+resource: 'Composite should I add this npm package to my project check in ONE call' and specifies the underlying data sources (deps.dev, bundlephobia). It clearly distinguishes this tool from siblings by naming the exact ecosystem (npm) and the data providers, so an agent knows precisely what it does.

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

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

The description explicitly states when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives exclusion criteria: 'NPM ecosystem only in v1' and directs other ecosystems to a different tool (deps.dev:version directly). This is exemplary when-to-use guidance with alternatives.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context by specifying the exact return fields (name, summary, record_count, owner/org, url) and the intended downstream use, which goes beyond the structured annotations. It does not disclose rate limits or edge cases, but the annotation coverage lowers the bar.

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

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

The description is two sentences: the first states purpose and scope, the second lists return fields and downstream usage. Every sentence earns its place, with no redundancy or fluff. The key information is front-loaded in the first sentence, and the structure is highly readable.

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

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

The tool has three optional parameters, no output schema, and is part of a larger toolset. The description fully covers what the tool returns and how to use the result with sibling tools, making it complete for the agent's decision-making. The schema covers parameter defaults and options, and annotations cover safety, so no critical information is missing.

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

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

The input schema has 100% description coverage for all three parameters (query, limit, org_id), so the schema already explains the parameters adequately. The description's mention of 'by keyword' aligns with the query parameter but adds no additional semantic nuance beyond the schema. Therefore, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Search Adams County GIS open geospatial datasets by keyword.' It specifies the resource (Adams County GIS open geospatial datasets) and the action (search by keyword), and lists example dataset types. It also distinguishes itself from siblings by indicating that its output (Feature Service url) is meant to be passed to query_layer / layer_info, positioning it as the entry point for dataset discovery.

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: it is for searching datasets by keyword and explicitly directs the user to pass the resulting url to query_layer / layer_info, implying a workflow. It does not explicitly mention when not to use this tool or compare with all siblings, but the downstream link and keyword-search framing make its intended use unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds substantial behavioral context: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K-char cap with truncation flagging, and that each passage includes an offset for verbatim verification. This goes well beyond annotations to disclose concrete technical behavior.

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

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

The description is compact yet information-dense. Three sentences cover purpose, use-case, pairing, and technical details without fluff. Every clause earns its place, and the most critical information (what the tool does) is front-loaded.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers what the tool does, when to use it, how it pairs with another tool, the technical embedding/offset mechanism, and input/output behavior. The agent would know exactly what to expect and how to invoke it.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it gives concrete examples for 'text' (SEC 10-K body, article, long tool result) and for 'query' (supply-chain risk, fiscal year 2024 revenue, drug interactions). It also explains that 'limit' controls the top-N passages returned. This enhances understanding of parameter 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 opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly identifies what the tool does, including input (text already pulled) and output (top-N passages with character offsets and similarity scores). It also distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and focusing on search within a single fetched record rather than broader 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?

The description provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and explains the trade-off (saves context, returns only relevant passages). It also names a sibling tool (ask_pipeworx_grounded) and describes the complementary workflow: fetch with the gateway, then ground over relevant passages. This gives clear when-to-use and how-it-fits guidance.

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

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

The description discloses auth requirements, delivery channel details (phone verification, 10/day cap, always-on feed), and persistence constraints. These go beyond the annotations and provide essential operational context. No contradiction with the annotations' hints (readOnly=false, openWorld=true, etc.).

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 long but every sentence carries useful information. It is front-loaded with purpose, then prerequisites, then types, then delivery. The structure is logical and free of filler, though it could be tightened by moving some details to the schema (which it already does).

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 and complex nested parameters, the description compensates by covering the return value, all subscription types, auth, and delivery channels. The schema fills in webhook details, so the combined definition is complete. The description adds context beyond the structured fields, making the tool highly usable.

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

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

The schema already provides thorough parameter descriptions, but the tool description adds interpretive value (e.g., items:["5.02"] = officer change) and concrete examples for each subscription type and delivery format. This exceeds the baseline for high schema coverage, though some redundancy exists.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, and it names the return value. The supported types and delivery channels further clarify the tool's purpose.

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

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

The description gives actionable guidance: use this for proactive monitoring, and for non-subscription pulls it suggests recent_alerts or the JSON endpoint. It also states a prerequisite (Pipeworx OAuth account; anonymous+BYO cannot persist). It stops short of explicitly naming list_subscriptions/unsubscribe as alternatives, hence not a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds context about the output format (category-bucketed example questions) and that results are drawn from a live catalog of thousands of tools. It also clarifies that passing `topic` narrows the spread, which is helpful behavioral information not in the schema.

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

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

The description is quite long but front-loaded with example user queries and a clear purpose. Each sentence carries useful information, though it could be trimmed slightly for brevity without losing meaning.

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

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

The description fully covers the tool's purpose, usage, optional parameter behavior, and output type. It even explains how to use it as a gateway to other meta-tools, making it complete for an onboarding tool with a single optional parameter and no output schema.

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

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

The parameter `topic` is fully described in the schema, and the description adds concrete examples ('finance', 'pharma', 'betting') and explicitly states that omitting it gives a cross-category spread. This adds practical meaning beyond the schema's type description.

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

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

The description clearly states the tool's function: it returns category-bucketed example questions to help an agent discover what Pipeworx can do. It distinguishes itself from siblings by calling itself 'the onboarding entry point' and specifically naming meta-tools (ask_pipeworx, entity_profile, compare_entities) it teaches.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter to focus the response, giving clear when-to-use context.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds important behavioral context: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events. 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, front-loaded with the primary action, and every sentence contributes meaningful information (ownership, deactivation, historical availability). Perfectly concise for a simple tool.

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

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

Given the tool has one parameter, no output schema, and simple behavior, the description is complete: it covers what it does, ownership, side effects, and data preservation. No critical information is missing.

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

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

Schema coverage is 100% and the parameter 'id' has a clear description. The tool description only repeats 'by id' and adds no extra semantic meaning, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Cancel a subscription by id') and clearly distinguishes from sibling tools like subscribe and list_subscriptions. The title 'Unsubscribe from Alerts' reinforces the purpose.

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

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

Provides clear context on ownership enforcement ('only cancel your own subscriptions') and explains the deactivation behavior with a link to recent_alerts, implying when this tool is appropriate. Lacks explicit alternatives or exclusion conditions, but is sufficiently 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?

The description goes well beyond the annotations. It explains the two verification paths, the full set of verdicts, and crucially defines the semantics of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source found). This behavioral nuance is essential for correct interpretation and is not captured in the annotations or schema.

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

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

The description is longer than typical but every sentence earns its place: trigger phrases, usage contexts, routing logic, verdict list, and a critical caller warning. It is front-loaded with purpose and ends with an efficiency note. While not as terse as a two-sentence example, it is well-structured and dense with high-value 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 this tool has no output schema, the description comprehensively covers return values: verdicts, actual value with citation, reasoning, and error fields. It also explains the two processing pipelines and the special cases of 'could_not_verify' and 'unsupported'. For a complex tool, this is highly complete and leaves few gaps for the agent.

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

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

Schema description coverage is 100%, with both 'claim' and 'tolerance_pct' richly described in the schema, including examples and default behavior. The tool description does not add any parameter-specific guidance beyond what the schema already provides. Baseline 3 is appropriate per the rubric.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases ('fact check', 'verify the claim that…'). It distinguishes itself from siblings by focusing on fact-checking rather than general queries, and mentions replacing 4–6 sequential calls, highlighting its unique consolidation role.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the two routing paths (SEC EDGAR for company-financial claims vs. grounded pipeline for all others) and warns about the meaning of 'could_not_verify', guiding correct usage. This is clear, with no ambiguity about when to invoke the tool.

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