Arcgis Pima

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive traits. The description adds valuable behavioral context: the default model is free, using Anthropic costs money and requires a BYO key ('you pay Anthropic directly'), and the return structure is disclosed (per-model score/confidence/signals/raw_response). 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 compact and front-loaded: first sentence states the core function, second covers defaults and cost, third covers output, and fourth gives use cases. Every sentence adds unique value without 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 tool with 4 params, no output schema, and good annotations, this is complete. It explains what the tool returns, the default behavior, the optional Anthropic path and cost, and practical use cases. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: it clarifies the default model if `models` is omitted, explains that `_apiKey` is only needed for 'anthropic', and provides the return shape for the tool's outputs. This goes beyond the schema's field descriptions.

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

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

The description uses a specific verb ('probe') and resource (LLMs) to state exactly what the tool does: scores visibility (0-100) per model for a given entity. It clearly distinguishes from sibling tools by focusing on LLM knowledge probing, not on chat, search, or data-layer 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 provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model behavior and when to pass `_apiKey`. It does not explicitly name alternatives or exclusions, but the context signals are clear enough for an agent to select this tool.

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

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

Annotations already declare the built-in safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description need not restate it. The description adds meaningful behavioral context on top: that the agent auto-routes to a large catalog of tools, auto-fills arguments, and returns answers with stable pipeworx:// citation URIs. It does not contradict the annotations. It omits minor operational details like rate limits, but annotations largely cover the risk profile.

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 on the longer side but front-loads the key instruction (PREFER OVER WEB SEARCH) and structures the rest as scope → behavior → trigger phrases → examples → default rule. Each section earns its place, though it is slightly redundant that the scope list and the example list cover overlapping territory.

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

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

For a complex routing tool with no output schema, the description is complete: it explains what the tool does, when to choose it (prefer over web search, trigger phrases), how to invoke it (natural language question), what comes back (structured answer with citation URIs), and how to identify scope (real-world data, authoritative sources). It also includes fallback guidance via the sibling comparison note, leaving no material gap for an agent to mis-call it.

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

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

Schema description coverage is 100% (each param is fully described as an alias for question), so the baseline applies. The description adds non-overlapping meaning to the single parameter by setting expectations about the query format — natural-language, factual, real-world questions — and provides six worked examples (e.g., 'adverse events for ozempic', '5-day forecast for London'). This turns the raw parameter from 'a string' into a well-grounded agent instruction.

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

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

The description names the exact behavior ('Routes the question to the right one of 5,596 tools across 1,465 verified sources, fills arguments, returns the structured answer'), plus a resource domain (authoritative real-world data with citations). It distinguishes itself from web search and sibling routing tools such as ask_pipeworx_grounded and deep_research. The verb+resource pairing is specific and non-tautological.

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 an explicit when-to-use rule ('PREFER OVER WEB SEARCH'), enumerates trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), provides concrete query examples for each domain, and even names the default behavior ('START HERE for most questions'). It clearly tells the agent the tool is the first choice for factual real-world queries, including where web search would also work.

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 readOnly, idempotent, and non-destructive behavior, so the description does not need to re-explain safety. It adds useful behavioral context beyond the annotations: there is currently no active candidate so it matches ask_pipeworx exactly, it is a full working router rather than a fallback, and it is purposely the experimental edge.

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 for a tool with this much caveat-laden context, front-loading the core identity as a beta universal router, then clarifying the active-candidate state and the comparison workflow. A few phrases repeat the same idea, but every part contributes important context for correctly interpreting the tool's current 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?

There is no output schema, but the description says the response shape is identical to ask_pipeworx, which is enough for agents that understand that sibling. Input shape is fully documented by the schema, and the behavioral caveats about beta state are well covered. It is slightly dependent on prior knowledge of ask_pipeworx, but the contract is clear enough.

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

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

Schema coverage is 100%, and the schema already documents the required 'question' parameter plus all aliases. The description adds no parameter-specific detail, but the schema carries the full burden. Baseline 3 is appropriate because the description's 'same arguments' pointer is redundant with 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 this as a beta version of ask_pipeworx, a universal router handling the same 5,596 tools, same arguments, and same response shape. It also distinguishes it from the stable sibling by calling out the experimental routing improvements, so an agent can immediately tell it apart from ask_pipeworx and 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 to use it exactly like ask_pipeworx when the newest routing is desired, and that results are compared against the stable router to decide merges. It does not give a clear 'when not to use' statement or compare directly with other siblings like ask_pipeworx_grounded, but the practical guidance is present.

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

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

The description goes well beyond the annotations by detailing refusal behavior, indication that answers are extracted only from the tool result, and the explicit refusal_reason values. It also discloses the extra LLM call cost. The annotations (readOnlyHint, idempotentHint) are consistent with this read-and-return behavior, and the description adds meaningful behavioral context about what happens when no grounded answer is found.

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 information-dense but front-loaded: it states the core behavior, then return shape, then refusal reasons, then usage guidance and tradeoff. Every sentence earns its place, and there is no repetition of schema fields or annotations.

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

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

For a read-only tool with no output schema, the description fully compensates by clarifying return structure, refusal paths, and when to use the alternative. Nothing that an agent would need to decide whether to invoke it or interpret its response is missing.

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

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

