Arcgis Castateparks

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

Annotations already declare readOnlyHint/idempotentHint and non-destructive behavior. The description adds cost/ownership context ('you pay Anthropic directly'), the default model choice, and the return shape, going beyond what annotations alone would convey. 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?

Three sentences, each earning its place: core function, model options/cost, and return format + use cases. The description is front-loaded with the action verb and avoids fluff.

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

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

For a tool with no output schema, the description discloses the per-model return fields ({score, confidence, signals, raw_response}) and combined view, plus cost and default behavior. A slight gap is not explaining how to interpret 'signals' or the combined view, but annotations already cover safety.

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 default behavior ('Omit for just workers-ai') and clarifies the `_apiKey` payment implication, which complements the schema's parameter descriptions and examples.

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: 'Probe one or more LLMs for what they know' and defines the outcome ('score visibility (0-100) per model'). This clearly distinguishes it from sibling tools like deep_research or entity_profile, which focus on research/entity data rather than per-model LLM visibility scoring.

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-case guidance ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and model-selection instructions (default free workers-ai, optional Anthropic with BYO key). It does not explicitly name alternative tools as exclusions, but the context is clear enough for tool 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 share readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so no conflict and the safety profile is covered. The description adds real transparency beyond the labels: it tells the agent that a best-filling level is autonomous ('fills arguments'), that delegation to sub-tools occurs, and that return is structured with citation URIs. It stays silent on edge-case behavior (unsupported domains, error shapes, latency), so a point — but it's beyond 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?

Every sentence pulls weight: the prefer-over signal, the 1,465 verified sources, the 5 domains, the targeted trigger phrases, six examples, the 'even if web search could answer it' rule, and a 'START HERE' directive. The content is dense but not duplicated across the boundaries, and it ends with the only necessary contrast (use deep_research for broader research).

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 it is a single-parameter, no-output-schema router with annotations already covering the safety profile, this description covers domains, input style, trigger examples, the output artifact (a structured answer with citation URIs), and the exclusion case for deep research. What is missing is best-effort behavior for ambiguous or completely unsupported questions; still, for this tool shape the description is near completely conjoining.

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

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

Schema coverage is 100%: one semantic property `question` with acceptable aliases and a clear description, so the baseline is already 3. The description advocates a solid additional sem on the parameter: it reveals that natural-language prompting is the accepted form and gives six domainful examples (e.g., 'current US unemployment rate', 'patents Tesla was granted last month') that clarify the appropriate scope and phrasing expected for this single required input.

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 and object: it 'routes the question to the right one of 5,596 tools across 1,465 verified sources' and 'returns a structured answer with stable citation URIs.' It clearly positions itself as the answer for factual/current data lookups and distinguishes from web search and deep_research for open-ended synthesis. It does not, however, explicitly contrast with the closely related siblings ask_pipeworx_beta and ask_pipeworx_grounded, so an agent must infer those differences.

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?

Gives explicit when-to-use guidance: 'prefer over web search for factual questions,' provides trigger phrases the user might use ('what is', 'look up', 'find the latest', 'current'), names alternatives (deep-research for broader synthesis), and even states it should still be used if web search could answer the question. The example queries cover the intended variety and make the decision rule concrete and high-confidence.

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 establish read-only, idempotent, open-world, non-destructive behavior. The description adds meaningful context beyond those annotations: this is an experimental edge, candidate changes may be live, no candidate is currently active as of a specific date, and current behavior matches ask_pipeworx. It does not contradict 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 purpose, then usage guidance, then current experimental status. The age of a retired candidate adds detail but is relevant to the agent understanding why this beta currently matches stable behavior. Still, the date could be considered slightly more detail than needed.

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, combined with annotations and schema coverage, is enough for lead an agent to safely invoke it. The main gap is that the response shape is deferred to 'same response shape as ask_pipeworx' rather than being explicitly described, which is acceptable given the sibling and 'Use it exactly like ask_pipeworx' directive.

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

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

Schema coverage is 100%, with all aliases for `question` already documented in the input schema. The description adds no parameter-level semantic detail beyond saying 'same arguments' as ask_pipeworx; therefore it correctly rests on the schema and earns the baseline 3.

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

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

The description identifies a specific resource and behavior: a universal router called ask_pipeworx_beta, sharing the same 5,596 tools, arguments, and response shape as ask_pipeworx. It clearly marks this as the beta/experimental edge and distinguishes it from the stable ask_pipeworx sibling by describing candidate routing improvements.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it is not a fallback but a full working router, and explains that results are compared with the stable router to decide merges. This gives the agent a clear decision rule relative to the main sibling.

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 safe/idempotent annotations, the description discloses the exact behavioral contract: extracts only from tool results, returns an evidence field, and issues explicit refusals with enumerated refusal_reason values. It also names the extra LLM call. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: mode definition, routing, extraction behavior, return shape/refusals, usage policy, and cost trade-off. It is front-loaded with the most important property and remains highly scannable.

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, yet the description fully covers the return object and refusal contract. It also provides enough context about routing, scope of data, failure modes, and trade-offs. Combined with the annotations, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100% — the schema already documents 'question' in natural language and the aliases. The description does not need to add parameter semantics, and mostly doesn't, so the baseline score applies.

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

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

The description states a specific verb ('extracts the answer') and resource ('tool result'), and identifies this as the grounded, hallucination-resistant mode of ask_pipeworx. It clearly differentiates from the sibling ask_pipeworx while also noting it shares routing. This is far more than a tautology.

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

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

