Arcgis Adamscounty

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

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

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

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

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

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

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

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

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

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

Schema covers all parameters, but the description adds the concrete default model name ('Workers AI Llama-3.3-70b') and reinforces the dependency between `models` and `_apiKey`, helping the agent reason about configuration.

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

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

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

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

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

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

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds meaningful behavioral context: it routes dynamically across thousands of tools, fills arguments, returns structured answers with stable citation URIs, and handles breaking-news queries. There is no contradiction with annotations, and the agent gets an accurate model of what happens when the tool is invoked.

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

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

The description is long but front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and organized into domain list, routing behavior, trigger phrases, and examples. Some redundancy exists between 'even if web search could also answer' and 'START HERE for most questions,' but the length is largely justified by the tool's broad scope.

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 broad routing tool with one required natural-language parameter and no output schema, the description covers function, routing behavior, citation output, triggering conditions, and representative examples. An agent has enough information to decide when to call it and what to pass.

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 the natural-language 'question' parameter and its aliases. The description contributes useful example queries and notes that the tool 'fills arguments', but it does not add per-parameter meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific action ('routes the question to the right one of 5,798 tools... returns the structured answer with stable pipeworx:// citation URIs') and clearly names the resource and scope. It also differentiates the tool from web search and signals it is the umbrella entry point ('START HERE'), which separates it from specialized sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...'), concrete example triggers, and names the main alternative (web search). It lacks an explicit when-not-to-use or a direct comparison with sibling variants like ask_pipeworx_grounded/beta, so it is 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 adds substantial context beyond the read-only, open-world, idempotent annotations: experimental status, live candidate routing improvements, current state as of the last retirement date, comparison against the stable router, and the important caveat that there is no fallback because this is a fully working router.

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

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

The description is compact and well-organized: it front-loads the core purpose, then states current behavior, usage instruction, and the no-fallback caveat. The repetitive 'same ... same ... same ...' phrasing is slightly wordy, but every sentence contributes essential information for an experimental tool.

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

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

The description is largely complete for a read-only routing tool with annotations and full schema coverage. It references the same response shape as ask_pipeworx, which compensates for the lack of an output schema, and it explains the current runtime state. A fully independent description of the response format would make it more complete, but referencing the sibling is reasonable here.

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 schema already documents the parameters. The description adds the useful meta-information that arguments are identical to ask_pipeworx, but it does not explain the individual parameters 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 clearly identifies this as the beta variant of ask_pipeworx: a universal router with the same 5,798 tools, arguments, and response shape. It also explicitly distinguishes it from stable ask_pipeworx by stating that candidate routing improvements are enabled live during tests.

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 a direct usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that when no candidate is active it currently matches ask_pipeworx exactly. However, it does not explicitly mention the grounded sibling variant or state when not to use this tool.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses the exact success shape, the refusal contract with five enumerated refusal reasons, that it uses only tool-result content, and that it costs one extra LLM call. This gives the agent a precise model of the tool's behavior.

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

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

The description is front-loaded with its purpose and then each sentence covers one necessary aspect: routing, return contract, usage, and cost tradeoff. Every sentence earns its place with no filler.

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

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

With no output schema, the description fully specifies the return contract on both success and refusal paths, states cost and usage boundaries, and the schema covers all input parameters. An agent has everything it needs to invoke and interpret 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 description does not add parameter-level meaning, but schema description coverage is 100% and the question parameter is already documented as natural language with aliases. No compensation is needed, so a baseline 3 is appropriate.

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

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

The description states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the grounded extraction behavior, distinguishing it from the sibling ask_pipeworx. It clearly identifies the operation (answer a question using only tool results) and names the sibling it diverges from.

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

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

It explicitly says to use it when answers 'will be quoted, cited, or acted on' and when the agent 'must not invent facts', and to prefer ask_pipeworx for casual lookups. This is direct when-to-use and when-not-to-use guidance with a named 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals critical behavioral details: parallel fan-out, resolver contract with confidence levels, status codes for low-confidence or closed markets, news fallback handling, illiquid spread warnings, and cancellation rule parsing. This is substantial extra context.

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

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

The description is very long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the core purpose, but could be trimmed for conciseness without losing essential information.

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

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