Schema coverage is 100%, and the schema already documents all six parameters as aliases of 'question'. The description doesn't add new parameter-level detail beyond implying that the user provides a natural-language question, so a baseline 3 is appropriate here; the schema carries the semantic weight.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode for high-stakes reads, distinguishing it from ask_pipeworx by naming the same routing but stricter extraction. It specifies a concrete verb (returns a grounded answer or refusal) and resource (data from tool results), so an agent can recognize the tool's role and separate it from siblings.

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

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

It gives explicit guidance on when to use this tool ('whenever an answer will be quoted, cited, or acted on...'), and the exact alternative to prefer for casual lookups ('prefer ask_pipeworx'). It also states the cost tradeoff of one extra LLM call, which gives an agent a clear decision rule.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral detail: resolver contract with confidence levels, parallel fan-out, blocking behavior for low-confidence/closed markets, news fallback on 429s, and cancellation-rule parsing. It also warns about flat-50¢ void settlements, which is critical safety 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 it's structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. All sentences contribute unique operational details, so although verbose, it earns its length.

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

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

Given no output schema, the description carefully documents response shapes (market/analysis/evidence), resolver contract, parent_event, news fields with fallback flags, and status codes. It also covers safety mechanisms (low_confidence_match, market_closed_or_inactive) and resolution-rule risk, 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?

Schema coverage is 100%, so baseline is 3, but the description enriches parameter semantics with fan-out examples per depth, response size implications for include_raw (~20KB vs 50-500KB), and market input forms. This elevates it to 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 uses a specific verb ('Research'), names the resource ('a Polymarket bet'), and explains the mechanism ('pulling the relevant Pipeworx data in one call'). It lists classifiers and fan-out examples, clearly differentiating it from siblings like deep_research or polymarket_edges.

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

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

It explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' which gives clear invocation context. It lacks explicit 'when not to use' or named alternatives, but the context is clear enough to avoid confusion with siblings.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantive behavioral detail: data sources (SEC EDGAR/XBRL, FAERS, FDA approvals, active trials), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in output. 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. It opens with example queries, states purpose, gives strong usage preference, and details type-specific behavior without redundancy. The length is justified by the richness of context provided.

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 covers return format ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. With only two parameters and strong annotations, this description fully equips an agent to invoke the tool correctly and interpret results.

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

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

Schema covers 100% of parameters, but description adds semantic depth: for type='company' it specifies financial fields pulled, for type='drug' it lists regulatory/trial counts, and provides concrete value examples (AAPL, MSFT; ozempic, mounjaro). This goes well beyond the schema's basic descriptions.

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

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

The description clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides example queries like 'X vs Y'. It distinguishes from siblings by emphasizing it replaces sequential single-pack lookups, making the tool's unique scope obvious.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists query patterns for when to use. This gives clear when-to-use context and implicitly names the alternative (sequential lookups) to avoid.

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

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

Annotations already mark it read-only and idempotent, and the description adds greatly: account/auth status, paid-tier limits, returns gaps[] and contradictions[] as explicit failure/agreement signals, claims citations are always resolvable, and gives execution time expectations. No contradiction with the readOnly/openWorld/idempotent hints.

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

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

The description packs a lot of value-dense information into a long block with a logical flow: account requirement, alternative, core function, best use cases, output details, and performance expectations. It is not tightly edited—several sub-clauses could be trimmed—but every sentence carries unique information rather than 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 no output schema, the description responsibly describes the main return structure: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and semantic excerpting. It also covers authentication prerequisites, pricing tiers, applicable sibling, execution time, and limitations. That is comprehensive for tool selection and first call.

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

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

Input schema covers 100% of parameters with good schema descriptions, so the baseline is 3. The description adds value by injecting depth-specific nuances beyond the schema (paid plan for thorough, relationship between depth and contradiction detection, typical latencies) and by confirming that the `question` parameter supports broad/multi-part natural-language queries.

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 highly specific action: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources' in one call, and clarifies that this is NOT open-web search. It also differentiates from the sibling ask_pipeworx by saying deep_research is for broad/multi-part questions while a single lookup should go elsewhere.

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

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

It gives explicit alternatives and conditions: without a sign-in, use ask_pipeworx; for single lookups, use ask_pipeworx; thorough depth requires a paid plan. The description also states when deep_research is 'Best for' broad/multi-part structured-data questions, leaving little ambiguity about 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?

Beyond the read-only/idempotent annotations, the description reveals key behavioral traits: it 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and emphasizes 'each result is ready to call directly, no second schema lookup needed.' This tells the agent exactly what to expect in the response.

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 but packed with purpose, usage, and return behavior. The list of domains is long but informative, and every sentence earns its place. Slight room for tightening, but overall well-structured and front-loaded.

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

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

There is no output schema, but the description compensates by explicitly stating the return format (top-N tools with names, descriptions, and full schemas). It also provides usage context and examples. It doesn't explain ranking criteria or error handling, but for a discovery tool in a large sibling set, this is sufficiently complete.

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

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

