Arcgis Mobile

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description goes beyond annotations by disclosing cost implications ('you pay Anthropic directly'), the default model selection, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This enriches the behavioral picture meaningfully.

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 with no filler. It front-loads the core action and output, then packs additional essential details (default model, cost, output fields) without redundancy. Every sentence contributes useful 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?

With no output schema, the description appropriately explains the return format, including per-model fields and the combined view. It covers defaults, optional parameters, and example use cases. For a moderately complex tool with 4 parameters, this is fully 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%, so the baseline is 3. The description adds value beyond the schema by explaining the relationship between 'models' and '_apiKey' (passing the key enables Anthropic), the default model when omitted, and the intent behind 'context' ('Helps disambiguate common names'). This cross-parameter guidance is not in the schema alone.

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

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

The description clearly states the action ('Probe one or more LLMs') and the resource (business/brand/product/topic), with a specific measurable outcome ('score visibility (0-100) per model'). It distinguishes itself from sibling tools by focusing on generic visibility scoring across LLMs, not specific entity queries like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description provides clear context for when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also provides practical guidance on defaults (Workers AI is free) and when to pass _apiKey (to use Anthropic). However, it does not explicitly state when not to use it or name alternative tools, 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 mark this as read-only, idempotent, open-world, and non-destructive, and the description does not contradict these. It adds valuable context by explaining that the tool routes to 5,529 tools across 1,455 sources, fills arguments, returns structured answers with stable citation URIs, and operates on every tier with one fast call.

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 minimal, but every sentence contributes value. The first sentence front-loads the core purpose, followed by concrete examples and usage escalation paths. The structure is logical and scannable, though the extended list of examples could be shortened without losing core 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?

Given that this is a simple tool with a single primary parameter and no output schema, the description is highly complete. It covers what the tool does, when to use it, alternatives, return format, and operational characteristics, making it fully actionable for an agent.

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

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

The schema provides 100% coverage for all six parameters, each being aliases for the main question field with clear descriptions. The description does not add additional parameter meaning beyond what the schema already states, but it does mention that the tool 'fills arguments' which implies the question is the primary input. Baseline 3 is appropriate.

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

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

The description opens with an explicit directive to prefer this tool over web search for a broad range of factual questions, then specifies the exact routing function and the categories of data covered. It clearly distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as step-up alternatives.

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 both when-to-use and when-not-to-use guidance. It gives multiple concrete example prompts, states 'START HERE for most questions', and explicitly mentions when to step up to ask_pipeworx_grounded or deep_research, including the breaking-news caveat. This fully covers usage 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the experimental nature: behavior changes when a candidate is under test, currently no candidate is active so it matches ask_pipeworx exactly, and it is a full working router. This goes beyond the structured annotations, though it does not detail response format or error handling.

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 and packed with useful information about the beta status, current behavior, and usage guidance. While slightly verbose, every sentence adds value—especially the clarification that it is a full working router and not a fallback. It is well-structured and front-loaded with the core purpose.

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

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

Given that this is a single-question router with annotations and a schema, the description is fairly complete. It explains what it does, how it differs from the stable version, and its current state. The main gap is that it references 'same response shape' without specifying what that shape is (no output schema), but since it points to ask_pipeworx as the stable template, an agent could infer or look up the sibling tool.

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

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

The input schema covers 100% of parameters, all as aliases for 'question'. The description mentions 'same arguments' but does not add any new meaning beyond what the schema already provides. Given the high schema coverage, a baseline of 3 is appropriate; the description doesn't need to restate the aliases.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router, and explicitly distinguishes it from the stable sibling ask_pipeworx by noting the candidate routing improvements. It includes specific details like the same 5,529 tools and same response shape, making its purpose unambiguous.

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

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

The description gives direct guidance: 'Use it exactly like ask_pipeworx when you want the newest routing,' which tells the agent when to select this tool. It also explains the current status (no active candidate) and that results are compared against the stable router, but it does not explicitly mention when to prefer ask_pipeworx or ask_pipeworx_grounded over this beta, leaving a slight gap in 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?

Goes well beyond annotations by detailing the exact success and refusal return shapes, the five refusal reasons, the guarantee of only using tool result, and the internal routing over 5,529 tools. No contradiction with readOnlyHint or other 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 informative and well-structured, starting with purpose, then mechanism, return format, and usage guidance. It is a bit dense but each sentence provides value, and there is little redundancy; front-loading the core purpose is effective.

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

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

Despite lacking an output schema, the description fully specifies the return shape and refusal reasons. It also covers when to use, cost implications, and the internal data-flow, leaving no major gaps for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds no parameter-specific detail beyond the schema, but the schema already fully explains the single required question parameter, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads, with specific behavior (extracts only from tool result, explicit refusal). It distinguishes from siblings like ask_pipeworx by the grounded guarantee and refusal reasons, making its purpose unambiguous.

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

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

Explicitly states when to use (answers that will be quoted, cited, or acted on; high-stakes domains) and when not to (prefer ask_pipeworx for casual lookups). Also mentions the extra LLM call cost, providing a clear trade-off.

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. The description substantially enriches this with concrete, non-obvious behaviors: low-confidence matches short-circuit with 'low_confidence_match' and suppress analysis fields; closed/dead markets return 'market_closed_or_inactive' and skip fan-out; both routes are blocking; wide-spread markets get a tradeability flag; news fallback retry mechanics; and cancellation-rule parsing with ev_impact. This goes far beyond the annotations and is crucial for safe usage.

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

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