Usage guidance is explicit: use when the answer will be quoted, cited, or acted on, with concrete high-stakes examples. It also provides the counter-case: 'prefer ask_pipeworx for casual lookups.' This fully answers when-to-use versus the main 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?

The description discloses extensive behavior beyond the annotations: parallel fan-out, resolver contract with market_match_confidence, suppression of analysis on low-confidence matches, fallback handling for news APIs (429, retry_after_sec), cancellation-rule parsing, and wide-spread warnings. It even details status codes for closed markets. This vastly exceeds what 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 long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with purpose and usage. Every section adds substantive detail, but the sheer volume makes it less immediately scannable than an ideal concise description, though it remains efficient for the tool's complexity.

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

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

There is no output schema, but the description compensates by thoroughly explaining response shapes (result.market, result.analysis, result.evidence), resolution contracts, parent_event extraction, and edge-case statuses. It also covers safety and rules-risk. This is a complete guide for a tool with many conditional behaviors.

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

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

The input schema already provides 100% coverage with clear descriptions for market, depth, and include_raw. The tool description adds contextual examples (e.g., BTC, Fed, Hormuz fan-outs) that illustrate depth/thorough behavior, but it does not significantly alter parameter understanding beyond the schema's own definitions, which are already precise.

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

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

The description opens with a clear statement of purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which names the verb, resource, and scope. It distinguishes this tool from siblings by focusing on a single bet's research (vs. global edge detectors like polymarket_edges), and it lists input formats and classifiers that make its role unmistakable.

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

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

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 intended-use guidance. It also describes blocker scenarios (low_confidence_match, market_closed_or_inactive) and safety checks, but it does not explicitly contrast with alternatives like ask_pipeworx 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?