Schema coverage is 100% and all parameters are documented with descriptions, so the baseline is 3. The description does not add meaning beyond the schema; it mentions 'describing the data or task' which echoes the schema's 'query' description, and aliases are already listed 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 starts with 'Find tools by describing the data or task,' which clearly states a specific verb and resource. It distinguishes itself from siblings by framing it as a meta-discovery tool, listing domains like SEC filings, FDA drugs, and stocks.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and gives concrete examples. 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)' provides clear guidance on when to invoke this tool, effectively implying when not to use it (when you already know the exact tool).

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

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

Beyond the readOnly/idempotent annotations, the description discloses the fan-out across multiple sources, the patents API sunset and soft-fail behavior, the GDELT→GNews fallback, and the specific output fields with sorting and URI formats. This adds valuable behavioral 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 dense but every sentence contributes either purpose, usage, or behavior. It could be tightened slightly, but the detail is necessary for a tool with no output schema.

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

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

Since there's no output schema, the description compensates by enumerating the returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and describing the URI format and sort order. It also notes the soft-fail for patents, ensuring the agent knows what to expect.

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

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

The schema already covers both parameters fully (type enum and value format with examples). The description reiterates the same constraints but doesn't provide additional semantic details beyond what's in the schema, so it meets the baseline but doesn't exceed it.

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

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

The description clearly states it creates a full cross-source profile of a US public company in one parallel call, with query examples like 'AAPL' and 'Microsoft'. It explicitly positions itself as preferable over chaining individual lookups, distinguishing it from alternative approaches.

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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly notes names are not supported, directing to resolve_entity instead. This gives clear when-to-use and when-not-to-use 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 disclose destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns with structured data. It adds minimal behavioral context (e.g., 'clear sensitive data the agent saved earlier') but does not go beyond what annotations convey about risk or side effects.

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 concise sentences, front-loaded with the action, followed by usage guidance and a pointer to related tools. Every sentence adds value with no redundancy.

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

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

For a single-parameter, no-output-schema tool, the description is nearly complete: it specifies purpose, when to use, and related tools. It could mention idempotency or lack of return value, but the annotations already cover behavior, making this sufficient.

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

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

Schema description coverage is 100%, and the schematic already defines 'key' as 'Memory key to delete'. The description's phrase 'by key' adds no additional 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 begins with a specific verb 'Delete' and identifies the resource as 'a previously stored memory by key', which clearly distinguishes it from sibling tools like remember and recall. It also explicitly mentions pairing with those tools, reinforcing its role in the memory lifecycle.

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 concrete when-to-use scenarios ('context is stale, the task is done, or you want to clear sensitive data') and explicitly names alternatives ('Pair with remember and recall'), giving the agent clear guidance on selecting this tool over siblings.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds useful behavior beyond annotations: it fetches the page, extracts title/description/key links, and emits a standard markdown text blob. This contextualizes the internal process 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?

Three sentences, each earning its place: function, process/output, use cases. Front-loaded with the core purpose, no redundancy or fluff.

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

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

The tool is simple (2 params, no output schema) and the description covers the full behavior: what it does, how, what the output looks like, and where to place it. Annotations cover the safety profile. No significant gaps for a tool of this complexity.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds some context about url (any URL) and indirectly about max_links via 'key links', but it does not meaningfully enhance parameter meaning beyond the schema. Meets the baseline for high 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 opens with a specific verb-resource pair: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this tool from siblings by naming the exact output artifact and the process (fetches, extracts, emits). No ambiguity.

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

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

A 'Useful for' list gives three concrete scenarios (client indexing, own project drafting, competitor auditing), providing clear context on when to use. However, it does not explicitly mention alternatives or when-not-to-use, preventing 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 destructiveHint. The description adds behavioral context by specifying exactly what data is returned (fields, geometry type, record count, capabilities), which is useful beyond the annotations. No contradictions found.

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

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

The description is one compact sentence that front-loads the purpose and lists return items without any fluff. Every word earns its place, making it highly concise and well-structured.

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

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

For a simple single-parameter read-only tool, the description is complete. It explains the purpose, the input URL, and the expected return data (fields, geometry type, count, capabilities). No output schema exists, so the description adequately covers return value context.

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

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

The single parameter 'url' is already well-described in the schema (including an example). The tool description only repeats 'by url' without adding more semantic detail. Schema coverage is 100%, so baseline 3 applies.

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

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

The description clearly states the tool's function: 'Get an ArcGIS Feature/Map Service layer's schema by url', and lists the specific return components (fields, geometry type, total record count, capabilities). This distinguishes it from siblings like query_layer which would retrieve data rather than schema.

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

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

The description implies usage via 'by url' but does not explicitly contrast with alternative tools (e.g., query_layer) or state when not to use it. It lacks explicit 'when to use this vs alternatives' guidance, so it falls to implied usage rather than clear contextual direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds meaningful behavioral details: it returns specific fields (id, type, params, timestamps, fire_count) and implies active-by-default behavior, while the schema handles include_inactive. This exceeds the baseline and enriches understanding.

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

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

Two sentences, front-loaded with action and resource, followed by return fields and usage guidance. Every sentence earns its place, with no redundancy 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?