Given there is no output schema, the description thoroughly explains return values, resolver contract, parent event extraction, news fields, safety statuses, and resolution rules. It even covers edge cases like de-indexed markets and flat-50¢ void settlements, making it highly complete for a complex tool.

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

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

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

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', with a specific verb and resource. It also gives explicit use cases ('should I bet on X') that distinguish it from sibling tools focused on arbitrage or edge tracking.

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

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

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

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

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

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

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

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

The description is longer than average but each clause provides useful information: usage patterns, data sources, sorting behavior, and return format. It is front-loaded with example queries and uses emphasis to highlight the key preference instruction. Slightly dense, but no wasted content.

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

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

Given no output schema, the description explains return values ('paired data + pipeworx:// citation URIs'), includes relevant edge-case behavior (off-calendar fiscal years), and quantifies efficiency gains (replaces 8–15 lookups). It fully addresses the complexity of a comparative lookup tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the entity type param with specific metric mappings (company vs drug) and giving concrete format examples for the values array (tickers vs drug names). This goes beyond what the schema states, earning a 4.

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

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

The description clearly specifies the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sequential single-pack lookups by naming the alternative pattern and providing concrete user-phrase examples (X vs Y, rank these companies).

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides a clear alternative to avoid. It also differentiates between company and drug use cases with specific data sources and metrics, guiding the agent's selection.

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

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

Annotations already mark it read-only and non-destructive; the description adds substantial behavioral context beyond annotations: account and paid-plan requirements, parallel decomposition across ~5,798 tools, latency expectations, explicit gaps[]/contradictions[] behavior, 'never invented' grounding, semantic excerpting, and the guarantee that citations are fetchable. 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 account requirements and the ask_pipeworx fallback, but it is long and redundant: 'use ask_pipeworx instead' appears twice, and the depth/hop/contradictions behavior repeats what the schema already says. The 'Second-hop iteration...' phrasing is also confusing and could be tightened.

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

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

Despite no output schema, the description fully describes the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]) and covers auth, pricing, latency, source scope, and error/uncertainty behavior. For a two-parameter tool this leaves no significant gap an agent would need 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?

Schema description coverage is 100% and the schema already documents each depth level, including the paid 'thorough' tier and hop behavior. The description mostly repeats those details, adding only latency and auth context rather than new parameter semantics, so the baseline 3 is appropriate.

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

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

The description states a clear verb+resource: grounded multi-source research across Pipeworx's 1517 structured data sources in one call. It also distinguishes itself from alternatives by explicitly saying 'this is NOT open-web search' and framing itself as the complementary option to ask_pipeworx, making its scope unambiguous.

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

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

Provides explicit routing guidance: if not signed in, use ask_pipeworx instead; for a single lookup, use ask_pipeworx instead; and it is 'best for broad/multi-part questions over structured data' with concrete examples. These statements directly tell an agent when to choose this tool vs its 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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations by disclosing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' It could mention pagination or error behavior, but given the annotation coverage, this is strong.

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

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

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

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

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

With no output schema, the description must account for return values, and it does: it specifies names, descriptions, schemas, and curated examples. It also provides strong usage context and domain examples. It lacks edge-case handling (e.g., zero results), but for a discovery tool with solid annotations, this is nearly complete.

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

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

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

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

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

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

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

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

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

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

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

Annotations already mark it readOnly, openWorld, idempotent, non-destructive, and the description adds substantial behavioral detail: it fans out across many sources, soft-fails USPTO after May 2025, treats empty sections as real no-data, and returns resolved_to/resolved_from for name inputs. It also explains expected empty results for fda_products with small-molecule-only companies, which prevents false bug reports.

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

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