Despite being long, the description is highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Every section contains dense, non-redundant operational details that earn their place. It is front-loaded with the primary purpose and usage, making it easy to navigate and parse.

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

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

For a complex tool with no output schema, the description is remarkably complete. It specifies response shapes (result.market, result.analysis, result.evidence), resolver contract fields (market_match_confidence, score, alternatives, suggestions), parent_event structure, news fallback fields, status codes for low-confidence/closed markets, and cancellation-rule semantics. This covers all likely return values and edge cases an agent would need.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already explains market (slug/URL/question text), depth (quick vs thorough), and include_raw (with size implications and recommendation). The description adds useful fan-out examples (e.g., 'BTC bet → coingecko + fred + gdelt+gnews') that give concrete meaning to 'thorough,' but does not materially change the schema's parameter definitions. It is adequate but not a standout compensation.

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 pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further details the process (resolves market, classifies, fans out, returns evidence packet + comparison) and explicitly states use cases for 'should I bet on X' etc. This clearly distinguishes it from siblings like polymarket_edges or polymarket_arbitrage by focusing on one bet's data research.

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

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

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives classifier categories and fan-out examples, which imply when to use. However, it does not explicitly name alternative tools for other scenarios (e.g., arbitrage, edge tracking) or state 'do not use when', so it stops short of full exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. This goes beyond the annotations without contradicting them.

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

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

The description is dense but well-structured: starting with example phrasings, then core function, then type-specific data sources and output behavior. Every sentence adds relevant information, though it is longer than average; still, it remains appropriately sized for the tool's complexity.

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

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

For a tool with no output schema, the description effectively communicates return format (paired data + citation URIs), sorting behavior, and the fact it consolidates many lookups. It lacks explicit error-handling info but covers the essential aspects of invocation and expected output.

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

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

Schema coverage is 100% (both type and values are described), so baseline is 3. The description adds meaning by detailing what each 'type' pulls (10-K financials for companies; FAERS/FDA data for drugs), and it also clarifies the values count and examples. This enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific verbs ('compare', 'rank') and resource types. It distinguishes itself from siblings by emphasizing its role for comparative queries and noting it replaces sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear when-to-use directive. It also mentions it handles both company and drug comparisons. However, it does not explicitly name alternative tools or state when NOT to use it (e.g., for single-entity lookups).

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, etc.), the description discloses latency ranges ('15-60s', 'up to ~90s'), gap handling ('explicit gaps[]... never invented'), second-hop iteration for standard/thorough, contradictions[] scanning, semantic excerpting, and citation_uri fetchability guarantees. This adds substantial behavioral context beyond the annotation flags and shows no contradiction.

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

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

The description is long but densely packed; most sentences carry unique value (account, alternatives, depth semantics, gaps, contradictions, latency). Minor redundancy exists (paid plan mention twice, 'NOT open-web search' could be seen as repeated emphasis), but the structure using parentheses and semicolons keeps it navigable.

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 exceptionally complete: it specifies return shape, behavior across depth levels, latency, account prerequisites, sibling alternatives, and limitations on news topics. It fully compensates for the absence of an output schema by detailing what 'findings packet' contains and how gaps/citations behave.

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

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

Schema coverage is 100% for both params, but the description enriches the depth parameter by explaining behavioral differences: 'standard' re-angles unanswered gaps, 'thorough' chases leads, and both include a contradictions[] scan. It also clarifies the 'question' param accepts broad/multi-part natural language, adding semantic depth beyond the schema text.

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+scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and notes it returns a 'findings packet' with evidence, confidence, source, and citations. It explicitly distinguishes itself from siblings by stating 'this is NOT open-web search' and references ask_pipeworx as the alternative for single lookups.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' plus 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also includes account-tier requirements and a fallback if not signed in, making alternatives and exclusions clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral value by specifying what the tool returns ('names, descriptions, and full input schemas') and the practical benefit ('no second schema lookup needed'). It does not contradict annotations and provides useful context beyond the structured hints.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a useful domain list and return behavior. The domain list is long but serves to define scope, making it worthwhile. It is structured as a single paragraph with logical flow, though slightly verbose with the exhaustive category listing.

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 a discovery meta-tool with no output schema, so describing the return value is essential. The description fully covers this: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. It also addresses usage context and helpful behavior, making it complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, and the schema already documents the 'query' parameter, aliases, and limit with clear descriptions. The description adds only the concept of 'top-N' and 'curated examples', but does not explain parameter syntax or values beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb 'Find' and clearly identifies the resource ('tools') and the action ('describing the data or task'). It also lists concrete domains (SEC filings, FDA drugs, etc.), distinguishing it from siblings by framing it as a meta-tool that discovers other tools rather than a task-specific 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 explicitly states when to use ('Use when you need to browse, search, look up, or discover what tools exist'), and gives a strong directive to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This implicitly excludes using it when you already know the specific tool, providing clear when/when-not guidance.

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

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

Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable behavioral detail: one parallel call, fan-out across multiple sources, patent API sunset with soft-fail, GDELT→GNews fallback, and the exact return structure. No contradiction with annotations.

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

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

The description is one dense paragraph but extremely efficient: it leads with query examples, then defines the tool's role and return sections. Every clause is informative, though the density and lack of visual structure make it slightly less scannable than ideal.

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

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

