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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context: it routes to a large tool set, returns structured answers with stable pipeworx:// citation URIs, and is described as 'one fast call'. These details go beyond annotations without contradicting them. A small gap is lack of failure/error behavior, but annotations carry the safety profile, so a 4 is appropriate.

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 (several sentences) but every part earns its place: it front-loads the core directive ('PREFER OVER WEB SEARCH'), provides domain lists, usage examples, and sibling routing. It could be trimmed slightly (e.g., the list of domains is exhaustive), but the structure is logical and the critical guidance is prominent. It's not tautological or padded, though it is dense.

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 as a router, the description covers: when to use (most factual questions), what it returns (structured answer with citations), how it works (routes to 5,892 tools), examples, and how to choose among siblings. There is no output schema, but the description explicitly mentions the return format. No missing information that an agent needs to call this tool correctly is evident.

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

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

Schema coverage is 100%: all six parameters are documented in the schema as aliases for 'question'. The description repeats that aliases are accepted ('Accepts query, q, prompt, text, input as aliases'), which adds no new semantic meaning. The description does explain the parameter's role in the context of routing, but since the schema already fully documents the parameters, the baseline of 3 applies – the description adds minimal value beyond the schema.

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

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

The description states a clear purpose: answering factual questions by routing to 5,892 tools across 1,538 sources. It explicitly lists domains (SEC filings, FDA, economic stats, etc.) and differentiates from siblings ask_pipeworx_grounded and deep_research by naming their specific use cases. This is far more than a vague 'answer questions' – it's precise and distinguishes the tool's role.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It also gives concrete alternatives with conditions: use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions, and notes it handles breaking news. This is model guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it is a beta with candidate routing improvements, currently matches stable exactly, and is a full working router rather than a stub. This goes beyond the annotations.

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

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

The description is slightly lengthy but front-loaded with the key fact that it's a beta version of ask_pipeworx. Each sentence adds meaningful information about experimental status, current equivalence, and usage. It could be trimmed slightly but remains efficient for the complexity it conveys.

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

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

Given there is no output schema, the description compensates by stating the response shape is identical to ask_pipeworx, which an agent can reference. It covers the experimental nature, current state, and usage guidance. Combined with annotations and schema, nothing critical is missing for an agent to call 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 schema has 100% coverage, describing the 'question' parameter and all aliases clearly. The description does not add any parameter-specific meaning, but since the schema already documents everything, the baseline of 3 is appropriate. No additional value is needed here.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by being the experimental edge, so an agent can tell it apart from the sibling tool without ambiguity.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing', which gives a clear usage condition. It also notes that results are compared against the stable router to decide merges, implying it's for experimental evaluation. However, it does not explicitly state when NOT to use it (e.g., for stability-critical tasks), leaving some room for inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description goes well beyond that: it discloses the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), the refusal modes, the mechanism of extracting only from tool results, and the extra LLM call cost. This is rich behavioral context that annotations do not cover.

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

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

The description is dense but every sentence serves a purpose: purpose, mechanism, return format, refusal conditions, usage guidance, and cost trade-off. It is front-loaded with the key differentiator (hallucination-resistant) and organized logically. 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 complex tool with special grounding behavior, the description covers all necessary aspects: what it does, when to use, what it returns, failure modes, and cost implications. Even without an output schema, the return shape is explicitly described. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% – each parameter (all aliases of 'question') is described. The description adds no parameter-specific guidance beyond what the schema provides, and the schema already explains natural-language input and aliases. A baseline 3 is appropriate since the schema handles 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 it is a 'hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx but extracts the answer strictly from tool results. It names the sibling ask_pipeworx and distinguishes the grounded variant's purpose, so an agent knows exactly what this tool does and how it differs.

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: 'whenever an answer will be quoted, cited, or acted on' and 'the agent must not invent facts.' It also gives the alternative: 'prefer ask_pipeworx for casual lookups,' and notes the cost trade-off. This is clear, actionable guidance for selecting between siblings.

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

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

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?

Annotations only state readOnly/openWorld/idempotent/non-destructive. The description goes far beyond: account requirement, paid depth tier, parallel tool routing, gap recovery, contradictions[] for certain depths, citation_uri always fetchable, large-record excerpting, and expected latency. It also clarifies it never invents findings. This is rich, non-redundant behavioral context with 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 and dense, but it front-loads the most critical operational constraint (account requirement) and the sibling alternative. Every sentence adds either a constraint, a behavior, or a routing hint. It is not tautological, though it could be tightened without losing substance; still, for a tool of this complexity, the length is justified.

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

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

Given the tool's complexity, the description covers account/auth, pricing, when to use alternatives, return packet contents (evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), time expectations, and the behavior of each depth mode. There is no output schema, so the description carries the full burden of explaining the result format, which it does thoroughly.

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

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