For a simple list tool with strong annotations and one well-documented optional parameter, the description fully covers purpose, return format, and application. No significant gaps remain for the stated use cases.

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 include_inactive fully described. The description's mention of 'active' and 'cancel' aligns with the parameter but does not add new semantic meaning beyond what the schema provides, so it meets the baseline without exceeding it.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', distinguishing it from sibling tools like subscribe and unsubscribe. It also specifies the return fields, making the tool's purpose unambiguous.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. These guidelines implicitly differentiate it from subscribe/unsubscribe, giving the agent clear context for when to invoke this tool.

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

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

Discloses rate-limiting (5/day), no tool-call quota impact, the claim_token flow for anonymous submissions, and that the team reads digests daily. These go well beyond the sparse annotations and set accurate expectations.

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

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

Though a single dense paragraph, every sentence serves a purpose: purpose, use cases, exclusions, claim_token mechanics, rate limits. It is front-loaded with the primary action and contains no 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?

As a feedback tool with 4 params and no output schema, this description explains the full lifecycle (file, receive token, later check status) and mentions relevant constraints. There is nothing material missing.

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

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

Schema covers all parameters, but the description adds crucial usage context: how to use claim_token to check status, not to paste user prompts, and to reference Pipeworx tools/packs. This clarifies invocation patterns beyond the schema definitions.

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: telling the Pipeworx team about broken/missing features or praise, with explicit examples. It distinguishes itself from sibling research tools by focusing entirely on feedback submission.

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 scenarios (bug, feature, data_gap, praise), a clear exclusion (only for Pipeworx-served tools, not other MCP servers), and tells where to file instead. This is a model of usage guidance.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds value with concrete details: data sourced from CF analytics-engine, no PII, just (pack, tool, count), and caching duration 5min-1h. This exceeds the annotation baseline.

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

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

The description is front-loaded with the core purpose, followed by a structured bullet list of use cases and a concise note on data source and caching. It uses four sentences with no filler, though slightly longer than strictly necessary.

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 explains the return value (top tools, packs, volume), window options, use cases, data source, and caching. Agents have enough to invoke it correctly without guessing.

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 'window' has 100% schema coverage including full description. The description repeats the schema's '24h, 7d, 30d' and the hot-vs-steady-state contrast, adding no new semantics beyond the schema.

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

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

The description states 'What other AI agents are calling on Pipeworx right now' and specifies outputs (top tools, top packs, total call volume). This clearly identifies a trending/popularity tool and distinguishes it from sibling search/discovery tools.

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

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

The 'Useful for' section lists three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It does not name alternatives or exclusions but the context is unambiguous.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral details: the fill check behavior, the partitioning filter thresholds, the semantic anchor similarity requirement, and the meaning of realizable_edge_pp <= 0. It explains what gets returned, how signals are priced, and what action to avoid—far exceeding the annotation baseline.

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

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

The description is quite long, but it is well-structured with clear mode breakdowns and labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Each sentence adds essential operational detail; however, it could be tightened slightly to improve skimmability. It is not wasteful, though.

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

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

This is a complex tool with multiple modes, filters, and a response format. With no output schema present, the description fully compensates by specifying the response fields (`opportunities[]`, `partition_check`) and warning about false positives. It covers the nuance of live book depth versus last-trade, making the description complete for an agent to use effectively.

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

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

Although the schema already covers both parameters with descriptions, the tool description adds substantial meaning: it explains the no-arg default, provides concrete examples for `event` and `topic`, clarifies mode-specific behavior, and details how each parameter maps to a distinct analysis type. This goes well beyond the schema's basic property descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings by detailing unique mechanisms (monotonicity and partition sums) and three operating modes. The scope is precise and 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 explicitly explains when to use each mode: no args for trending scan, 'event' for a specific market, and 'topic' for cross-event scanning. It even recommends `event` when targeting a specific market and names an alternative tool (polymarket_fill_risk) for custom sizing, satisfying the when/when-not/alternatives criterion.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond by detailing the three response segments, model families (e.g., crypto_price lognormal barrier from 90d FRED log-returns), tradeable-edge knobs, the 24h-move warning, the cache behavior ('Cached 1h at the KV level'), and the _diagnostics funnel counters. No contradictions exist between description and 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?

While the description is long, it is densely organized with clear section markers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loaded with the primary purpose. Every sentence provides distinct technical context that an agent would need. It could be trimmed slightly but the structure is effective for a complex tool.

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

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

Given the tool has no output schema and 9 optional parameters, the description compensates by specifying the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), segment contents, and filtering logic. It also explains edge_pp_net, kelly_fraction, and the 24h-move warning. The description provides sufficient context to understand the tool's full behavior 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 provides 100% description coverage for all 9 parameters, so the baseline is 3. The tool description adds meaningful context beyond the schema, such as why min_partition_leg_kelly exists ('Partition arbs always return kelly_fraction_half=0 at the parent level by design') and how category_filter relates to the segments. This raises the score to 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 uses specific verbs 'Scan' and 'return opportunities' paired with the resource 'top Polymarket markets' and the differentiator 'where Pipeworx data disagrees with market price.' It also states the built-for use case ('what should I bet on today'), which clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_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?