For a multi-source read tool with no output schema, the description comprehensively enumerates all return fields (cik, recent_filings, fundamentals, patents, news, LEI), edge cases (patent sunset, fallback chain), and input constraints (ticker or CIK only). This is sufficient for an agent to select and invoke the tool correctly in context.

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

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

The input schema already covers both parameters at 100% with detailed descriptions (ticker/CIK formats, name restriction, enum type). The description mostly reiterates the same information ('Pass ticker "AAPL" or zero-padded CIK'), so it adds no meaningful new parameter semantics beyond the schema. Baseline of 3 for high schema coverage applies.

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

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

The description states a specific verb+resource: 'full cross-source profile of a US public company', with concrete user query examples like 'Tell me about X' and 'brief me on Tesla'. It explicitly differentiates from single-pack SEC/XBRL/news lookups and directs name-only queries to resolve_entity, so it is clearly distinguished from siblings.

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

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

The description explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', and clearly states when not to use it: 'names not supported (use resolve_entity first if you only have a name)'. This provides strong when/when-not and alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds context about clearing sensitive data and pairing with other tools, but no additional behavioral details beyond what the 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 two sentences, front-loaded with the primary action, and includes essential usage guidance without any filler. Every sentence contributes value.

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

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

For a single-parameter tool with no output schema, the description covers purpose, when to use, and related tools. It could briefly mention the return value or confirmation behavior, but that is not essential for this simple destructive 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 coverage is 100% with a clear description for the 'key' parameter ('Memory key to delete'). The tool description adds no extra information about the parameter format, validation, or examples 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 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It distinguishes from siblings like remember and recall, which store and retrieve memories 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?

The description provides explicit use cases: '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, giving relevant alternatives. However, it does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it fetches the URL, extracts specific elements, and outputs a single markdown text blob. It also mentions the standard format and site-root placement, which is richer than typical descriptions.

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 plus a brief 'Useful for' list. It front-loads the core action, explains the mechanism, and lists use cases without unnecessary fluff. Every sentence earns its place.

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

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