Annotations already declare readOnly/openWorld/idempotent, so the description adds valuable context beyond them: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and output format (paired data + pipeworx:// citation URIs). This is substantial additional behavioral detail, though it could mention potential limitations like entity name resolution failures.

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 earns its place—trigger phrases, data details, sorting behavior, output format, and efficiency claim. It front-loads with recognizable query patterns, making it easy to scan. The structure is well-organized by type and behavior.

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 comparison tool with two entity types, multiple output metrics, and no output schema, the description covers the core aspects: what data is returned, how it is sourced, how results are ordered, and citation URIs. It omits edge cases like invalid entities or mixed-type inputs, but these are minor given the schema constraints.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values.' The description adds significant enrichment: it specifies exact data fields pulled for each enum value (revenue, net income, cash, long-term debt for companies; FAERS counts, FDA approvals, trial counts for drugs) and clarifies that values are tickers/CIKs or drug names with examples. This goes well beyond the schema 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 concrete trigger phrases and explicitly defines the tool as 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes from sibling tools by stating it replaces sequential single-pack lookups, leaving no ambiguity about its function.

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 instructions: natural-language comparison requests like 'X vs Y' and 'rank these companies,' plus the directive 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also disambiguates company vs drug usage, giving clear guidance without needing to name a specific 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?

Going beyond the readOnly/idempotent/openWorld annotations, the description discloses critical behaviors: account/paywall requirements, parallel tool decomposition, structured data scope, the findings packet structure (verbatim evidence, confidence, gaps[], contradictions[]), citation resolvability, latency expectations, and the explicit prohibition on inventing data. These are essential for correct invocation and output interpretation.

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 information-dense; every sentence introduces a distinct operational or outcome-related fact. It is front-loaded with account requirements and the sibling-tool fallback, then explains mechanism and output semantics. Slight over-length is justified by 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?

Given no output schema and a complex behavior, the description covers all necessary invocation context: auth gates, depth semantics, latency, result format, gap/contradiction handling, and fetchable citation URIs. An agent has enough information to select, call, and interpret results without additional lookup.

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 documents both parameters (question and depth) with 100% coverage, providing a strong baseline of 3. The description adds meaningful semantic detail by linking depth levels to latency and the contradictions[] scan, and by noting that 'thorough' requires a paid plan, which is decision-relevant for the agent.

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

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

The description clearly states a specific verb ('research') and resource ('Pipework's 1465 STRUCTURED data sources'), distinguishes itself from open-web search, and contrasts with sibling tools like ask_pipeworx. It describes the decomposition-and-routing mechanism, making the tool's function unambiguous.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead' and 'Best for broad/multi-part questions over structured data' while noting 'For a single lookup use ask_pipeworx' as an alternative. It also includes access and pricing prerequisites.

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 and idempotent, but the description adds meaningful behavioral detail: returns top-N results, includes full input schemas with curated examples, and each result is ready to call directly with no second schema lookup. This goes well beyond the safety hints and tells the agent exactly what to expect.

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 purpose. The second sentence's domain list is long but directly helps the agent decide when to use the tool, and the third sentence packs return-format and usage-directive value. 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?

Given the tool's broad scope, the description is complete: it conveys what it returns, that results are immediately callable, when to use it first, and the range of searchable domains. The rich input schema and annotations cover the rest; no output schema is needed since the tool returns tool definitions.

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

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

Schema description coverage is 100% with detailed param descriptions including aliases and examples, so the schema does the heavy lifting. The description adds only general context ('describing the data or task') and implies limit via 'top-N', but doesn't materially enhance parameter understanding beyond the schema.

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

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

The description opens with 'Find tools by describing the data or task', a specific verb+resource+method that clearly distinguishes this meta-search tool from sibling tools focused on specific domains. The follow-up list of domains (SEC filings, FDA drugs, etc.) sharpens the purpose further.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and gives a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This implies the alternative—if you need one answer, use a specific tool—thus providing both when and when-not guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds concrete behavioral details: fans out across multiple sources, returns specific fields, soft-fails for USPTO API sunset, uses GDELT→GNews fallback, and requires ticker or zero-padded CIK. It also notes it is a single parallel call, providing context not captured by 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 well-structured: it opens with relatable examples, then states the core purpose, followed by technical details and restrictions. While dense, every sentence carries useful information; it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly explains what the tool returns (cik, filings, fundamentals, patents, news, LEI) and includes caveats like soft-failing and fallbacks. It covers prerequisites (ticker/CIK vs. name) and parallel-call behavior, making it complete for the intended use.

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 explains both parameters in detail. The description reinforces the same information (e.g., example values, names not supported) but does not add unique semantic meaning 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 it produces a 'full cross-source profile of a US public company in ONE parallel call', with specific verb examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from siblings like compare_entities and resolve_entity by focusing on a single entity and explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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

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

It provides explicit when-to-use guidance ('when the user asks for a holistic view') and when-not-to-use ('names not supported — use resolve_entity first'). It also names an alternative approach (chaining single-pack lookups) and explicitly states preference for this tool over that approach.

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 aligns with these but adds minimal extra behavior—only the note about pairing with remember and recall. It doesn't detail what happens if the key doesn't exist or whether deletion is permanent, though destructiveHint implies it.

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 purposeful sentences: purpose, usage, and related tools. No redundancy or filler. Each sentence earns its place.

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

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

For a simple one-parameter delete tool with annotations, the description provides purpose and usage guidance. It doesn't need to explain return values since no output schema exists, but could have mentioned irreversibility explicitly; however, destructiveHint covers that.

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 'key' parameter, with a clear description ('Memory key to delete') and an example. The description only restates 'by key' and adds no additional parameter details, so the baseline of 3 applies.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It specifies the resource (memory) and the operation (delete), and distinguishes it from sibling tools like remember and recall by positioning it as the counterpart for removal.

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

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

It provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' This gives clear context, but it does not specify when not to use the tool or directly name alternatives, so it falls short of a full 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context beyond these by explaining that it fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format, along with the output shape (single text blob for site-root). This provides useful detail without contradicting annotations.

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

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

The description is three sentences long, front-loaded with the main purpose, and includes only relevant details (what it does, output format, use cases). No wasted words, and every sentence adds value.

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

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

The tool is simple (2 params, no output schema), and the description covers the key aspects: functionality, output format, and use cases. It does not mention edge cases (e.g., invalid URL handling), but given the low complexity and strong annotations, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema covers both parameters with descriptions (url and max_links), achieving 100% coverage. The description does not add additional meaning beyond the schema; it mentions 'extracts title/description/key links' but this is already implied by the tool's purpose and the schema's 'url' description. Thus, baseline 3 is appropriate as schema does the heavy lifting.

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 generates a llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on producing the standard llms.txt markdown format, not just checking visibility.

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 by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context on when to use it. It does not explicitly list alternatives or when-not-to-use, but the specificity makes the intended usage 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 adds specific behavioral details beyond annotations, detailing the exact schema components returned. It doesn't contradict the readOnlyHint and idempotentHint annotations, reinforcing the safe, read-only nature of the operation.

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, front-loaded sentence that conveys all essential information without redundancy. Every word earns its place.

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

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

Given the simple one-parameter tool with rich annotations, the description adequately covers the return content (schema fields, geometry type, record count, capabilities) and leaves no major gaps. The lack of an output schema is compensated by the explicit listing of returned information.

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 only parameter 'url' is fully described in the schema with format and example. The description's 'by url' adds no additional semantic information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description uses the specific verb 'Get' and identifies the resource as an ArcGIS layer's schema, listing the exact information returned (fields, geometry type, record count, capabilities). This clearly distinguishes it from siblings like query_layer.

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

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

The description clearly implies the tool is for retrieving schema information rather than querying data, providing clear context for when to use it. However, it doesn't 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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that it returns the caller's own subscriptions and lists specific fields, but does not disclose additional behavioral traits like pagination or rate limits. With annotations present, this is adequate but not rich.

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 primary purpose and return format, the second gives a direct use case. Every word earns its place, and it is front-loaded with the core action.

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 enumerates all return fields (id, type, params, created_at, last_fired_at, fire_count), which is essential for consumers. Combined with strong annotations and a simple parameter schema, the description is complete for a list 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?

The input schema has 100% description coverage for the single optional parameter include_inactive, so the schema already fully explains parameter semantics. The description does not mention this parameter, leaving meaning solely to the schema. This meets the baseline but adds no extra value.

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

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

The description starts with 'List the caller's active subscriptions', which clearly specifies the verb (list) and resource (subscriptions). It also lists the exact return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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: 'review what you're monitoring before adding more or to find an id to cancel.' It implies the tool is for inspection, not modification, and suggests alternatives (adding and cancelling) without explicitly naming them. This gives a strong sense of when to use it.

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

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

Disclosures go well beyond annotations, which are neutral. The description reveals the claim_token lifecycle (filing without an account returns a token, pass it back to read status and changes), rate limits (5 per identifier per day), and meta-behavior (digest read daily, roadmap impact, free/no quota). These are important behavioral traits not available from structured fields.

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 appropriately sized given the tool's complexity. It front-loads the main purpose in the first sentence, then flows logically through usage scenarios, exclusions, mechanics, and meta-context. Every sentence contributes actionable information—no filler. The structure makes it easy to scan quickly.

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

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

Despite no output schema, the description tells the agent exactly what to expect: the claim_token response, follow-up mechanism, and rate limits. It covers scope (which tools), constraints (don't paste prompts), and consequences (roadmap impact). This is complete for an agent to decide whether and how to invoke the tool correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds valuable semantics beyond schema: it explains the claim_token workflow (filing returns it, passing it back reads resolution), clarifies the type enum via scenarios, and advises on message content (be specific, don't paste end-user prompt). This enriches understanding without duplicating schema text.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's purpose as submitting feedback to the Pipeworx team, distinguishing it from sibling tools like ask_pipeworx or discover_tools by framing it as an outward communication to maintainers rather than a query/discovery tool.

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

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

Provides explicit when-to-use guidance with concrete examples: bug (wrong/stale data), feature/data_gap (tool not in catalog), praise (worked well). It also gives a clear exclusion: only for tools served by this Pipeworx connection, not other MCP servers, and advises filing elsewhere. Practical tips about not pasting end-user prompts and how to identify Pipeworx tools further enhance usability.

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 cover read-only/idempotent/non-destructive, and the description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. This provides insight into data source, privacy, and freshness that annotations do not.

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

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

The description is a single, dense paragraph that starts with the core purpose, then explains return contents, use cases, and data/caching details—all without wasted words. Every sentence contributes meaningful 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?

Despite having no output schema, the description explains what the tool returns (top tools, top packs, total call volume; packs, tools, counts) and covers data privacy, aggregation, and caching. With only one optional parameter, this is sufficient for an agent to invoke it correctly.

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

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

The single parameter is fully documented in the schema with enum values and descriptions. The tool description reiterates the window options and adds a bit of usage context (shorter vs longer), but the schema already does the heavy lifting, so the description adds marginal value.

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

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

The description clearly states what the tool does: returns top tools, packs, and call volume over a recent window. This distinguishes it from sibling tools like discover_tools or search_datasets by focusing on trending usage across agents rather than discovery or search.

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

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

Explicitly lists three concrete use cases (hot data sources, canonical tool selection, aligning with agent needs) and explains window semantics (shorter for hot, longer for steady-state). It does not name alternatives or state when not to use, but the guidance is clear and actionable.

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

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

Extremely transparent. Describes thresholds (3pp deviation, >20% placeholder), semantic anchor (Jaccard >= 0.30), response structure, and fill-check behavior including a concrete trading rule: 'realizable_edge_pp ≤ 0... do not trade it.' While annotations already signal read-only/idempotent, the description adds rich context about internal checks and edge cases 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 long, but every part serves a purpose: mode selection, semantic anchor, partition filter, response format, fill check. It is front-loaded with the main purpose and no-arg behavior. The use of ALL-CAPS labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) is a slight organizational blemish but aids scanning. Overall dense but not redundant.

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 return structures ('opportunities[]', 'partition_check', 'fill_check') and how to interpret them. It also covers placeholder filtering and book-depth realism, which are essential for correct trading decisions. This makes it complete for a tool with 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?

The schema descriptions already give decent parameter info, but the description goes far beyond: for event it explains 'walks child markets, checks date-axis/threshold-axis ordering AND computes the partition_check'; for topic it explains cross-event Jaccard filtering. This adds substantial meaning beyond the schema's simple 'mode' descriptions, so it earns a 5.

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

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

Purpose is stated immediately: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' The verb 'find', resource 'Polymarket arbitrage opportunities', and method are clear. It distinguishes from siblings by its unique approach and mentions polymarket_fill_risk for related but different functionality.

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

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

Explicit mode guidance: 'Call with NO args for a trending_scan', 'pass event for...', 'topic for...'. It even recommends 'event (recommended for a specific market)'. Clear alternative is given: 'For custom sizing use polymarket_fill_risk.' This tells the agent exactly when to use each variant and when to use another 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?

The description goes far beyond the readOnly/idempotent annotations by disclosing caching behavior ('Cached 1h at the KV level'), diagnostics with funnel counters, the 24h-move warning, and the Fed signal unreliability caveat. These are concrete behavioral traits not present in annotations or schema, and none contradict 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 dense and long, but highly structured with clear segment headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and top-level response fields. Every sentence carries substantive detail, but it is verbose enough that a user must parse carefully; still, the organization justifies the length.

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

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

Given the tool's complexity (3 segments, multiple model families, 9 knobs) and the lack of an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates/fed_note, _diagnostics) and failure modes (why segments may be empty). It also includes model-specific thresholds and historical context, making it nearly self-sufficient for an agent to understand what will be returned.

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

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

Schema coverage is 100%, but the description adds meaningful context for several knobs: it explains that min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable' and that min_partition_leg_kelly 'filters partitions by best per-leg Kelly.' It also adds real-world context for slippage ('Polymarket has zero trading fees... 20-50bp per trade'). However, not all parameters (e.g., limit, category_filter) are referenced in the description, leaving some semantics solely to the schema.

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

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

The description clearly states it 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' identifying a specific action and resource. It further distinguishes itself from siblings by detailing its model families and response segments, making it unmistakably distinct from other Polymarket tools like poly_market_arbitrage or poly_market_edge_tracker.

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

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

It explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also includes implicit exclusions, such as the Fed note explaining why Fed bets are excluded from ranking. However, it doesn't explicitly name alternative tools or state when not to use this tool, so it stops short of 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral traits: history limited by 60-day snapshot TTL, snapshots written on cache-miss causing gaps, and decay computed on daily closes net of slippage. These details are not inferable from annotations alone and provide essential 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 long but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers args, response structure, and limitations. The clear use of labels like 'Args', 'RESPONSE', and 'LIMITS' makes it easy to scan despite the density.

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 full responsibility for explaining return values, and it does so thoroughly with tracked[], expired[], and snapshot_dates[] plus field definitions. It also covers historical depth, missing-data behavior, and calculation methodology. Given the tool's complexity, the description is remarkably 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 schema already describes both parameters completely (100% coverage), giving a baseline of 3. The description adds interpretative context by calling days a 'lookback' and window a 'snapshot family,' which helps an agent understand their real-world meaning, pushing it to a 4.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal behavior rather than just edge presence.

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

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

The description provides clear context for when to use this tool, emphasizing that 'a fresh wide edge and a 3-week-old wide edge are different trades.' However, it does not explicitly name alternatives or state when not to use it, 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description significantly adds context beyond these flags: it explains the tool 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), and warns that partial fills can convert an arb into unhedged directional risk. It also delineates behavior for single-market versus basket modes, enriching the agent's understanding of side effects and risk.

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

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