The description establishes clear usage context with 'Built for "what should I bet on today"' and notes that agents 'discover opportunities without paging hundreds of markets.' It also provides guidance on knob usage (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and mentions exclusions like Fed bets excluded from ranking. However, it does not explicitly name alternative tools for when not to use it, so a 4 is appropriate.

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

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

The description goes well beyond the readOnlyHint annotation, detailing response structure (tracked, expired, snapshot_dates), how decay is computed, snapshot-writing behavior on cache-miss, and limitations like TTL and daily-close data. 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 front-loaded with purpose, then organized into args, response, and limits. Every sentence provides value, though it could be slightly tightened without losing crucial detail.

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 fully explains the response fields and semantics, data freshness, gaps, and historical depth constraints. It is complete for a tool of this complexity and well-differentiated from sibling polymarket tools.

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

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

Schema description coverage is 100%, and both parameters are already well-described in the schema. The description adds minimal extra meaning beyond calling window a 'snapshot family' and restating the default/max values, which is marginal.

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 edge persistence and decay telemetry, with a specific question it answers: 'how long has this edge existed and is it shrinking?' It distinguishes from siblings by focusing on historical snapshot analysis rather than current edge discovery.

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

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

The description gives strong context for when to use this tool—when edge age matters—and explains how fresh vs. old edges are differently valued. It does not explicitly name alternative tools for current-edge queries, but the guidance is clear enough.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral detail: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp), and warns about forced directional risk from partial basket fills. This goes well beyond the annotations and provides critical context for an agent. No contradiction with annotations.

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

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

The description is long and dense, but every sentence carries weight given the tool's two-mode complexity. It uses ALL-CAPS labels for modes and clear lists of return values. While it could benefit from more formatting (e.g., bullets), it is appropriately structured and information-rich for the domain.

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 enumerates the expected return values for both modes, including per-leg fill details, thin_legs[], and max_clean_notional_usd. It also explains the risk of unhedged positions. Given the tool's complexity, the description provides a complete picture of inputs, outputs, and risks.

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%, giving the baseline of 3. The description adds meaningful interpretation by explaining size_usd as 'max spend on buys, target proceeds on sells' and, in basket mode, as 'settlement notional S (shares per leg).' It also clarifies that side defaults are auto-selected based on partition sum. These nuances go beyond the schema's basic type descriptions, meriting 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges signals and specifying when those signals should trigger this check. It also clearly delineates two distinct modes (single-market and basket), each with a specific purpose.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable) and warns about the risk of partial basket fills. It also distinguishes between single-market and basket modes, making it clear when each is appropriate.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It proactively discloses edge cases and safety fields: compatibility_warning with two distinct causes, temporal_alignment for resolution period matching, and skipped_cross_type/subtype counters for dropped comparisons. This gives agents deep insight into when results are meaningful and when they are 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 long but efficiently structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence adds substantive information; the detailed example of bet-shape mismatch is dense but illustrative. It is not as trimmed as it could be, 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?

Given the tool's complexity and absence of an output schema, the description does a commendable job of explaining the response structure (leg-by-leg prices, matched spread, top_spreads_pp) and the meaning of safety fields. However, it does not clarify behavior when zero parameters are provided or when only one of the two explicit identifiers is supplied, which is a minor gap for a tool with 0 required parameters.

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

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

The schema already provides 100% coverage for all three parameters. The description adds valuable context beyond the schema by explaining the interaction between topic and explicit parameters (explicit overrides the mapped side), and by naming all valid topic values inline. This enriches the semantic understanding, though the schema descriptions are already strong.

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

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

The description opens with a specific, unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's core function and distinguishes it from sibling tools like polymarket_arbitrage, which focus on single-venue opportunities. The two-mode design (topic vs explicit) further clarifies intended usage.

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 explains the two modes (pre-mapped topic shortcuts vs explicit ticker/slug pairing) and provides context for when each is appropriate. It also warns that most pre-mapped topics return compatibility_warning today, advising caution. However, it does not explicitly name alternative tools or exclusion criteria, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature, reducing the burden on the description. The description adds that it 'Returns attribute rows (and geometry)', which is useful. However, it doesn't disclose potential error conditions or pagination behavior. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two concise sentences with no fluff. The first front-loads the core function and key parameters, and the second gives a practical sampling tip. 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?

With 6 parameters and no output schema, the description covers the main parameters, return type ('attribute rows (and geometry)'), and usage context. It lacks details on error handling or response structure, but the core functionality is well explained. Sufficient for a non-destructive query tool with strong annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the relationship between parameters and providing a concrete usage pattern ('where="1=1" + out_fields="*" to sample'). This adds practical meaning beyond the individual field descriptions.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer, specifying the resource type and source (search_datasets). It distinguishes from siblings like search_datasets and layer_info by focusing on data retrieval. The verb 'Query' and specific parameter list make the purpose unambiguous.

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

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

It explicitly ties usage to search_datasets ('by its url (from search_datasets)'), implying a workflow. It also gives a specific sampling tip ('Use where="1=1" + out_fields="*" to sample'). However, it doesn't explicitly mention alternative tools or when not to use this tool, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the important scoping detail: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains the optional key behavior (list all when omitted), which is a behavioral trait not fully 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?