For a simple tool with two parameters, no output schema, and strong annotations, the description is complete. It explains the purpose, process, output format, and realistic use cases. There are no critical gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning for parameters beyond what the schema already provides: it mentions 'key links' and 'any URL', but does not explain max_links. This is adequate since the schema fully documents both parameters.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file for any URL'), clearly distinguishing this from sibling tools like ai_visibility_check or scan_competitor_ai_presence. It also details the process (fetches page, extracts title/description/links) and the output format (standard llms.txt markdown).

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 use cases ('getting a client's site indexed by AI', 'drafting llms.txt', 'auditing how an AI crawler would see a competitor') but does not explicitly mention when not to use it or name alternative tools. This gives clear context without 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, idempotentHint=true, and destructiveHint=false, providing the safety profile. The description adds concrete return elements (fields, geometry type, record count, capabilities) but does not disclose potential performance costs or request limits, which is acceptable given 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?

A single, dense sentence that front-loads the action and lists the key return values. Every word earns its place with zero 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?

For a simple one-parameter read-only metadata tool, the description fully covers the purpose, required input, and return content. No output schema is present, but the listed outputs are sufficient for an agent to use the tool correctly.

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

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

The input schema already defines the single 'url' parameter with a full description. The tool description's 'by url' simply restates the schema's meaning. No additional parameter nuance is needed, so baseline 3 applies.

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

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

The description uses a specific verb ('Get') and names the exact resource ('ArcGIS Feature/Map Service layer's schema') plus the key outputs (fields with name/type, geometry type, record count, capabilities). This clearly differentiates it from sibling tools like query_layer or search_datasets.

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

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

The description implies when to use this tool: when you need schema metadata (fields, geometry, count, capabilities) for a given layer URL. It does not explicitly state exclusions or alternative tools, but the context and sibling list make the intended use clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context by specifying the returned fields and the default behavior of listing only active subscriptions (implied by 'active' and the include_inactive parameter). This goes beyond the annotations without contradicting them.

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

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

The description is two sentences: the first states the core function and return fields, the second gives usage guidance. Every sentence earns its place with no redundancy or filler. The structure is front-loaded and efficient.

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

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

This is a simple list tool with one optional parameter and no output schema. The description covers the return fields, the default scope (active only), and practical use cases. Given the tool's simplicity and the rich annotations, the description is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%: the only parameter include_inactive has a clear description in the schema. The tool description mentions 'active subscriptions,' which slightly reinforces the parameter's default behavior, but it does not add meaningful detail 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 clearly states the tool's function: 'List the caller's active subscriptions.' It also specifies the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which distinguishes it from sibling tools like subscribe/unsubscribe. The verb 'list' is specific and the resource is explicit.

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

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

The description provides clear use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This explicitly tells when to use the tool, though it does not name alternatives or state when not to use it. The context is sufficiently clear for an agent to select it appropriately.

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

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

Beyond annotations, the description discloses a stateful claim-token mechanism ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and cost/free behavior ('Free; doesn't count against your tool-call quota'). It also reveals human review cadence ('The team reads digests daily'), none of which is in the annotations. No contradiction with the annotations.

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

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

The description is longer than average but every sentence earns its place: core purpose, usage categories, scope exclusion, token workflow, rate limit, and cost. It is front-loaded with the primary action and uses clear typographic cues. No redundant or filler content.

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

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

Given the tool's complexity (4 parameters, nested context, enum, no output schema), the description covers everything an agent needs: full usage scenarios, scope limitations, claim-token lifecycle, rate limits, and content expectations. It is self-sufficient even without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving content guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This lifts it above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback categories (bug, feature/data_gap, praise) and clearly distinguishes this tool from siblings by stating it is ONLY for tools served by this Pipeworx connection, which no sibling 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 explicit when-to-use scenarios ('Use when a tool returns wrong/stale data...') and when-not-to-use with an alternative ('if the tool came from a different MCP server... file it with that server instead'). It also adds boundary guidance ('Pipeworx tool names are the ones this connection lists') and rate-limit information, making usage unambiguous.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral context: caching windows (5min-1h), data provenance (CF analytics-engine), PII handling, and the exact data shape (pack, tool, count). This fully discloses operational characteristics.

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

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

The description is front-loaded with a punchy opening question, followed by a clear list of use cases and a precise data provenance note. Every sentence adds distinct value with no fluff or repetition, achieving high information density in a compact form.

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 (single enum parameter, no output schema), the description fully covers return contents (top tools, top packs, total call volume) and provides key operational details (caching, PII). No critical aspect is left unexplained for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline of 3 is appropriate. The description mentions the window parameter and its effect, but the schema's own parameter description already covers this exact semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). No additional meaning is added.

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

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

The description clearly identifies the tool as an aggregator of other AI agents' usage, with a specific verb 'Returns' and explicit resources (top tools, top packs, total call volume). It distinguishes itself from siblings like discover_tools by focusing on cross-agent trends rather than static 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?

Provides a detailed 'Useful for' list with three concrete scenarios, effectively communicating when to use the tool. However, it does not explicitly name alternative tools to contrast with or exclusions for when not to use it, only implied 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?

Goes well beyond the readOnly/openWorld/idempotent annotations by detailing how partitions are checked (sum of YES prices ≈1, >3pp deviation triggers signals), the Jaccard similarity threshold for semantics, placeholder-slug filtering, and the fill-check behavior that warns against trading when realizable edge ≤0. No contradiction with annotations.

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

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

Dense but every section earns its place: mode distinction, semantic anchor, partition filter, response shape, and fill-check warning are each essential. It's front-loaded with the primary purpose and uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for scannability.

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 analysis tool with no output schema, the description fully covers invocation modes, algorithmic details, edge cases, placeholders, response fields, and trade safety warnings. There are no missing pieces for an agent to select and use the tool correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it explains the exact format for event slugs, gives seed-question examples for topic, explains what each mode returns, and describes the no-arg behavior not represented in the schema. This is far beyond baseline.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges and polymarket_fill_risk by defining the exact methodology and scope.

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

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

Provides explicit when-to-use guidance for all three invocation modes: no args for trending_scan, `event` for specific markets (recommended), and `topic` for cross-event scanning. It even recommends when each is appropriate and points to polymarket_fill_risk for custom sizing, serving as an explicit alternative.

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

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

Annotations already mark this as read-only, open-world, and non-destructive. The description adds substantial behavioral detail beyond that: caching behavior ('Cached 1h at the KV level keyed on all knobs'), the 24h-move warning, diagnostics so callers can see why a segment is empty, and the rationale for excluding Fed bets. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and organized by model families, knobs, and response structure. However, it is extremely dense, including per-sport α values and placeholder-slug rules, which may be more detail than an agent needs for tool selection. Some information repeats the schema (e.g., min_liquidity/max_spread_pp), so it is not fully concise.

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

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

There is no output schema, so the description must explain return values, and it does thoroughly: by_segment structure, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp), fed_note, and _diagnostics with funnel counters. It also explains how knobs affect output and mentions caching. This is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds extra meaning by grouping knobs under 'TRADEABLE-EDGE KNOBS' and explaining nuanced behavior, e.g., min_partition_leg_kelly filters per-leg Kelly because parent-level Kelly is always 0 for partitions. This goes beyond the 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 opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' – a specific verb, resource, and clear output. It also states the intended use case, 'what should I bet on today', which distinguishes it from sibling tools like polymarket_arbitrage by focusing on data-vs-market disagreements rather than pure arbitrage.

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 targets the 'what should I bet on today' scenario and explains that agents avoid paging hundreds of markets. It describes filtering knobs (min_liquidity, max_spread_pp) and even notes why Fed bets are excluded from ranking. However, it does not explicitly contrast with alternative tools or state when not to use this tool, 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?

Even with annotations (readOnlyHint=true, idempotentHint=true), the description adds rich behavioral context: history is bounded by a 60-day snapshot TTL, snapshots are written on cache-miss so gaps indicate no scan, and decay is computed from daily closes of edge_pp_net, not intraday. It also details the response structure, enabling the agent to understand what data will be returned. No contradictions with annotations.

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

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

The description is long but every sentence contributes. It is structured with clear sections: purpose, args, response (with tracked/expired/snapshot_dates), and limits. The information density is high, and no redundant or filler text exists. Appropriate for the tool's complexity.

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

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

For a telemetry tool with no output schema, the description thoroughly covers return values (tracked, expired, snapshot_dates), their semantics, and limitations (TTL, cache-miss gaps, daily vs. intraday). It also explains the implications of gaps and the 'competition clock'. This is exceptionally 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 both parameters (days and window) are already well-documented in the input schema. The description essentially repeats the defaults and allowed values (days default 14 max 30, window default '1wk'), adding slight value with the phrase 'snapshot family' but not meaningfully enhancing the schema's semantics. 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?

Purpose is explicitly stated: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' The description goes beyond a simple verb+resource by explaining the core question ('how long has this edge existed and is it shrinking?') and distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) by contrasting fresh vs. old edges.

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

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

The description gives clear guidance on when to use it by explaining the trade context: 'a fresh wide edge and a 3-week-old wide edge are different trades'. It also mentions the 'median lifespan is your competition clock', implying use cases. However, it does not explicitly name alternatives or state when not to use it, 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?

Despite annotations declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: it details the walking of the order ladder, modes (single-market vs basket), specific output fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and risk factors like forced_directional_risk. This goes far beyond generic safety hints. 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 long but exceptionally well-structured: it opens with the core purpose, uses capitalized labels for modes (SINGLE-MARKET, BASKET), enumerates outputs clearly, and ends with actionable usage. Every sentence conveys necessary information for a complex tool with two modes; 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?

Given the tool's complexity (two modes, numerous outputs), the description is remarkably complete. It covers inputs, outputs, defaults, edge cases, and even failure modes (thin_legs, forced_directional_risk). There is no output schema, so the description appropriately explains all return values in detail.

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

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

Schema coverage is 100%, but the description enriches param meaning significantly: it explains market vs event modes, interpretation of size_usd in each mode (max spend vs target proceeds vs settlement notional), defaults, clamps, and auto-side behavior. This is more than the schema's basic descriptions, making the parameters fully understandable.

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 core function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It uses a specific verb ('check') and resource ('order-book depth'), and distinguishes itself from sibling tools by referencing 'polymarket_arbitrage' and 'polymarket_edges' as precursors, making its unique role evident.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books and partial fills create unhedged positions), offering clear when-to-use and rationale, with implied alternatives via the sibling tools.

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

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

The description discloses extensive behavioral details beyond the readOnly annotation: it explains compatibility_warning triggers (non-equivalent bet shapes, no token overlap), temporal alignment semantics, and skip counters for cross-type/subtype mismatches. It also clarifies that pre-mapped shortcuts are not automatically tradeable, which is non-obvious and valuable.

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

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

The description is long but well-structured, with clear labels (RESPONSE, SAFETY FIELDS, two modes) and every sentence carrying useful information. It is slightly verbose compared to minimal descriptions, but the complexity of the tool justifies the length. A 4 balances completeness against brevity.

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

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

With no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skip counters). It covers both normal and edge-case behavior, making it complete for the tool's complexity and annotations.

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

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