The description is dense but well-organized, using clear mode labels (SINGLE-MARKET:, BASKET:) and imperative guidance (REQUIRES, USE THIS). It is somewhat long, but every sentence contributes necessary behavioral or usage detail. The front-loaded purpose sentence and structured returns make it navigable, though a bulleted layout could slightly improve scanability.

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

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

There is no output schema, so the description must explain return values, which it does thoroughly: it lists all return fields for both single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket modes (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs[], etc.). It also covers prerequisites, environment (live CLOB), and the primary risk scenario, making it complete for a complex tool with no structured output.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond the schema. It explains the one-of requirement for market/event, how size_usd is interpreted differently in single-market (max spend/target proceeds) versus basket (settlement notional, shares per leg), and the default auto side logic for baskets. These clarifications are critical for correct invocation and are not fully spelled out in the schema alone.

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

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

The description clearly defines the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishing two modes (single-market and basket) and explicitly referencing sibling tools (polymarket_arbitrage, polymarket_edges) to position it as an execution-risk validator. The verb 'check' plus resource 'order-book depth' makes the function specific and distinct.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clarifies the required input ('REQUIRES one of market or event') and explains why using it matters (theoretical overround on thin books is not capturable, partial fills unhedge). This provides clear when-to-use and why-to-use guidance, including implicit 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 only state read-only, idempotent, open-world. Description adds substantial behavioral detail: price gap ranges (2-25pp), two compatibility_warning cases, temporal_alignment semantics ('aligned:false means spreads are mathematically meaningless'), and skipped_cross_type/subtype counters. 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?