Three sentences, front-loaded with the primary action, then usage context, scoping, and sibling relationships. No filler or repetition.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what it does, when to use it, scoping, and related tools. It does not explain error behavior, but the low complexity makes this acceptable.

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 states 'omit to list all keys.' The description reinforces this and provides examples of key types, but does not add new parameter syntax or format beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument),' which specifies the verb and resource and clearly distinguishes this from sibling tools like remember and forget. It also gives concrete use cases ('the user's target ticker, an address, prior research notes').

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

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

It explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also points to alternatives by saying 'Pair with remember to save, forget to delete,' which implies when not to use this tool.

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

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

The description explicitly mentions a state-changing behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the annotation readOnlyHint:true, which asserts the tool makes no modifications to server state. This is a direct annotation contradiction, warranting the lowest score regardless of other added 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 moderately sized with five sentences, each carrying useful information. It front-loads the core purpose, then explains filters, side effects, and an alternative access method. No sentence is wasteful, though it could be slightly tighter without losing meaning. This is efficient but not maximally concise.

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

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

There is no output schema, so the description compensates by listing return fields (source, citation_uri, raw event payload). It explains the persisted feed, filtering options, mark_read behavior, and even provides an HTTP alternative. The schema covers all parameters (including unread_only), so the description is fairly complete for a read/list tool, but the annotation contradiction undermines overall completeness.

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 meaningful parameter descriptions, so the baseline is 3. The description adds value beyond the schema by providing a concrete type example ('sec_8k'), explaining the mark_read side effect (how it affects subsequent calls), and clarifying the return payload fields. This lifts 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 ('Pull') and resource ('fired events from your subscription feed'). It distinguishes the tool from siblings like list_subscriptions and recent_changes by emphasizing alerts from the persisted feed, and includes relevant details like return fields. This is a specific, unambiguous purpose statement.

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 useful usage context, explicitly noting that polling works fine and pointing to an HTTP endpoint for scripts/dashboards. It also gives filtering examples (type, since). However, it does not explicitly state when to prefer this tool over alternatives or list exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by disclosing fallback behavior (GDELT preferred, GNews fallback on rate-limit/5xx), USPTO sunset and soft-fail, and the return shape (changes[] grouped by source, total_changes, citation URIs). This enriches the agent's understanding of side effects and limitations without contradicting any 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 well-organized: it front-loads with example queries, then states the core function, lists data sources and fallbacks, explains the `since` parameter, describes the return value, and closes with an alternative. Every sentence adds value, though it is longer than the ideal two-sentence example. The use of em dashes and semicolons keeps it compact despite the volume of information.

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

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

Given the tool's complexity (three parameters, no output schema, multiple data sources with fallbacks), the description is impressively complete. It explains the return structure (changes[], total_changes, pipeworx:// URIs), source-specific behavior, failure modes (USPTO sunset), and how to differentiate from entity_profile. This is sufficient for an agent to invoke the tool 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?

Schema description coverage is 100%, so the schema already documents all three parameters (type, since, value) with types, enums, and examples. The description repeats the `since` format (ISO or relative) and `value` as ticker/CIK, but adds little new parameter-level meaning beyond restating the schema. The baseline of 3 is appropriate because the schema does the heavy lifting and the description provides minor supporting context (e.g., what `since` applies to).

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

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

The description uses specific verbs and resources: 'change feed for a company in the last N days/weeks/months in ONE parallel call' and elaborates on fan-out to SEC EDGAR, GDELT/GNews, and USPTO. It clearly distinguishes from the sibling tool entity_profile by explicitly stating 'Use entity_profile instead when you want the static profile...' This makes the tool's purpose unmistakable and differentiated.

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

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