The input schema already provides 100% parameter coverage with descriptions and examples. The description adds meaningful semantic context by explaining the two-mode usage (topic vs explicit overrides) and how parameters interact, which goes beyond the schema's flat descriptions. Since the schema covers the basics, a 4 is appropriate rather than a 5.

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

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

The description clearly states that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the exact resource (two prediction markets) and the action (comparing prices/spreads), and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on spread between venues rather than a single venue's arbitrage opportunities.

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

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

The description explains two usage modes (topic shortcuts vs explicit event parameters) and warns that most pre-mapped topics currently return compatibility warnings, setting expectations for when the tool is or isn't useful. It does not explicitly name alternative tools for when this tool should not be used, but the context is clear enough for an agent to decide, so a small deduction.

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 and idempotentHint, so the agent knows this is a safe read operation. The description adds the return type (attribute rows and geometry) and a usage tip, but does not disclose additional behavioral traits like error cases or rate limits. It is consistent with annotations.

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

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

The description is three sentences, front-loaded with the primary purpose. It efficiently lists the key parameters and includes a practical tip without redundancy. Every sentence contributes value.

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

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

No output schema, but the description communicates that the tool returns attribute rows and geometry, which is adequate. All parameters are already in the schema. The reference to search_datasets provides workflow context. Minor gaps like explicit pagination behavior are covered by the schema.

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

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

Schema description coverage is 100%, with each parameter described and defaults provided. The description's parameter overview (SQL-like where, comma-separated out_fields, etc.) does not add new semantics beyond the schema. The sampling tip is already implied by schema defaults.

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 action (Query) and the resource (ArcGIS Feature Service / Map Service layer), and it connects the tool to search_datasets. However, it does not explicitly differentiate from sibling tools like layer_info, though the query context implies data retrieval rather than metadata.

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

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

The description provides clear context for use (layers obtained from search_datasets) and gives a practical sampling tip (where="1=1" + out_fields="*"). It does not mention when to use alternatives or exclusions, but the context is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID), and it supports two distinct modes (retrieve vs. list). This goes beyond the annotations without contradicting them.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence earns its place: the first states the dual functionality, the second gives usage context, and the third explains scoping and companion tools. No unnecessary words or repetition.

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

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

For a tool with a single optional parameter, no output schema, and strong annotations, the description covers all essential aspects: purpose, usage context, scoping, and relationship to related tools. It adequately informs the agent about what the tool does and when to use it, making it complete for this level of complexity.

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

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

The schema provides a description for the 'key' parameter (omit to list all keys), giving 100% coverage. The description reinforces this and adds further meaning: the key was previously saved via 'remember', and gives practical examples of what the value might hold, such as a target ticker or address. This enriches the parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: retrieve a value previously saved via remember, or list all saved keys. It specifies the resource (memory) and the verb (retrieve/list), and distinguishes it from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names the complementary tools 'remember' and 'forget' and clarifies the scoping behavior, providing clear context for when this tool is appropriate.

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

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