Long but well-structured with capitalized labels (TWO MODES, RESPONSE, SAFETY FIELDS) and parenthetical examples. Every sentence contributes to usage, response interpretation, or edge-case handling. Slightly dense, but the complexity justifies the length.

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

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

Without an output schema, the description explains the response surface thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning triggers, temporal_alignment fields, and skipped_cross counters. Covers edge cases like non-equivalent bet shapes and unmatched events, making the tool self-sufficient for an agent.

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

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

Schema already covers all three parameters with descriptions. The description adds mode semantics: 'topic' as overridable shortcut vs explicit 'kalshi_event_ticker' + 'polymarket_event_slug' for custom pairings, plus override relationship. This goes beyond the schema's per-field text and aids correct selection.

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

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

Opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' giving a specific verb+resource with clear scope. Distinguishes from siblings like polymarket_arbitrage by centering on the Kalshi–Polymarket pair and unique compatibility warnings.

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?

Clearly describes TWO MODES (topic shortcuts vs explicit ticker/slug) and when each is appropriate. Warns that 'most pre-mapped topics return compatibility_warning today,' effectively telling agents when results are not tradeable. Does not explicitly name sibling alternatives, but the mode guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds useful behavioral context: it returns attribute rows and geometry, and suggests a sampling pattern. It does not mention auth or rate limits, but given the annotation coverage, this is acceptable.

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

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

The description is three sentences long, each sentence earns its place: first states the core purpose, second lists the key parameters, third provides a usage example. No redundant wording or filler.

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

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

Given the well-annotated schema (100% coverage, read-only hints), the description is quite complete: it covers the source of the URL, the query capabilities, and the return type. It does not explicitly explain pagination flow (e.g., using offset for next pages), but the schema already documents offset and limit, so this is a minor gap. No output schema exists, but the return type is stated as attribute rows and geometry.

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 for all six parameters, so the baseline is 3. The description adds value by summarizing the parameter family (SQL-like where, comma-separated out_fields, order_by, limit, offset) and by pointing out that the URL comes from search_datasets, which enriches the url parameter's meaning. The sampling tip also connects parameters in a practical way.

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 'Query an ArcGIS Feature Service / Map Service layer by its url', which is a specific verb+resource. It also distinguishes from siblings by mentioning 'from search_datasets', implying search_datasets is for finding datasets and query_layer is for querying them.

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

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