Schema coverage is 100% and the depth parameter already has a detailed description. The tool description still adds meaningful context by explaining the second-hop iteration, gap recovery, contradictions scan, and the trade-offs between depth levels (e.g., 'thorough' is paid and chases leads). It reinforces and enriches the schema without simply repeating 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 states a precise verb ('grounded multi-source research'), a specific resource (Pipeworx's 1538 structured data sources), and explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx. It clearly frames what the tool does and what it does not, so an agent can immediately differentiate it from its siblings.

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

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

It explicitly tells when to use deep_research (broad/multi-part questions over structured data) and when not to (single lookups, breaking/current news), naming ask_pipeworx as the alternative in both cases. It also covers account tiers and second-hop iteration, leaving no ambiguity about invocation context.

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

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

Annotations already declare 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 establish read-only, idempotent, non-destructive behavior, and the description adds substantial behavioral context: parallel fanout across many sources, per-section return semantics, soft-fail for sunset APIs, fallback behavior, sources_used/sources_failed, and the expected-empty FDA section for companies without biologics. This far exceeds what the annotations alone provide.

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

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

The description is front-loaded with user intent examples and the key routing rule, and the long tail contains dense, mostly necessary detail about sources, return sections, and edge cases. It is verbose and somewhat repetitive, but the length is justified by the tool's complexity and the absence of an output schema.

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

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

Given there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: every result section is named, failure modes are explained, empty results are distinguished from bugs, and private-company behavior is specified. An agent has enough context to call this 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 documents both parameters fully at 100% coverage, including the type enum and accepted value forms. The description mostly restates this, adds examples, and notes resolved_from/resolved_to, but that is output behavior rather than new parameter semantics.

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

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

The description states a specific action and resource: building a full cross-source profile of a US public company in one parallel call, backed by many concrete user-intent examples. It clearly differentiates from chaining individual lookups, though it does not name or explicitly differentiate from sibling tools like deep_research or compare_entities.

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

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

It gives an explicit routing instruction: ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also specifies accepted input forms and private-company behavior, but it does not state when to prefer siblings such as deep_research or compare_entities.

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

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

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?

Even though annotations already assert readOnly, idempotent, and non-destructive behavior, the description goes far beyond them: it discloses safety fields (compatibility_warning and compatibility_codes), the gross-not-net fee limitation, null semantics for temporal_alignment, and the pairing_unverified flag that is set in either mode. It also spells out that unknown metric_type/match_subtype legs are never paired and explains skipped_cross_type/subtype counters. This is exemplary disclosure of the tool's limitations and edge cases.

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

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

The description is extremely long and dense, with capitalization-heavy inline sections that are hard to scan; nearly every sentence carries a distinct caveat, but the wall-of-text structure hurts readability. It is front-loaded with the core purpose and key safety framing, but the volume of detail could be better organized into bullets or a table. It earns its place content-wise, but not concision-wise.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does: it covers per-venue leg prices, top_spreads_pp, per-entry flags, temporal_alignment semantics including the null case, fees_note, skipped counters, and unclassified/skipped leg behavior. It also handles edge cases like unknown metric types and unverifiable pairing. For a complex, high-caveat tool, this is complete.

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

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

Schema coverage is 100%, and the description still adds substantial meaning beyond the schema: it enumerates the ten topic shortcuts with examples, explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and states that both modes run the identical token-overlap matcher. It also clarifies the relationship between the parameters (topic vs explicit pairing fields) in a way the schema alone does not.

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 sentence names the exact cross-venue deliverable (spread between Kalshi and Polymarket for the same resolving question) and distinguishes it from generic arbitrage tools by scoping it to equivalent bet shapes. The two-mode description (topic shortcuts vs explicit ticker/slug) further pins down the operational surface. Among siblings like polymarket_arbitrage and polymarket_edges, this is unmistakably the Kalshi–Polymarket spread comparator.

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

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

The description gives strong when-to-use context: it explains when the delta is a real signal (equivalent bet shapes), when the tool says so, and how to choose between topic mode and explicit mode with override semantics. It also cautions that most pre-mapped topics return compatibility_warning today and that pre-mapped ≠ tradeable, steering agents away from blind use. It does not explicitly name sibling alternatives, but the routing context is clear.

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

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

Annotations already declare readOnlyHint 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 readOnly/openWorld/idempotent annotations, the description discloses critical runtime behavior: multi-source cascading, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting instead of omission, and ambiguous-match handling via `figi_candidates`. This substantially enriches what annotations alone convey.

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

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

The description is front-loaded with examples and the core purpose, but the 'company' bullet contains a very long parenthetical that mixes many distinct behaviors into one dense block. Every sentence earns its place for the complexity it covers, but the structure could be tightened without losing information.

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

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

For a 2-parameter tool with no output schema, the description is complete: it covers both entity types, accepted inputs, return fields (CIK, ticker, LEI, FIGI, RxCUI, etc.), failure behavior, and degradation. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is already 100%, and the description goes well beyond baseline by explaining each enum value, providing concrete examples (AAPL, 0000320193, ozempic), and adding a crucial edge-case rule for bond issuer names. The 'ENTITY NAME ONLY' instruction prevents a very plausible misuse.

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 example queries and the crisp statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also explicitly says 'Use FIRST whenever you have a name but need an ID,' which makes its role relative to sibling tools like entity_profile and compare_entities clear.

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

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

It gives an explicit trigger condition ('Use FIRST whenever you have a name but need an ID') and rich input guidance, including accepted formats (ticker, CIK, ISIN, name), the warning to pass only the issuer name for bonds, and the behavior for non-ticker instruments. This is far beyond minimal usage guidance.

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

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

Annotations already 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.