The description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies a persistent state change. This directly contradicts the annotation readOnlyHint=true, which declares the tool as read-only. The contradiction is serious enough to invalidate behavioral transparency.

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

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

The description is front-loaded with the main purpose and consists of four tightly packed sentences. Every clause earns its place, including return payload details, filter examples, mark_read behavior, and an alternative HTTP endpoint. No wasted words.

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

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

Despite lacking an output schema, the description explains what each alert carries (source, citation_uri, raw payload). It covers filtering, incremental reads via mark_read, polling suitability, and provides an alternative for scripts. Parameters like limit and unread_only are already covered by the schema, so the description is sufficiently complete.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds semantic value by explaining filtering with 'type (e.g. "sec_8k") and/or since (ISO timestamp)' and clarifying the effect of mark_read. This exceeds the baseline for full schema coverage.

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

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

The opening phrase 'Pull fired events from your subscription feed' clearly identifies the tool's function with a specific verb and resource. It distinguishes itself from sibling tools like list_subscriptions (which enumerates subscriptions) and recent_changes (which tracks changes), making the purpose unambiguous.

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

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

The description provides clear usage context: 'Polls work fine' and explains how to use mark_read for incremental reads ('Set mark_read:true to flag returned events read so the next call only shows newer ones'). It also offers an alternative for direct scripts/dashboards via a URL, but it does not explicitly name sibling tools as alternatives or 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 mark this as readOnly, idempotent, openWorld, and non-destructive. The description goes well beyond these by detailing the fan-out to three sources, the GDELT→GNews fallback under rate limiting/5xx, and the USPTO soft-fail until May 2025. It also specifies the return format (structured changes[], total_changes, citation URIs) and the parallel-call behavior, giving the agent full insight into what will happen.

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

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

The description is dense and information-rich, front-loaded with user intent and supported by organized details about sources, parameters, and output. It is longer than the calibration examples but every clause contributes (e.g., provider sunset, fallback logic, return shape). The structure flows logically from use-cases to behaviors to parameters, although it could be split into bullet points for even quicker scanning.

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 (three upstream data sources, fallback rules, time-window parsing, structured return), the description covers all critical aspects: sources, fallbacks, soft-fail caveats, parameter syntax, recommended values, Return format, and differentiation from sibling entity_profile. No output schema exists, but the description compensates by naming the return fields and citation URIs. This is complete for an agent to select and invoke correctly.

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

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

The input schema covers all three parameters with descriptions and an enum for type. The description adds concrete usage context: `since` accepts both ISO dates and relative shorthand ("7d", "30d", "3m", "1y") and recommends "30d" or "1m" for typical monitoring. It also clarifies that type only supports "company" and provides example values for ticker/CIK, which is exactly the kind of extra semantic meaning that helps invocation.

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

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

The description opens with concrete user intents ("What's new with X" / "latest on Y") and defines the tool as a "change feed for a company in the last N days/weeks/months in ONE parallel call." It specifies the resources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from the sibling entity_profile by contrasting the dynamic change feed with a static profile.

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

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

The description provides clear when-to-use guidance through query examples and explicitly names the alternative: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." It also discloses provider fallback behavior (GDELT→GNews) and soft-fail conditions (USPTO), helping the agent decide if this tool fits the request.

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

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

Beyond the annotations (idempotent, non-destructive), the description adds critical behavior: key-value scoping by identifier, persistence for authenticated users vs. 24-hour retention for anonymous sessions, and cross-session reuse. 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 concise and front-loaded: purpose first, then usage, then storage details. Each sentence earns its place, with 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?

For a simple storage tool, the description is complete: it explains purpose, usage, persistence, scoping, and relationship to siblings. There is no output schema needed, and the description covers what the agent needs to know to invoke it correctly.

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

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

The input schema already covers both parameters (key, value) with descriptions and examples, so the description adds no new parameter-level information. It only mentions 'key-value pair' in prose, which is redundant with the schema. Baseline 3 is appropriate for 100% 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 states the tool saves data for later reuse with a specific verb ('Save data') and resource, and clearly distinguishes from sibling tools by explicitly naming recall and forget as complementary operations.

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

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

It provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference'), and mentions alternatives (recall, forget), giving the agent clear direction on how to choose among related tools.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses source-labelled identifiers, explicit unresolved fields, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal cascading through multiple endpoints. This adds significant behavioral context not present in 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?

Though lengthy, the description is front-loaded with examples and a clear directive, then structured by supported types. Every sentence contributes behavioral, usage, or parameter detail with no filler; the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates by explaining exact output contents: source-labelled identifiers, an explicit unresolved field, drug citation format, and graceful degradation. It also covers edge cases and example queries ('who owns X'), making it highly complete for a two-parameter 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%, but the description enriches parameter meaning by detailing what each type returns (e.g., CIK/ticker/LEI/FIGI for company, RxCUI/brand for drug) and accepted input forms. This goes beyond the schema's basic parameter descriptions, aiding correct selection of type and value format.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, with concrete query examples. It differentiates itself from siblings by positioning itself as the first tool to use when a name needs an ID, distinct from profile/search tools.

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

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