The description is long but front-loaded with example intents and the key directive to prefer this over chaining. Every sentence carries operational information, especially around source fan-out and failure semantics; however, some details repeat schema content (e.g., both values are interchangeable) and the return list could be more compact.

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 and the tool has a complex multi-source return structure, but the description enumerates every returned section (cik, fundamentals, patents, contracts, fda_products, hiring, news, LEI, sources_used/failed) and explains edge cases like private companies and expected empty sections. No critical information needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: 'company' and 'ticker' are interchangeable and both accept ticker, CIK, or name values, names resolve via SEC EDGAR, and CIKs should be zero-padded. Examples like 'AAPL', '0000320193', and 'Moderna' reinforce the accepted shapes.

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 names a specific action — producing a 'full cross-source profile of a US public company in ONE parallel call' — and gives multiple natural-language triggers ('Tell me about X', 'research Acme', 'brief me on Tesla'). It clearly distinguishes itself from single-pack lookups and related siblings like compare_entities and resolve_entity.

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

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

The description explicitly says 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, and explains behavior for private companies via resolved:false. It does not name sibling alternatives like resolve_entity or compare_entities for narrower comparisons, so some routing to siblings is left implicit.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful process details: it fetches the page, extracts title/description/key links, and outputs a text blob. This goes beyond the annotations, though it does not disclose potential failure modes or rate limits, which would push it to 5.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, with both url and max_links clearly documented. The description does not add extra semantic detail about the parameters themselves, so it meets the baseline for high coverage but does not enhance understanding beyond the schema.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL, with specific steps (fetches, extracts, emits). It is specific with a verb and resource, but does not explicitly distinguish itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence, so it misses the top score.

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

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

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

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

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

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

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

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

The description is a single, concise sentence that front-loads the action and includes specific return details. Every word earns its place, with no fluff or redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a simple list tool with no required params and no output schema, the description is complete: it states scope, what it returns (specific fields), and when to use it. Safety is covered by annotations, and the schema handles the one optional param. Nothing essential is missing.

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

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

Schema coverage is 100% since the only parameter include_inactive has a clear description in the schema. The tool description adds the word 'active' which aligns with the default behavior but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

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

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

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

The description provides explicit use cases: 'to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it, but it doesn't mention when not to use it or explicitly name alternative tools, though the use cases implicitly distinguish it from subscribe/unsubscribe.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description explicitly states what the tool does: it reports what other AI agents are calling on Pipeworx, including top tools, top packs, and total call volume over a window. This is a specific verb+resource combination that clearly distinguishes it from sibling tools like ask_pipeworx or discover_tools.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

There is no output schema, so the description must enumerate return values, and it does for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, capture_ratio, thin_legs, etc. for basket). It also explains the risk implications and prerequisites, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: the 'REQUIRES one of market or event' constraint, mode-specific interpretation of side, and the distinction between single-market spend/proceeds vs basket settlement notional. This goes beyond simple parameter listing, though not by a huge margin.

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

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

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

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

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

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

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

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

Annotations already signal read-only, idempotent, open-world, and non-destructive behavior, but the description adds substantial behavioral context beyond that: pairing is keyword-based and never fully verified, Kalshi fees are not modeled, unknown legs are never paired, temporal_alignment null has a specific meaning, and compatibility_codes[] can be non-empty even when pairs are returned. These caveats materially affect how an agent should interpret results.

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 long, but the length is earned by the tool's complexity and the many safety/interpretation caveats an agent must know. It front-loads the core purpose and modes before diving into return fields and codes. It is not as scannable as it could be — one large paragraph rather than clear sections — but nearly every sentence carries actionable 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 provided, the description does the necessary work of explaining the response shape, safety fields, compatibility codes, per-pair flags, skipped-leg counters, fee disclosure, and temporal alignment semantics. It also tells the agent exactly what to check even when matched_pairs > 0. For a complex cross-venue comparison tool, this is a remarkably complete description.

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

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

The input schema already documents all three parameters and even includes override semantics, so the baseline is 3. The description adds meaning by explaining that `topic` auto-fetches matching events from both venues, that explicit ticker/slug parameters create custom pairings, and that both modes run the identical token-overlap matcher. This is useful semantic context beyond the schema's individual parameter notes.

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, unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this tool from sibling Polymarket tools by focusing on a Kalshi–Polymarket comparison and clearly stating what it returns (leg prices and top_spreads_pp). The two modes are also explicitly defined, so an agent can immediately understand the tool's 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?