The description opens with concrete user intents ('What's new with X' / 'latest on Y' / 'updates on Acme') and explicitly names an alternative (entity_profile) for static profiles. However, it does not address other potentially similar sibling tools like recent_alerts, leaving some ambiguity about when to prefer this over other change-related tools. Still, the primary use case and a key exclusion are clearly stated.

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 it as a write operation (readOnly=false) and idempotent. The description adds useful context about persistence (24 hours for anonymous users vs permanent for authenticated users) and scoping by identifier. However, it doesn't explicitly state overwrite behavior per key, which is a minor gap given idempotency.

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

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

The description is compact yet information-dense, covering purpose, usage, persistence, and tool relationships in three sentences. Every sentence contributes a distinct aspect, with no redundancy.

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

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

For a simple key-value store, the description covers all necessary aspects: what it does, when to use it, persistence behavior, and companion tools. The annotations and full schema coverage fill any remaining gaps, making the tool fully comprehensible.

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 fully documents both parameters (key and value) with examples, achieving 100% coverage. The description's examples of keys and values overlap with the schema, so it adds little beyond the schema's 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 clearly states 'Save data the agent will need to reuse later' with concrete examples of memory-worthy items. It distinguishes itself from siblings by naming recall and forget for retrieval and deletion, making its role in the memory triad 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?

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and lists example scenarios. It also directs to complementary tools (recall, forget), giving clear context for when to use 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 provide safety hints (readOnly, idempotent, etc.), and the description adds substantial behavioral context: internal cascading through multiple lookup endpoints, graceful degradation when external sources fail, explicit reporting of unresolved identifiers, and source labeling. This goes well beyond the annotations, so a 5 is warranted.

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

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

The description is dense but well-structured, leading with example queries and the core purpose before diving into type-specific details. While long, each sentence adds meaningful context, earning a 4 rather than 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?

The description thoroughly covers what the tool returns for both entity types, including identifiers with source labels, unresolved entries, and a citation for drug lookups. Without an output schema, this level of detail is essential and well-provided.

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

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

Schema coverage is 100%, and the description adds value by explaining the resolution outcomes for each type (CIK/ticker/LEI/FIGI for company; RxCUI/ingredient/brand for drug) and noting accepted input formats like ISIN. This enriches the parameter semantics beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides concrete example queries and explicitly positions it as the first tool to use when a name needs an ID, distinguishing it from sibling tools.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. However, it does not name alternative tools or specify when not to use it, so it falls short of a perfect 5.

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

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

The description reveals that the tool 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and 'Returns ranked list with score, confidence, signal density per entity.' This goes beyond the annotations (readOnly, idempotent) and provides insight into its internal process and output, which is valuable for the agent.

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 purposeful sentences are front-loaded with the primary action, followed by the use case and output details. The example quote adds color without unnecessary length. There is no fluff or repetition.

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

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

Given there is no output schema, the description properly explains the return structure (ranked list with score, confidence, signal density) and the relationship between the subject and competitors. It covers the main use cases and behavioral flow, though it does not elaborate on optional parameters (models, _apiKey) which are already well-documented in the schema, so this is sufficient.

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

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

Schema description coverage is 100%, and the schema already explains each parameter. The description adds minimal extra semantics beyond 'your brand + N competitors', which the schema also covers in the entities description. Thus it does not significantly enhance parameter understanding beyond the structured data.

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

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

The description opens with 'Compare AI visibility across multiple entities side-by-side', using a specific verb (Compare) and resource (AI visibility). It clearly distinguishes from the sibling tool ai_visibility_check by emphasizing side-by-side comparison and ranking, making its purpose unambiguous.

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

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

It provides a clear use case: 'Useful for competitive AI-marketing audits' and gives an example question. It implies use when comparing multiple entities, though it does not explicitly state when not to use it or name alternatives, so it lacks explicit exclusionary 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 the read-only/idempotent annotations, it discloses the composite fan-out architecture, the 5-30s first-measurement latency from bundlephobia, and graceful degradation via sources_failed. This is operational context the agent would otherwise not know.

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

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

The description is dense but well-structured, with each sentence serving a distinct role: purpose, usage trigger, output contract, ecosystem caveat, and failure handling. It is longer than average but justified for a composite tool with no output schema.

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

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

With no output schema, the description takes on the full burden and enumerates the exact summary block fields, mentions per-advisory detail and links, and explains the timeout behavior. It leaves no critical gap about what the agent can expect in return.

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?

Both parameters (package, version) have 100% schema coverage with clear descriptions. The tool description only restates the npm ecosystem limitation and the version default which are already implied by the schema, adding no substantial new semantic information.

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 user-centric problem: 'should I add this npm package to my project' check in ONE call. It precisely names the data sources (deps.dev and bundlephobia) and explicitly limits scope to the NPM ecosystem, distinguishing it from sibling research tools.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an alternative pathway: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clearly defining when not to use this tool.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, reducing the burden. The description adds value by detailing the output contents (name, summary, record_count, owner/org, url) and the scope (Pima County GIS open data), which are not in annotations.

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

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

Two concise sentences, front-loaded with action and scope, with each sentence contributing meaningful information. 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?

Given no output schema, the description helpfully lists the returned fields and suggests next steps. It covers essential usage context, though it omits edge cases like no-result behavior or pagination details.

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 query, limit, and org_id. The description does not add parameter-level details beyond the schema, 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 tool searches Pima County GIS open geospatial datasets by keyword, with specific examples. It distinguishes itself from siblings by naming downstream tools (query_layer/layer_info) and listing the exact return fields.

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

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

The description implies the intended workflow: use this tool to discover datasets, then pass the returned Feature Service url to query_layer/layer_info. It gives clear context and a usage pattern, though it doesn't explicitly exclude alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant extra context: the embedding model (BGE-base-en), similarity metric (cosine), chunking approach (500-char overlapping windows), input cap (200K chars), and truncation/flagging behavior. This far exceeds the annotation baseline and is genuinely useful for anticipating results.

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

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

The description is dense but every sentence earns its place. It front-loads the core action, then covers use case, pairing, and technical details in a logical flow. There is no fluff or repetition, making it efficient for an agent to parse.

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

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

Without an output schema, the description explains what the agent will get back: 'top-N passages with character offsets and similarity scores.' It also covers edge behavior (truncation and flagging beyond 200K chars) and the relationship to sibling tools. For a search tool with 3 parameters, this is comprehensive.

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 each parameter already described. The description adds real value by giving concrete examples for `query` (e.g., 'supply-chain risk') and clarifying that `text` is 'the text you already pulled.' It also explains that `limit` affects 'top-N passages.' While the schema is sufficient, the description enriches understanding without redundancy.

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 immediately states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings by clarifying the input is text already pulled (e.g., a SEC 10-K body) and the output is top-N passages with character offsets and similarity scores. This clearly separates it from tools like 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?

Explicit guidance is given: 'Use when the record is too big to cram into the prompt.' It also names a complementary alternative, ask_pipeworx_grounded, and describes the recommended workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives the agent clear decision-making 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?

The description's 'Returns the new subscription id' implies each call creates a unique subscription, which contradicts the annotation idempotentHint=true. Despite providing rich detail on OAuth requirements, verification, and webhook behavior, the contradiction forces a score of 1 per the rubric.

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 purpose is front-loaded and every sentence carries substantive detail. However, the long single paragraph could be more scannable with bullet points or structured sections, though it remains appropriately sized for the tool's complexity.

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

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

Covers prerequisites, all subscription types with examples, delivery channel constraints, feed fallback, return behavior, and verification requirements. Since there is no output schema, the description appropriately discloses the returned ID and webhook secret, making it complete for a tool of this complexity.

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

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

Although the schema already covers all parameters, the description adds semantic meaning beyond the schema, such as item-code examples ('5.02' = officer change), SMS verification and daily cap, and webhook signing secret behavior. This significantly enriches parameter understanding beyond the structured fields.

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,' specifying the verb and resource. It enumerates supported types and delivery channels, distinguishing it from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 prerequisites (Pipeworx OAuth account) and notes that anonymous/BYO cannot persist subscriptions. It also mentions feed pull alternatives (recent_alerts, GET registry.pipeworx.io/alerts.json), but does not explicitly name alternatives for stopping or managing subscriptions beyond the sibling list.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context beyond annotations: it returns dynamic content drawn from a live catalog, provides example questions with tool+argument shapes, and behaves differently with or without the topic argument. 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 longer than average but every sentence adds value: example queries, return contents, invocation options, and usage guidance. It is well-structured and front-loaded with user intents, earning a 4 rather than 5 due to minor redundancy (e.g., listing all categories twice).

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

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

Despite no output schema, the description fully explains what the tool returns, how to invoke it in both modes, and when to use it in context of the broader tool ecosystem. It is complete for an onboarding tool with a single optional parameter.

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 the 'topic' parameter with allowed values, so baseline is 3. The description adds practical examples ('finance', 'pharma', 'betting') and explains the behavior difference between omitting and passing the parameter, enhancing schema semantics.

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

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

The description clearly states the tool's function: an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shapes. It distinguishes itself from siblings by framing its role as a 'first' step and referencing meta-tools like ask_pipeworx and entity_profile.

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

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

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

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 significant behavioral context beyond annotations: ownership enforcement ('you can only cancel your own subscriptions') and the soft-delete behavior ('row is deactivated, not deleted') with a note that history remains available. This complements the annotations without contradicting them.

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

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

The description is two sentences with no redundant filler. Every sentence contributes to understanding the tool's purpose and side effects, making it appropriately sized and front-loaded.

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

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

Given the low complexity (one parameter) and the rich annotations, the description covers the key aspects: what it does, ownership, and the non-destructive outcome. It doesn't describe the return value, but this is not critical for a simple cancel operation.

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

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

The schema already documents the 'id' parameter as a subscription UUID. The description reinforces that it's the target for cancellation and adds ownership semantics (the id must be yours), which is useful for correct usage.

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

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

The description begins with 'Cancel a subscription by id,' which is a specific verb+resource pairing that clearly identifies the tool's function. It also distinguishes from siblings by noting the deactivation behavior, making it distinct from subscribe and list_subscriptions.

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

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

The description implies when to use it (when canceling a subscription) and provides important context about ownership and the non-destructive nature. However, it does not explicitly contrast with alternatives or state when not to use it, but the context is clear enough for a simple tool.

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

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

Annotations already declare read-only, open-world, and idempotent, but the description adds critical behavioral nuances: it explains that could_not_verify means the check did not happen and must not be shown as evidence, and unsupported means no source was found. It also discloses the internal fast-path vs grounded pipeline routing and the fact that it replaces 4-6 sequential calls. No contradiction with annotations.

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

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

The description is long, but every sentence carries essential information: query examples, routing logic, verdict list, and important caveats. It is front-loaded with intuitive examples and avoids fluff. Though somewhat dense, it is not wasteful.

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 takes responsibility for explaining return values. It lists all verdicts, the actual value with pipeworx:// citation, and reasoning. It also clarifies edge cases (could_not_verify vs unsupported) and mentions the efficiency advantage over sequential calls. This is complete for a moderately complex fact-checking 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?

Both parameters (claim, tolerance_pct) are fully documented in the schema with 100% coverage. The description adds minimal extra semantic value beyond the schema; it mentions 'exact percent-delta math' which relates to tolerance but does not elaborate on parameter formats or defaults. Baseline 3 is appropriate.

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

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

The description explicitly states 'natural-language claim verification against authoritative sources' and provides multiple example query phrasings ('fact check', 'verify the claim that...'). It clearly distinguishes this tool from general Q&A or research tools by focusing on returning a verdict, which separates it from siblings like ask_pipeworx or deep_research.

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

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

States 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths (structured SEC EDGAR for company financials, grounded pipeline for everything else). It does not name specific alternatives to avoid, but the guidance is clear enough for correct tool selection.

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