Provides clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or state when-not-to-use, 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 idempotentHint=true, so the agent knows it's a safe, non-mutating operation. The description adds behavioral context beyond annotations: it states the tool "Probes each entity ... with ai_visibility_check, ranks by score" and "Returns ranked list with score, confidence, signal density per entity," disclosing internal delegation and output structure. This enriches the annotation-only picture.

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

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

The description is four concise sentences, each carrying distinct information: purpose, mechanism, use case, and return value. It's front-loaded with the main action and avoids fluff. No redundancy.

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

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

The tool has 4 parameters, full schema coverage, annotations, but no output schema. The description covers what it does, how it does it (probes and ranks), and what it returns (ranked list with score/confidence/signal density). It doesn't mention error handling or edge cases, but for a non-mutating read tool with strong annotations, this is adequate.

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

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

Schema description coverage is 100%, and the schema already explains each parameter, including that the first entity is the subject. The description's mention of "your brand + N competitors" reinforces but doesn't add new parameter-level detail beyond the schema. Thus baseline 3.

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

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

The description opens with "Compare AI visibility across multiple entities side-by-side," a specific verb+resource that distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities. It further details that it probes each entity, ranks by score, and identifies most/least recognized, making the purpose unambiguous.

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

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

The description includes a concrete use case: "Useful for competitive AI-marketing audits: 'does Claude know about us as well as our competitors?'" This tells the agent when to employ it. It mentions it probes with ai_visibility_check, implying that tool is for single-entity checks, though it doesn't explicitly say "use this instead of..." so it's clear but not exhaustive.

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

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

The description discloses important runtime behaviors beyond the annotations: it fans out across two services, may take 5-30s on first bundlephobia measurement, and degrades gracefully with sources_failed listing timeouts. This complements the readOnly/idempotent hints with latency and partial-failure semantics.

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

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

The description is dense but well-structured: main purpose first, then return fields, then ecosystem scope and failure behavior. Each sentence adds distinct value, and the length is justified for a composite tool. No filler or repetition.

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

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

With no output schema, the description fully lists the return shape (summary fields, per-advisory detail, links, alternative versions), covers ecosystem limitations, and explains error handling. This gives an agent complete expectations for invocation and results.

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

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

Schema coverage is 100% with descriptive parameter text for both package and version. The description adds no new parameter meaning beyond restating the default behavior; it does reinforce that version is optional and defaults to latest, but that's already in 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 opens with a specific, outcome-oriented verb phrase ('should I add this npm package to my project' check) and enumerates the data sources (deps.dev and bundlephobia) and covered aspects (license, advisories, bundle size, etc.). This clearly distinguishes it from sibling tools like deep_research or validate_claim by stating its exact scope.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also cautions that the tool is NPM-only in v1 and directs other ecosystems to deps.dev:version directly, offering a clear exclusion and alternative.

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 the safety profile. The description adds valuable context by specifying the exact return fields (name, summary, record_count, owner/org, url) and the data domain (City of Mobile GIS). It does not mention pagination or rate limits, but the schema covers the limit parameter, and the annotations cover the read-only behavior, so the description provides adequate extra transparency beyond the structured data.

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

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

The description is two sentences long and front-loaded with the primary action ('Search City of Mobile GIS open geospatial datasets by keyword'), followed by a compact enumeration of return fields and a clear pointer to dependent tools. Every sentence contributes essential information without unnecessary 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?

Although there is no output schema, the description explicitly lists the return fields, which is critical given that a return format schema is lacking. It also provides domain context (parcels, zoning, public works & city services) and explains how to use the output url, making the tool self-contained for the user. Combined with the schema and annotations, the description is comprehensive for a search tool.

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

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

The schema has 100% coverage for all three parameters (query, limit, org_id), each with a clear description. The tool description does not add parameter-specific details beyond what the schema already provides; it only restates the keyword search concept and provides examples of dataset categories, which maps to the query parameter but does not enrich the semantics further. 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 uses the specific verb 'Search' with a clear resource ('City of Mobile GIS open geospatial datasets'), lists example categories, and explains the return payload (name, summary, record_count, owner/org, url). It distinguishes itself from siblings like query_layer and layer_info by explicitly stating that the returned url should be passed to those tools, confirming its role as a discovery tool.

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

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

The description clearly implies when to use the tool: to find datasets by keyword. It also directs the user to pass the resulting url to query_layer/layer_info, providing a clear next-step alternative. However, it does not explicitly state when not to use search_datasets or list other alternatives beyond those two sibling tools, 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses concrete behavior: returns character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and enforces a 200K char cap with truncation flagged. This adds substantial context about output structure and limitations, far exceeding annotation coverage.

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

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

The description is concise yet packed with useful information, front-loaded with the core purpose. Every sentence serves a purpose: what it does, when to use it, how it pairs with other tools, and technical constraints. 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?

Despite lacking an output schema, the description explicitly states return values (passages with offsets and similarity scores). It covers performance characteristics, input limits, and integration with a sibling tool. For a search tool of moderate complexity, this provides a complete picture for an agent to decide and invoke successfully.

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

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