The description provides a clear usage context: first get a URL from search_datasets, then query this layer. It also gives a practical tip for sampling (where="1=1" + out_fields="*"). However, it does not explicitly state when NOT to use it compared to alternatives like layer_info or search_within, so it stops short of full 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 establish safety (readOnlyHint, idempotentHint, destructiveHint=false). The description adds behavioral context beyond that: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the fact that omitting the key lists all saved keys. It also clarifies the relationship with remember/forget. 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 three sentences, front-loaded with the core action, and every sentence adds value: the first defines the operation and the optional-key behavior, the second provides usage context, and the third clarifies scope and tool relationships. No fluff or repetition.

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

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

For a simple tool with one optional parameter, good annotations, and no output schema, the description covers the main requirements: what it does, when to use it, its scope, and its companion tools. It does not explicitly describe the return format (e.g., the value or array of keys), but that is reasonably implied by 'Retrieve a value' and 'list all saved keys'. Minor gap, otherwise complete.

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

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

Schema coverage is 100% for the single 'key' parameter, with the schema description already noting that omitting it lists all keys. The tool description adds semantic value by giving concrete examples of what keys might contain (target ticker, address, research notes) and reinforces the optional-key behavior. This exceeds the schema baseline of 3.

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

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

The description uses a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and additionally covers the list-all-keys mode when the key is omitted. This clearly distinguishes it from sibling tools like remember and forget, which are the complementary save and delete operations.

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

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