The description gives clear guidance on when to use the `topic` shortcuts versus explicit `kalshi_event_ticker` + `polymarket_event_slug`, and warns that most pre-mapped topics return compatibility warnings today. It does not explicitly name sibling alternatives such as polymarket_arbitrage, so it stops short of full when-not-to-use-this-tool guidance, but the mode selection and caution about pre-mapped topics are strong usage direction.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It provides concrete user intents ("What's new with X" / "latest on Y") and explicitly says 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains the GDELT→GNews fallback and when each source is used, giving an agent clear selection criteria and expectations.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. No contradiction with annotations; extra specifics beyond annotation hints.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare read-only, open-world, and idempotent hints, so the bar is lower, and the description adds substantial behavioral detail: cascading internal lookups, graceful degradation when LEI/FIGI enrichment is unavailable, ambiguous matches returning figi_candidates rather than asserting, explicit unresolved identifiers, and source-labeling of each identifier. 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 intent and usage guidance, and the SUPPORTED TYPES structure improves scannability. It is quite long and contains dense run-on sentences, but for a tool with this much multi-source complexity and edge-case behavior, most sentences earn their 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?

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: it covers resolved identifiers, unresolved fields, candidate disambiguation, source provenance, and output formatting such as the RxNorm citation. Both required parameters are fully documented in the schema and further clarified in the description.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning beyond the schema: it explains what each identifier type resolves to, how ISINs map to legal entities, and gives a critical input-format warning to pass only the entity name, not the full noun phrase, so that security-class trailing words do not break matching.

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 purpose: resolve a user-spoken NAME to canonical/official identifiers other tools require as input, with specific query examples that an agent is likely to see. It also distinguishes itself from siblings like entity_profile and compare_entities by positioning it as the identity-resolution first step.

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?

Clear and explicit: 'Use FIRST whenever you have a name but need an ID.' It gives strong when-to-use guidance and lists supported entity types. However, it does not explicitly name sibling alternatives or say when not to use this tool versus compare_entities, entity_profile, or deep_research.

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

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

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

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

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

The description is four sentences, each serving a distinct purpose: state the operation, explain the mechanism, provide the use case, and list the return structure. It is front-loaded with the core purpose and contains zero filler or repetition. It is concise while packing substantial information.

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

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

For a tool with no output schema, the description fully covers what the agent needs: what it does, how it works (multi-entity comparison via probing), when to use it, and what it returns (ranked list with score, confidence, signal density). The annotations and schema cover safety and parameter details. Given the moderate complexity, the description is complete and self-sufficient.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description provides clear usage context: it is for searching datasets by keyword and explicitly directs the user to pass the resulting url to query_layer / layer_info, implying a workflow. It does not explicitly mention when not to use this tool or compare with all siblings, but the downstream link and keyword-search framing make its intended use unambiguous.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it gives concrete examples for 'text' (SEC 10-K body, article, long tool result) and for 'query' (supply-chain risk, fiscal year 2024 revenue, drug interactions). It also explains that 'limit' controls the top-N passages returned. This enhances understanding of parameter usage.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly identifies what the tool does, including input (text already pulled) and output (top-N passages with character offsets and similarity scores). It also distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and focusing on search within a single fetched record rather than broader retrieval.

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

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

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

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

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

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

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

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

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

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

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

With no output schema and complex nested parameters, the description compensates by covering the return value, all subscription types, auth, and delivery channels. The schema fills in webhook details, so the combined definition is complete. The description adds context beyond the structured fields, making the tool highly usable.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter to focus the response, giving clear when-to-use context.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds important behavioral context: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events. No contradiction with annotations.

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

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

Two sentences, front-loaded with the primary action, and every sentence contributes meaningful information (ownership, deactivation, historical availability). Perfectly concise for a simple tool.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is longer than typical but every sentence earns its place: trigger phrases, usage contexts, routing logic, verdict list, and a critical caller warning. It is front-loaded with purpose and ends with an efficiency note. While not as terse as a two-sentence example, it is well-structured and dense with high-value information.

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

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

Given this tool has no output schema, the description comprehensively covers return values: verdicts, actual value with citation, reasoning, and error fields. It also explains the two processing pipelines and the special cases of 'could_not_verify' and 'unsupported'. For a complex tool, this is highly complete and leaves few gaps for the agent.

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

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

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

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

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

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

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

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

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

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