Schema coverage is 100% with detailed descriptions for all parameters, so baseline is 3. The description adds minimal new parameter semantics beyond schema, though it reinforces the text cap and gives query examples already present in the schema. It does not meaningfully improve parameter understanding beyond what 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 a specific action: 'Semantic search INSIDE a fetched record', and specifies inputs (text, natural-language query) and outputs (top-N passages with character offsets and similarity scores). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with searching the whole document.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt', and names an alternative flow with ask_pipeworx_grounded. This gives clear context and direct comparison to a sibling tool, demonstrating when this tool is preferred.

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 this as non-read-only, idempotent, and non-destructive. The description adds valuable operational details beyond these: it returns a new subscription id, requires authentication, mandates phone verification before SMS delivery, and enforces a 10/day SMS cap. It also clarifies that the feed is always enabled. 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 a single dense paragraph but well-structured with colons and parentheses, front-loading the action. Every sentence serves a purpose: purpose, return value, auth prerequisite, supported types, and delivery options. It could be slightly more readable with bullet points, but the length is justified by the tool's complexity.

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

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

With 3 parameters, nested objects, and no output schema, the description covers the essential aspects: return value, prerequisites, subscription types, and delivery constraints. It works together with the schema to provide a complete picture. Minor gaps exist (e.g., error handling, idempotency details) but these are not required for a create tool with rich annotations.

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

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

The input schema has 100% parameter coverage with descriptions, providing the baseline of 3. The description enhances this by giving concrete, type-specific examples like items:['5.02'] for sec_8k and topic:'fed' for polymarket_edge, which add semantic understanding beyond the schema's generic 'Type-specific filter' phrase. This illustrates how params map to real use cases.

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 'Create a proactive monitoring subscription to a live-data event stream', a specific verb+resource phrase that unambiguously states the tool's function. It clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action, leaving no doubt about its role.

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

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

The description provides clear context for when to use this tool: it requires a Pipeworx OAuth account, lists supported subscription types with example parameters, and explains delivery channels including the always-on feed and optional email/SMS. It references recent_alerts as an alternative for pulling the feed, implying a distinction between proactive (subscribe) and reactive (pull) monitoring. However, it doesn't explicitly state when not to use `subscribe` compared to other tools, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond this: it returns category-bucketed example questions with tool+argument shapes, and that calling with no arguments yields the full spread. This enriches the agent's understanding of what to expect without contradicting annotations.

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

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

The description is longer than average but every sentence contributes value: it opens with natural-language examples, explains the output, provides usage scenarios, and conveys the exact tools. The structure is front-loaded with the core concept and flows logically, 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?

Given the absence of an output schema, the description compensates by explaining the return format (category-bucketed questions with tool+argument shape). It also covers the optional parameter, the no-argument behavior, and the tool's role as an onboarding entry point. This is a complete picture for an agent to decide when 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 coverage is 100% with the topic parameter already described. The description adds meaningful examples ('finance', 'pharma', 'betting') and clarifies that omitting it gives a cross-category spread, which goes beyond the schema's enumeration and helps the agent decide how to use the 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 clearly states the tool's purpose: it returns category-bucketed example questions with the exact tool and argument shape that answers each. It distinguishes itself from siblings by positioning as 'the onboarding entry point' for an agent that just connected, making it distinct from discover_tools or ask_pipeworx.

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

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

The description gives explicit guidance on when to use it: '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 and how to get the full spread. While it doesn't name specific alternatives or state when not to use it, the context is clear and 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behaviors: ownership enforcement, row deactivation not deletion, and preservation of historical events via recent_alerts. This adds significant value beyond the structured 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 compact sentences, front-loaded with the verb and object, and every sentence adds useful content. No wasted words.

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

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

For a simple one-parameter tool with annotations covering mutability and idempotency, the description covers purpose, ownership, and side effects. No output schema means return value explanation is unnecessary. Complete for the tool's complexity.

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

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

The schema already fully describes the only parameter (id as a uuid returned by subscribe). The description adds no additional parameter semantics beyond repeating 'by id'. With 100% schema coverage, 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 action ('Cancel a subscription by id') and specifies the resource (subscription). It distinguishes from siblings like subscribe and list_subscriptions by using 'Cancel' as the verb.

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

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

The description gives clear usage context: you can only cancel your own subscriptions, and the operation deactivates rather than deletes. It does not explicitly mention alternatives, but the context is sufficient for a straightforward tool.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description substantially adds critical behavioral context: the meanings of 'could_not_verify' (with verification_error), 'unsupported', the fallback logic between SEC EDGAR and grounded pipelines, and verdict types. This goes well beyond the annotations and helps the agent interpret results correctly.

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

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

The description is dense and well-structured: it opens with concrete trigger phrases, then states when to use, explains the two routing paths, defines verdict semantics, and closes with the efficiency benefit. Every sentence carries necessary information without redundancy or fluff.

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

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

Given the tool's complexity (two pipelines, five verdicts, error semantics) and the lack of an output schema, the description fully explains return values, the meaning of 'could_not_verify' vs 'unsupported', and the overall workflow. It is complete enough for an agent to correctly use and interpret results.

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

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

Schema coverage is 100% with detailed descriptions for both claim and tolerance_pct, including examples and default behavior. The description adds minimal extra meaning beyond reinforcing that the claim is natural-language and the tolerance can be overridden. It meets the baseline but doesn't elevate it.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides trigger phrases like 'fact check' and 'verify the claim that…', and distinguishes itself from siblings by explaining it replaces 4–6 sequential calls, covering both SEC EDGAR financial verification and a grounded pipeline for other claims.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the two distinct paths (financial vs. general claims). However, it does not name alternative tools or explicitly state when not to use it, only implying it consolidates multiple steps.

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