The description gives clear use cases ('the user's target ticker, an address, prior research notes') and states when it's valuable ('without re-deriving it from scratch'). It mentions pairing with remember and forget, but does not explicitly say when *not* to use recall (e.g., for live or external data). This is good context but lacks an explicit exclusion or alternative comparison.

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 helpful behavioral details: return payload structure, mark_read side effect, polling friendliness, and an alternative URL. However, it explicitly states that mark_read:true flags events as read and affects future calls, which is a state-modifying operation. This directly contradicts the readOnlyHint=true annotation, which signals a read-only operation. Per the rubric, this contradiction requires a score of 1.

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 with no waste. It leads with the core purpose, then details return contents, filtering options, and side effects. Every sentence adds value, and the alternative endpoint is a concise bonus. The structure is front-loaded and easy to scan.

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

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

Given no output schema, the description adequately explains what is returned (source, citation_uri, raw payload) and how to control results (filters, mark_read, unread_only). It also notes polling works and provides an alternative access method. Missing details about edge cases or pagination are not critical for a read tool with well-documented schema. The contradiction with readOnlyHint is a completeness gap, but it is already penalized in transparency.

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 for parameters is 100%, so the baseline is 3. The description adds extra meaning for type (with example 'sec_8k'), since (ISO timestamp), and mark_read (explains that it flags events read and affects the next call). This goes beyond the schema's brief descriptions, providing practical guidance on how to use the parameters.

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

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

The description opens with 'Pull fired events from your subscription feed,' which clearly identifies the tool's action and resource. It distinguishes this from sibling tools like recent_changes by specifying the persisted feed and the types of data returned (source, citation_uri, raw payload). The verb 'Pull' is specific and the scope is well-defined.

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: filtering by type and since, using mark_read to control subsequent calls, and noting that polling works fine. It also offers an alternative HTTP endpoint for scripts/dashboards, which gives an alternative access path. No explicit exclusions or sibling comparisons are given, but the usage context is sufficient.

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

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

Even with annotations declaring readOnly/idempotent behavior, the description adds valuable behavioral context: it documents the fan-out to multiple external sources, the GDELT→GNews fallback on rate limits or 5xx errors, and the USPTO soft-fail due to the PatentsView sunset. It also describes the output structure (changes[] grouped by source + total_changes + citation URIs), which is not available from structured fields.

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 example queries and a concise one-liner ('change feed for a company in the last N days/weeks/months in ONE parallel call'). While it is longer than the calibration ideal, every sentence serves a purpose—describing sources, fallback behavior, input formats, output structure, and alternatives. The structure flows logically from what it does to how to invoke it and when to use something else.

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 multi-source, complex tool with no output schema. The description compensates thoroughly by explaining the return value (changes[] grouped by source + total_changes + citation URIs), the input formats, source-specific quirks (GDELT→GNews fallback, USPTO sunset), and a sibling alternative. An agent has enough information to select and correctly invoke this 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 the baseline is 3. The description adds value beyond the schema by explaining the accepted formats for `since` (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and recommending typical values. It also clarifies that `value` can be a ticker or CIK, though that is already in 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 identifies the tool as a change feed for a company, with a specific list of sources (SEC EDGAR, GDELT→GNews, USPTO) and a clear scope ('last N days/weeks/months'). It also distinguishes itself from the sibling entity_profile by explicitly stating when to use that alternative.

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 guidance on when to use the tool ('What's new with X' queries) and explicitly names an alternative: 'Use entity_profile instead when you want the static profile...'. It also gives concrete parameter recommendations: 'Use "30d" or "1m" for typical monitoring.' This goes beyond mere context to actionable 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?

Discloses additional behavioral traits beyond annotations: memory is scoped by agent identifier, authenticated users get persistent memory, anonymous sessions retain memory for 24 hours, and it explicitly pairs with recall/forget. The idempotentHint and destructiveHint are consistent with the description; no contradictions.

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

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

The description is concise (three sentences), front-loaded with the core purpose, and efficiently covers use cases, storage details, persistence, and companion tools without redundancy. Every sentence earns its place.

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

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

For a simple two-parameter memory-write tool with rich annotations and no output schema, the description is complete. It covers when to use, what is stored, persistence, and how to retrieve/delete, giving the agent all necessary context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the schema's examples ('resolved ticker, target address') but does not add substantial new parameter-specific semantics beyond what is already in the input schema. It adds overall context but not parameter-level details.

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') with a clear resource ('data the agent will need to reuse later') and specifies the storage model ('key-value pair scoped by your identifier'). It distinguishes from siblings by naming recall and forget as the complementary retrieval and deletion tools, making its role in the memory workflow explicit.

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

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

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and explains the persistence behavior (authenticated vs anonymous sessions). It also names alternatives ('Pair with recall to retrieve later, forget to delete'), giving clear context for use vs. sibling tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral details like graceful degradation (LEI/FIGI unavailable), internal cascading lookups, source labeling of identifiers, and explicit listing of unresolved items. No contradictions with annotations.

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

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

The description is long but well-structured with a front-loaded key instruction and clear sections for each entity type. Every sentence adds value, though some technical details about LEI/FIGI resolution could be slightly more compact without losing clarity.

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

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

With no output schema, the description fully covers return values for both types (identifiers, source labels, unresolved items) and explains behavior under degraded conditions. It provides a complete picture of what the agent will receive and how the tool operates internally.

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 enriches both parameters substantially. For 'type', it explains the cross-source identity spine and return types; for 'value', it expands accepted inputs (e.g., ISIN) and provides domain-specific examples. The description adds meaning well 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 resolves names to canonical identifiers, with specific examples and supported entity types (company, drug). It distinguishes itself from sibling tools like entity_profile by emphasizing name-to-ID resolution as a 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?

The instruction 'Use FIRST whenever you have a name but need an ID' provides clear guidance on when to invoke this tool. However, it does not explicitly state when not to use it or name alternative tools, though the context implies alternatives exist for ID-to-profile use cases.

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 establish read-only, idempotent, open-world behavior. The description adds valuable context beyond that: it discloses that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific fields (score, confidence, signal density). This gives the agent a clear model of what happens when the tool runs, without contradicting annotations.

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

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

The description is compact and front-loaded. Four sentences each contribute: purpose, mechanism, use case/example, and output. No redundant words or restatements of the title or schema properties.

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 sufficiently covers what the tool does, how it works (probing with ai_visibility_check, ranking), when to use it, and what it returns. It also clarifies entity ordering semantics ('First entry treated as the subject') in the schema, and the description itself does not need to repeat that. This is complete for the tool's complexity.

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

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

The schema already provides full descriptions for all 4 parameters (100% coverage), including the meaning of entities, the optional models, _apiKey, and context. The tool description does not add parameter-level meaning beyond the schema, 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 clearly states a specific action ('Compare AI visibility across multiple entities side-by-side') and distinguishes it from the sibling tool ai_visibility_check by focusing on multiple entities, ranking, and competitive comparison. It also names the probe mechanism and the output, 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 usage context ('Useful for competitive AI-marketing audits') and an illustrative example question. However, it does not explicitly mention when not to use this tool or name alternatives (e.g., ai_visibility_check for single entity), 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 establish readOnly/idempotent/non-destructive, but the description adds valuable context: fan-out behavior, partial failure handling, timeouts (5-30s for first bundlephobia measurement), and the sources_failed field. It also details the return block fields and alternative version list, going well beyond annotations.

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

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

The description is dense but every sentence adds value: core purpose, use cases, return summary, ecosystem limitation, and failure behavior. It is front-loaded with the most important information and does not contain 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?

Despite lacking an output schema, the description thoroughly enumerates the return fields, explains what data comes from each service, and covers edge cases (timeouts, unsupported ecosystems). For a complex composite tool, this is a complete and self-sufficient 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 description coverage is 100% for both package and version, so the schema fully documents parameter meaning. The description does not add additional parameter-level semantics beyond what the schema already provides, hence 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 composite goal ('should I add this npm package to my project' check), names the underlying services (deps.dev, bundlephobia), and lists the exact metrics returned. It clearly distinguishes itself from sibling tools by noting the ecosystem scope and fallback for other package managers.

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 an agent asks is X safe / popular / small' and gives a concrete example. Also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear when-to and when-not-to 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 indicate this is a read-only, idempotent, non-destructive operation, so the description doesn't need to repeat that. It adds value by disclosing the exact return fields (name, summary, record_count, owner/org, Feature Service url) and the recommended next action, which is beyond the structured metadata.

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 tight two sentences. The first sentence front-loads the core action (search datasets by keyword) and the second sentence details the return payload and the downstream workflow. No wasted words or redundant repetition of the tool name.

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 search tool with no output schema, the description adequately summarizes the return values and provides a clear handoff to related tools. It does not mention pagination or the limit parameter's default, but these are covered in the schema. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already provides full descriptions for all three parameters, so the description does not need to explain them. It does mention 'keyword' implicitly, but adds no additional semantic detail beyond what the schema already covers, keeping this at the baseline for 100% schema coverage.

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

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

The description specifies a clear verb ('Search'), a defined resource ('California State Parks GIS open geospatial datasets'), and the scope ('by keyword'). It also distinguishes this from sibling tools by detailing the return fields and pointing to downstream tools (query_layer / layer_info), making its role in the workflow unmistakable.

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

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

The description provides clear context on when to use the tool (to discover datasets by keyword) and even instructs what to do with the results (pass the returned url to query_layer / layer_info). It does not explicitly state exclusions or alternatives among the sibling tools, but the workflow guidance is sufficient for most use cases.

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, idempotent, non-destructive), the description discloses the mechanics (BGE-base-en embeddings, cosine over 500-char windows), the return payload (passages with offsets and similarity scores), and the input cap with truncation behavior. This adds significant context that annotations alone do not provide. 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 a clear purpose, then expands to usage, technical details, and pairing. It is moderately long but every sentence contributes value. A slight deduction for including both technical minutiae and marketing-style phrasing, but it remains efficient.

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

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

For a tool with 3 params and no output schema, the description covers input requirements, output details (passages with offsets and similarity scores), use case, technical constraints, and integration with a sibling tool. It is complete enough for an agent to select and invoke correctly without further documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some contextualization (e.g., 'text you already pulled', 'natural-language query') but does not significantly extend beyond the schema's parameter descriptions. It does clarify the query parameter with domain examples, which is useful, but the schema already captures the essentials.

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 'Semantic search INSIDE a fetched record', clearly stating the verb, resource, and scope. It explicitly differentiates from siblings by emphasizing the tool operates on text already pulled by the agent, and it contrasts with ask_pipeworx_grounded.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also names the alternative workflow with ask_pipeworx_grounded, providing explicit guidance on how this tool fits with other tools.

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

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

Annotations already cover read-only/destructive/idempotent hints. The description adds meaningful behavioral details: OAuth account requirement, SMS verification and daily cap, and feed persistence. No contradiction with annotations.

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

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

The description is a single dense paragraph that is front-loaded with purpose and packed with relevant details. All sentences earn their place, though readability could be improved with bullet points or structured sections.

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, it explicitly mentions the return value. It covers prerequisites, all five subscription types with parameter examples, delivery channels including constraints, making it 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?

The input schema has 100% coverage with detailed descriptions for all parameters and nested objects. The description repeats some examples (sec_8k, polymarket_edge, fred_series) but does not add significant meaning 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 'Create a proactive monitoring subscription to a live-data event stream' and explicitly notes it returns the new subscription id. It enumerates supported subscription types, which distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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 on when to use the tool by mentioning the OAuth account requirement, the always-on feed with retrieval methods, and optional delivery channels. While it doesn't explicitly name alternatives, the reference to recent_alerts and the registry endpoint implies usage context.

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

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

Annotations already mark it as read-only and idempotent, but the description adds substantial behavioral detail: the structure of the response (category-bucketed example questions), the fact it draws from the live catalog, and the behavior of the optional `topic` parameter. It also mentions it returns the exact tool+argument shape, which helps the agent know what to expect.

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

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

The description is a single dense paragraph that front-loads the purpose with realistic example queries and then covers usage. It contains multiple clarification phrases but each earns its place by adding use cases, return details, and alternatives. Slightly long but well-structured and efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete. It tells the agent when to use it, what it returns, how to pass the topic, and even suggests it as a way to learn meta-tools. No gaps remain for the agent to guess.

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 100% coverage of the single `topic` parameter with a full list of allowed values and instruction to omit for cross-category spread. The description repeats and exemplifies these topics but adds no new meaning beyond what the schema already states. 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 this is the onboarding entry point, returning category-bucketed example questions with exact tool+argument shapes drawn from the live catalog. It distinguishes itself from siblings by positioning as 'Use this FIRST when you do not yet know what Pipeworx can do for you', which separates it from other discovery tools like 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?

Explicitly tells the agent when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the two invocation modes — no args for full spread, or with `topic` to focus — and lists example topics. This provides clear actionable context without needing to infer.

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

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

The description discloses important behavioral traits not fully captured by annotations: ownership enforcement and soft-delete behavior (deactivated, not deleted). It also notes that historical events remain available via 'recent_alerts', adding useful operational context.

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

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

The description is two sentences, with the primary action front-loaded in the first sentence and additional context in the second. Every sentence provides necessary information with no wasted words.

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

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

For a simple one-parameter tool with strong annotations, the description covers purpose, constraints, and outcome (deactivation with historical data). It is sufficiently complete for an agent to invoke correctly without needing an output schema.

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

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

The input schema already fully documents the 'id' parameter (type, description, and that it's returned by 'subscribe'). The description adds no additional parameter-specific meaning beyond the schema, 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 ('Cancel a subscription by id') with a clear resource (subscription) and method (by id). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by being the cancellation operation.

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 context for when to use the tool: when canceling a subscription, with the key constraint that ownership is enforced. It doesn't explicitly name alternatives but the context is sufficient for an agent to select it appropriately.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing the meaning of each verdict, especially the crucial distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source exists). It also discloses the internal routing, verbatim evidence requirement, and return structure, which are important behavioral traits.

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 the average but every sentence serves a purpose: examples, usage, routing, verdict explanations, and error semantics. It is front-loaded with the most important purpose and usage, and the structure is logical. Only slight verbosity prevents a 5.

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

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

Given the tool's complexity and the fact that there is no output schema, the description does an excellent job covering the return values (verdict, actual value, citation), the nuanced error conditions, and the routing logic. It fully prepares the agent to understand what the tool does and what to expect from its output.

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

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

Though schema coverage is 100%, the description adds significant meaning: it explains the tolerance_pct parameter's purpose (override, default behavior, and specific use for hallucination detection) and provides concrete examples for the claim parameter. This context helps the agent choose and set parameters correctly beyond what the schema alone offers.

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

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

The description opens with concrete example phrasings and clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It identifies the resource (claims) and the specific verb (verify/refute), and it distinguishes itself from sibling tools by scoping to fact-checking and noting it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct,' and it provides context for the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline otherwise). However, it does not directly name sibling tools to avoid or explicitly state when not to use this tool, so it lacks the full 'when-not/alternatives' clarity.

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