Arcgis Kingston

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations by revealing the default model (Workers AI Llama-3.3-70b, free) and the cost implication of passing _apiKey (BYO key; user pays Anthropic directly). It also outlines the response shape, giving the agent a clearer model of behavior.

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

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

The description is two sentences long and front-loaded with the primary action. Every sentence earns its place: the first explains what it does and the default, the second covers optional key behavior, return format, and use cases. No fluff or redundancy.

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

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

Given the tool has 4 parameters, no output schema, and a read-only probe nature, the description is complete enough. It explains the default model, the optional Anthropic key, the per-model and combined output structure, and gives concrete use cases. The agent can select and invoke this tool correctly without needing additional 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 description coverage is 100%, so the baseline is 3. The description adds meaningful context over the schema by explaining the role of _apiKey (to probe Anthropic) and the default behavior when 'models' is omitted. This helps the agent understand parameter relationships and cost implications beyond the raw 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 uses a specific verb ('Probe') and resource ('LLMs') and clearly states the tool scores visibility (0-100) per model. It describes the return format and use cases, making the purpose unambiguous. However, it does not explicitly differentiate itself from nearby siblings like 'scan_competitor_ai_presence' or 'compare_entities', missing the opportunity for sibling distinction.

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

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

The description gives clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and implies the free vs. paid model choice. It does not explicitly name alternatives or state when not to use this tool, but it provides enough usage context to guide an agent.

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

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

The description discloses key behavior beyond the annotations: it routes questions to one of 5,581 tools, fills arguments, and returns a structured answer with stable pipeworx:// citations. It doesn't contradict the annotations, and it gives the agent a good mental model of what happens after invocation.

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

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

The description is long but front-loaded with the critical preference instruction. The domain-salary list and example queries are useful for a broad general-purpose tool, though some list items are redundant. It could be slightly tighter, but the structure remains clear.

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 covers input type, when to use, examples, and the nature of the output (structured answer with citation URIs), which is a lot for a tool with an open-world, read-only scope. It does not address potential failure modes or how to handle ambiguous entity references, and it does not guide the agent toward sibling variants, so it is not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the parameter is natural language question fragments and adds example queries, but contributes no new parameter semantics beyond what the schema already describes.

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's purpose: ask_pipeworx routes factual/current/historical questions to authoritative tools and returns structured answers. It uses specific verbs and a broad resource list, distinguishing itself from general web search. It does not explicitly differentiate from sibling pipeworx variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it loses the full score.

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

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

The description gives very explicit usage criteria: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with concrete example queries. It clearly indicates when to use this tool versus generic web search. However, it does not discuss when to use the sibling ask_pipeworx variants instead, making the guidance slightly incomplete.

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 behavior, but the description adds critical dynamic context: candidate improvements 'enabled live', the fact that 'No candidate is active right now', and the explicit warning 'Falls back to nothing — this IS a full working router'. It also explains that outputs are compared against the stable router, giving the agent a mental model of how behavior might drift over time. 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?

Four sentences deliver the essential caveats (beta, live toggling, no active candidate), usage instruction, and fallback clarification in a front-loaded, logical order. The final 'Falls back to nothing' sentence is slightly redundant with the earlier 'identical to ask_pipeworx exactly' but reinforces an important safety point. A minor redundancy that doesn't hurt usability.

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 router with no output schema, the description covers the dynamic aspect that matters most: behavior may change when a candidate is under test, and currently matches stable. The main gap is that the 'no candidate active' statement will go stale, and there's no way for an agent to dynamically detect when a candidate is active beyond calling the tool. Still, it gives the agent a robust mental model 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 coverage is 100%, so the baseline is 3. The description adds value by guaranteeing 'same arguments' as the stable ask_pipeworx, letting an agent reuse its knowledge of the sibling's parameters without re-deriving them. It doesn't redefine the aliases, but it doesn't need to given the thorough 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 is explicit: it identifies the tool as a beta version of ask_pipeworx that is an 'identical universal router (same 5,581 tools, same arguments, same response shape)' with live-toggled candidate improvements. It clearly sets expectations that it is experimental yet fully functional, distinguishing it from the stable sibling ask_pipeworx. The scope and relationship to the stable version are unambiguous.

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

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

The description directly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the alternative (ask_pipeworx/stable router) and clarifies the current equivalence state when no candidate is active. This mirrors the quality of the HIGH calibration example.

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

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

The description discloses the full refusal reason enum, the fact that it costs an extra LLM call, and that it uses only tool result content, with evidence as a verbatim quote. It also details the exact return fields. This goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) and gives the agent complete behavioral 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?

Every sentence earns its place: purpose, mechanism, return format, refusal conditions, use cases, and cost trade-off. The description is appropriately sized for the tool's complexity and front-loaded with the core purpose before diving into details. 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?

Given that there is no output schema, the description fully specifies the return object and refusal reasons. It also covers the cost/performance trade-off and explicitly names the sibling alternative (ask_pipeworx). Nothing an agent needs to decide when to invoke and how to interpret results 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% (all six parameters are described as aliases for 'question'). The description adds no additional parameter-level details, which is acceptable given the high coverage. Baseline of 3 is therefore appropriate; no extra credit is warranted because the description doesn't enrich parameter understanding beyond the schema.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains the tool's function: same routing as ask_pipeworx, then extraction using only tool result contents, with a refusal mechanism. This distinctly differentiates it from the sibling ask_pipeworx, which lacks the extraction and refusal behavior.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also says 'prefer ask_pipeworx for casual lookups,' providing a clear alternative and when-not-to-use condition. This is more than sufficient 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 declare readOnly, idempotent, and openWorld hints, and the description adds extensive behavioral context: resolver confidence levels, low-confidence short-circuiting, market_closed_or_inactive status, wide-spread tradeability, cancellation rule parsing, parent event extraction, and news fallback mechanisms. This goes far beyond the annotations and gives agents critical operational knowledge.

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

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

The description is long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK) and front-loads the core purpose. Each section adds operational value for a complex tool; while not as minimal as a two-sentence description, the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates fully by explaining return shapes, status codes, failure modes, safety behaviors, and resolution rules. It covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules, making it operationally complete for an agent.

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

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

Schema coverage is 100%, with all three parameters documented in the schema. The description mentions input forms and the include_raw behavior, but does not add substantial new parameter semantics beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from sibling tools by focusing on a single bet and aggregating multiple data sources, with explicit examples of input formats and output structure.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It clearly indicates when to use the tool, though it does not explicitly name alternative tools or exclusions like the top-calibration example. Context is strong, 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), fiscal-year handling, sorting by primary metric, and the return format (paired data + citation URIs). This fully informs the agent about what the tool does internally.

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 yet efficient, opening with user-facing trigger phrases before diving into specifications. Every sentence contributes either to when to use, what data is pulled, or how results are returned—no wasted words.

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

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

For a tool with only 2 parameters, the description covers inputs, data sources, sorting behavior, return format, and alternatives. It leaves no obvious gaps for an agent to misuse the tool, and the annotations cover safety constraints.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values'. The description adds semantic meaning by explaining what each type value ('company' vs 'drug') pulls, and provides explicit examples for values (e.g., ["AAPL","MSFT"], ["ozempic","mounjaro"]). This goes beyond the schema's generic descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in ONE parallel call. It uses specific verbs like 'compare' and lists trigger phrases, and it distinguishes itself from single-entity lookups by emphasizing parallel comparison.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing when-to-use guidance and naming the alternative approach. It also gives concrete comparison scenarios like 'X vs Y' and 'rank these companies,' making usage context very clear.

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

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

The description explicitly mentions the account requirement and the need for a paid plan for depth:'thorough', which is useful behavioral context. However, it does not disclose other behaviors like data usage, side effects, or limitations beyond the account tier. Since no annotations are provided, the description itself must carry this weight, and it is only partially informative.

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

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

The description is concise and front-loads the critical account requirement with a URL and conditional advice. It avoids repetition but might benefit from stating what the tool actually returns or how it differs from alternatives.

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 complexity of a research tool with multiple parameters (including a depth parameter with tier implications) and no output schema, the description is too brief. It doesn't explain what 'grounded' means, what sources are used, how the output is formatted, or how it compares to other research tools like ask_pipeworx beyond the signed-in condition.

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

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

The input schema covers the parameters (100% coverage), so baseline is 3. The description does not add any additional parameter semantics beyond mentioning the 'depth' parameter's cost implication in the auth note. No extra guidance on parameter usage is provided.

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

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

The description states it does 'Grounded multi-source research', which gives a general sense of purpose but lacks specificity about the exact scope, output, or how it differs from other research tools. It names no specific resource or domain, and while 'deep_research' implies depth, the description doesn't elaborate on what that entails.

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

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

The description provides a clear conditional: if not signed in, use ask_pipeworx instead. However, it does not explain when to choose deep_research over other alternatives when signed in, or what distinguishes it from ask_pipeworx_beta or other research-oriented siblings. The guidance is partial.

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

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

Annotations already mark it as read-only and idempotent. The description adds valuable behavioral context: results include names, descriptions, and full input schemas with curated examples, and no second schema lookup is needed. This goes beyond 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 main purpose and includes a useful list of searchable domains. It is somewhat dense but every sentence contributes to agent understanding without filler.

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

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

Given the absence of an output schema, the description fully explains the return format (top-N tools with names, descriptions, schemas). It also covers usage timing and domain coverage, making it complete for this moderately simple read-only tool.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the schema. The description only adds the 'top-N' phrasing for limit, but doesn't provide additional parameter semantics beyond the schema, meeting the baseline.

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

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

The opening phrase 'Find tools by describing the data or task' clearly states a specific verb and resource. It distinguishes itself from sibling data-retrieval tools by focusing on tool discovery, not data retrieval.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear when-to-use guidance and implies alternatives when the tool is already known.

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 behavior, but the description adds significant context: it fans out across multiple sources, uses fallbacks (GDELT→GNews), soft-fails on the USPTO API sunset, and imposes input restrictions (zero-padded CIK). These traits go well beyond the annotations and help the agent predict edge cases.

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

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

The description is long but well-organized, mixing example queries, behavioral notes, and return-field details. It front-loads the core purpose and then provides necessary specifics. A bit verbose, but every sentence carries useful information.

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

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

There is no output schema, so the description must explain return values, and it does, listing cik, company_name, recent_filings, fundamentals, patents, news, and LEI sources. It also covers failure modes (soft-fail) and input limitations. Slightly missing exact JSON shapes or error codes, but overall sufficient for a complex tool.

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

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

The schema already documents both parameters with full coverage, so the baseline is 3. The description adds practical examples ('AAPL', '0000320193') and clarifies the zero-padding requirement and the unsupported name input, which is useful for correct invocation.

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

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

The description is very specific: 'full cross-source profile of a US public company in ONE parallel call' with concrete examples like 'Tell me about X' and 'company profile for Microsoft.' It clearly distinguishes itself from sibling tools by advising 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-only inputs.

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 when to use (holistic view needs) and when not to (when only a name is provided, use resolve_entity first). It also suggests avoiding the alternative of chaining multiple tools, naming the preferred approach directly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description's 'Delete' aligns with these but adds little beyond restating the operation—no mention of irreversibility or behavior for missing keys. It adds some usage context but no new behavioral traits.

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

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

Two concise sentences front-loaded with the action, followed by use cases and related tools. No redundancy or wasted words.

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

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

For a simple one-parameter tool with annotations covering destructiveness and idempotency, the description fully covers purpose and usage. No output schema exists, so return values need not be explained. Pairing with remember and recall adds helpful 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?

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete.' The description mentions 'by key' in prose but adds no additional semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory by key), and distinguishes from siblings like remember and recall by focusing on removal.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, implying alternatives, though it does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, but the description adds valuable behavioral detail: it fetches the page, extracts title/description/key links, and outputs a single text blob in standard llms.txt markdown. This goes beyond the annotations and gives the agent a clear model of what happens when the tool is invoked, without contradicting any annotation.

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: two sentences plus a short 'Useful for' list. It front-loads the main action, then adds brief process context and concrete application scenarios. Every sentence earns its place without fluff, making it easy for an agent to parse quickly.

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

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

Given the tool is a simple read-only generator with two well-schema'd parameters and no output schema, the description is complete. It covers purpose, process, output format ('single text blob'), and typical use cases. The annotations cover safety (read-only, idempotent), so no further disclosure is necessary.

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% (both 'url' and 'max_links' are described), so the baseline applies. The description does not add extra parameter information beyond what the schema provides; it only reinforces the 'url' purpose via 'for any URL'. Thus it neither enhances nor detracts, staying at the minimal viable level.

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

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

The description opens with a specific action verb ('Generate') and a concrete resource ('a production-ready llms.txt file for any URL'), clearly stating what the tool does. It further explains the process (fetches, extracts, emits markdown), making it distinct from sibling tools like 'scan_competitor_ai_presence' which focus on auditing rather than generating.

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 ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context on when to use it. It stops short of naming alternative tools or stating when not to use it, but the scenarios effectively guide selection.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive, covering safety. The description adds the specific return fields (schema, geometry, record count, capabilities), which is useful but does not disclose potential latency, authentication requirements, or failure modes. This meets the lower bar set by annotations but adds only modest 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 a single, front-loaded sentence that starts with the action verb 'Get' and immediately states the resource and output details. Every word contributes meaning, with no filler or redundancy.

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

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

For a simple one-parameter read-only tool, the description fully explains the tool's purpose and the content of the returned information. It lacks an explicit example of a valid URL format, but the schema's example covers that. Minor gaps include not specifying whether it works with both map and feature services, though the description mentions both. Overall, it is complete for the tool's complexity.

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

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

Schema coverage is 100% with the single 'url' parameter adequately described in the input schema. The description just restates that the tool uses a URL, adding no new semantic information beyond what the schema already provides. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Get an ArcGIS Feature/Map Service layer's schema by url' and specifies the exact outputs: fields (name + type), geometry type, total record count, and capabilities. This distinguishes it from siblings like query_layer, which likely queries data rather than metadata.

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

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

The description establishes clear context: use this tool when you need schema information for an ArcGIS service layer, identified by URL. It does not explicitly name alternatives or exclusion scenarios, but the specific verb and resource make the intended use obvious, fitting the 'clear context, no exclusions' level.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by disclosing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's active subscriptions, which is useful behavioral context not in the schema.

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

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

At two sentences, the description is tightly written: the first states the action and return fields, the second gives usage guidance. No redundant phrases, all information 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?

The tool is simple (1 optional param, no output schema), and the description covers the return shape and primary use cases. It doesn't mention error conditions or permissions, but annotations indicate a safe read operation, and the schema covers the 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?

The only parameter, include_inactive, already has a complete description in the schema (100% coverage). The tool description does not mention this parameter, so it adds no extra semantic meaning; 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: 'List the caller's active subscriptions,' specifying a unique verb and resource scope. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on review, not mutation.

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 offers use cases: 'review what you're monitoring before adding more or to find an id to cancel,' giving concrete guidance for when to invoke. It implicitly positions this against subscribe/unsubscribe by naming those actions.

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 are all false, so the description carries the full disclosure burden. It fully meets it by revealing: the claim_token mechanism (filing without an account returns a token; passing it back retrieves status), the team's daily digest review, the rate limit (5 per identifier per day), and that the call is free and quota-free. It also warns about the delay if used for non-Pipeworx tools. This goes far beyond typical descriptions.

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

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

The description is long but every sentence delivers necessary information: purpose, usage scenarios, exclusions, token flow, rate limits, and quota implications. It is front-loaded with the core purpose and expands logically. Slight verbosity keeps it from a 5, but it is well-organized and free of redundant statements.

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 and only all-false annotations, the description is self-sufficient. It covers the full lifecycle (filing feedback, receiving a token, checking resolution), explains constraints (rate limit, quota, scope), and addresses potential misuse (other servers). The nested context object is not explicitly detailed but its purpose is clear from the schema, and the description's guidance about tool/pack terminology compensates. For a feedback tool of this complexity, this is complete.

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

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

Schema coverage is 100% so the baseline is 3. The description adds value by demonstrating the exact invocation for claim_token retrieval (`pipeworx_feedback({claim_token:"pwfb_…"})`) and by instructing users not to paste the end-user's prompt into the message field. These additional semantics help the agent construct correct calls, nudging the score above baseline.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature, data_gap, praise), and distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues rather than seeking answers. The scope restriction to only Pipeworx-served tools further clarifies its unique role.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and provides a clear exclusion: do not use for tools from other MCP servers. It also offers a heuristic for identification ('Pipeworx tool names are the ones this connection lists') and gives content guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This is model guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond those: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This informs the agent about data provenance, privacy, and freshness, which is not captured 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?

The description is well-structured and every sentence carries weight. It opens with a clear definition, then details outputs and use cases, and ends with transparency notes. The numbered 'Useful for' list improves scannability, and there is no redundant or filler content.

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

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

Given the tool's simplicity (one optional parameter), strong annotations, and lack of output schema, the description covers all essential aspects: what it returns, the data source, privacy, caching, and use cases. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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 merely mentions the window range ('24h, 7d, or 30d') without adding details beyond what the schema already provides ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). No additional semantic value is added.

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

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

The description clearly states the tool's purpose: 'What other AI agents are calling on Pipeworx right now' and specifies the exact outputs: 'top tools, top packs, and total call volume.' It distinguishes itself from siblings by emphasizing the aggregate, self-aggregating signal of agent usage, which is unique among the listed 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 provides explicit use cases: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' However, it does not mention alternative tools or when not to use it, so it falls short of a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds rich operational context beyond that: partition threshold >3pp, Jaccard similarity ≥0.30, placeholder fraction >20% causing null signal, and the fill-check pricing at 1000 shares/leg. 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?

Although long, the description is densely packed and front-loaded with the core purpose. Capitalized labels (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) structure the content, and every sentence contributes operational or safety-critical information. 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?

Given the tool's complexity and no output schema, the description is exceptionally complete: it covers default behavior, per-mode logic, filters, response shape, threshold values, fill-check caveats, and a pointer to a sibling tool for custom sizing. It effectively substitutes for documentation.

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

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

Schema coverage is 100%, but the description adds substantial value: no-args default behavior, concrete example slugs ('fed-decision-may-2026'), accepted full URLs, and a clear conceptual distinction between event and topic modes. This goes well beyond the baseline schema 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 three modes (trending_scan, event, topic), which differentiates it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description gives explicit when-to-use instructions: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also names a sibling alternative, 'For custom sizing use polymarket_fill_risk,' and even warns not to trade when realizable_edge_pp ≤ 0. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds extensive behavioral detail: model families, per-family logic, edge calculations, slippage assumptions, caching at KV level for 1h, diagnostics to explain empty segments, and a 24h-move warning. No contradictions.

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

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

The description is long and dense, but the opening sentence immediately states purpose and it front-loads the main use case. The structure uses parentheses and section labels, but it runs as a single block, making it harder to scan. The detail is warranted for the tool's complexity, though it could be better organized with bullet points.

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

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

Given the absence of an output schema, the description carries a heavy burden and largely succeeds: it details the top-level response keys (by_segment, fed_candidates, _diagnostics), lists edge metrics, explains knobs, and covers caching/empty-segment scenarios. However, it says 'FIVE MODEL FAMILIES' but then enumerates only four (crypto_price, news_momentum, partition_overround, concentrated_longshot), which is a minor inconsistency that could confuse an agent.

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

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

The input schema contains detailed descriptions for all 9 parameters, covering defaults and intent (e.g., slippage_pp explains zero fees but bid/ask costs). The description only briefly references min_liquidity/max_spread_pp and doesn't add semantics beyond the schema, so it meets the baseline for high coverage 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 opens with a specific verb ('Scan') and resource ('top Polymarket markets'), and states the output: opportunities where Pipeworx data disagrees with market price. It also names three response segments by model family, differentiating it from generic market tools. It doesn't explicitly name sibling tools, but the focus on Pipeworx disagreements and tradeable-edges framing distinguishes it from other polymarket tools.

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

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

Provides clear usage context: 'what should I bet on today' and 'without paging hundreds of markets'. It also explains when segments may be empty and mentions how knobs filter opportunities. However, it doesn't explicitly say when NOT to use this tool or name alternative sibling tools.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important operational behavior: snapshots are only written on cache-miss, so gaps exist; history is bounded by a 60-day TTL; decay is computed from daily closes of edge_pp_net (net of default slippage), not intraday. It also explains how expired opportunities are determined, adding significant transparency beyond the annotations.

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

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

The description is long but tightly packed with essential information: purpose, args, response structure, and limitations. Each segment (Args, RESPONSE, LIMITS) is clearly labeled and front-loaded with the core question the tool answers. No redundant sentences exist; every clause adds behavioral or semantic value.

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

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

With no output schema, the description fully covers return semantics: tracked[] items include edge_pp_net time-series, first_seen, trend, and decay_pp_per_day; expired[] includes lifespan_days; snapshot_dates[] explains data gaps. It also covers historical limitations (TTL, snapshot enablement) and the signed meaning of negative values. For a telemetry tool of moderate complexity, this description is complete.

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

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

The input schema already provides complete descriptions for both parameters (days lookback with clamp 2-30, window family with enum). The description restates defaults (days default 14, window default 1wk) but adds little beyond the schema—it only clarifies that window refers to the snapshot family. With 100% schema coverage, the baseline is 3, and the description does not meaningfully 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 names the tool's specific function: 'edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly answers the question 'how long has this edge existed and is it shrinking?' and distinguishes the tracker from sibling tools like polymarket_edges by focusing on time-series persistence rather than current edge detection.

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

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

The description clearly implies when to use the tool: when an agent needs to evaluate whether an edge is fresh or decaying, noting 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternative tools or provide exclusion criteria, but the use case is well enough described that a user would know this is for tracking edge history, not for current edge lists.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns that partial basket fills create unhedged directional risk. No contradiction with annotations; the description enriches the safety profile with operational details.

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

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

The description is dense and lengthy, but every sentence earns its place; it front-loads the purpose, then structures modes, parameters, and outputs logically. Slightly less concise than ideal, but appropriate given the tool's complexity and the amount of unique information conveyed.

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

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

No output schema exists, and the description compensates by listing all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers usage thresholds and risk context, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3; however the description adds meaning beyond the schema by clarifying that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode, plus the auto side default from partition sum. This goes beyond the schema descriptions, which are more terse.

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-plus-resource statement ('Realizable-vs-theoretical edge check against live CLOB order-book depth') that clearly identifies what the tool does. It also distinguishes itself from sibling tools by explicitly naming the use cases: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert an arb into an unhedged directional position), providing clear context and rationale.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds rich behavioral context: compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also warns that most pre-mapped topics are not tradeable, which is valuable for an agent deciding whether to rely on the result.

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 front-loaded, starting with the core purpose and then covering modes, response fields, and safety warnings. Each sentence earns its place, though it is long and could potentially be tightened without losing information.

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

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

Given the complexity of cross-venue comparison and no output schema, the description thoroughly covers response fields (spread[], top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), safety conditions, and limitations. It is complete enough for an agent to decide when and how to invoke the 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%, and the description goes beyond it by explaining the two-mode structure, listing all topic shortcuts, and describing how explicit parameters override topic-mapped sides. This gives the agent a clear mental model of parameter relationships.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with two explicit modes (topic shortcuts and explicit tickers). This specific verb+resource+scope distinguishes it from sibling tools like polymarket_arbitrage and 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?

The description provides clear context on when to use topic shortcuts vs explicit tickers, and includes important caveats about pre-mapped topics often returning compatibility_warning and not being tradeable. It does not explicitly name alternatives, but the guidance on limitations and safety checks is strong.

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

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

Annotations already establish the read-only, safe nature, so the description's added value is the return format ('Returns attribute rows (and geometry)') and the sampling hint. It doesn't contradict annotations and adds useful behavioral context, though it could disclose default result size or pagination behavior (though schema covers defaults).

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

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

The description is two sentences, with the main verb and resource up front. It efficiently summarizes the parameters and ends with a practical tip, with zero 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 read-only query tool with a schema covering all parameters, the description covers the essential context: source of URL, query capabilities, return type, and a usage tip. It could explicitly mention default limit max and pagination, but these are in the schema, so the description is adequate for the tool's complexity.

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

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

Schema descriptions cover 100% of parameters with concrete examples and defaults, so the description's role is minimal. It restates parameter names and notes SQL-like 'where' and comma-separated 'out_fields', which adds a little conceptual framing but little new meaning beyond the schema.

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

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

The description clearly identifies the tool's function: querying ArcGIS Feature/Map Service layers via URL. It distinguishes itself by referencing search_datasets as the source, separating it from sibling tools like layer_info or search_within. The listed parameters further clarify the operation scope.

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

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

The description implies a workflow: first use search_datasets to find a layer URL, then query with this tool. It also provides a practical sampling technique (where="1=1" + out_fields="*"). However, it does not explicitly state when to use this versus alternatives like search_within or layer_info, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable context beyond annotations, such as scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the paired relationship with remember/forget, which enriches behavioral understanding without contradicting annotations.

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

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

The description is three sentences long, each providing distinct value: primary action, usage examples, and scoping/related tools. It is front-loaded with the main verb and resource, and contains no filler or redundant content.

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

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

Given the tool has only one optional parameter, no output schema, and strong annotations, the description fully explains the tool's purpose, usage, examples, and scope. It is complete for an agent to select and invoke correctly, including the distinction between retrieving a single value and listing all keys.

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 fully documents the 'key' parameter. The description reinforces the meaning by saying 'omit the key argument' and provides example use cases, but it does not add new semantic details beyond the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool retrieves a previously saved value by key or lists all saved keys, using the specific verb 'Retrieve' and naming the resource (saved values). It explicitly distinguishes from siblings 'remember' (save) and 'forget' (delete), making the purpose unambiguous.

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

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

The description provides clear when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It implies the alternative of re-deriving, but does not explicitly state when to avoid using this tool or name an alternative for saving, which would earn a 5.

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

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

The description adds rich detail (mark_read state change, feed content, external endpoint), but it directly contradicts the readOnlyHint and idempotentHint annotations. Setting mark_read:true flags events read and changes future results, which is a side effect and violates the read-only/idempotent hints. Therefore a score of 1 is required.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence adds useful information. It is slightly dense but not redundant; the external endpoint note is relevant for scripted access. It balances detail with brevity well.

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

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

With no output schema, the description compensates by naming returned fields (source, citation_uri, raw payload), explaining filtering and read-state semantics, and offering an alternative access path. It is complete enough for a polling tool, though it does not enumerate all response fields such as timestamps 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?

Input schema already covers 100% of parameters, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ("sec_8k"), clarifying the 'since' parameter as an ISO timestamp, and explaining that mark_read:true causes the next call to return only newer events—semantics not present 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 a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly states what is returned (recent alerts with source, citation_uri, raw payload) and distinguishes it from sibling tools like list_subscriptions (which lists subscriptions, not events).

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

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

It conveys clear usage context: filtering by type/since, using mark_read for read tracking, and notes 'Polls work fine' plus an alternative REST endpoint for scripts/dashboards. It does not explicitly name exclusions or compare to sibling tools, but the polling guidance and endpoint reference give practical when-to-use 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?

The description discloses important runtime behavior beyond annotations: it fans out to multiple sources in parallel, uses GDELT with GNews as fallback on rate limits/5xx, and soft-fails for USPTO due to the PatentsView API sunset. It also explains the return shape (changes[], total_changes, citation URIs) which is not in the output schema.

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

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

The description is dense and comprehensive, but it is a single long paragraph with many embedded clauses. Each piece adds value, yet breaking it into shorter sentences or bullets would improve scannability without losing information.

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

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

With no output schema, the description fully compensates by specifying the structured return format and grouping semantics. It also covers source fallback behavior, soft-fail conditions, date formats, and the distinction from entity_profile, making the tool's capabilities and limitations clear.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds practical guidance such as recommending '30d' or '1m' for typical monitoring and showing example values for both ticker and CIK formats. This goes beyond what the schema spells out.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, listing exact resources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts it with entity_profile. The verb is implicit in 'what's new' but the resource and scope are unmistakable.

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

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

It provides explicit user intents ('What's new with X', 'updates on Acme') and explicitly directs users to entity_profile for static profiles. This gives clear when-to-use and when-not-to-use guidance, distinguishing it from a key sibling.

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

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

Annotations cover idempotency and non-destructive nature, but the description adds behavioral context: storage as a key-value pair scoped by identifier, and the 24-hour retention for anonymous sessions versus persistent memory for authenticated users. This goes beyond the annotations by explaining session-specific behavior.

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

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

Three sentences: purpose, usage, and persistence/sibling pairing. Each sentence adds value and there is no redundant content.

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

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

The description covers the tool's purpose, usage context, storage model, and companion tools. It lacks explicit overwrite semantics or error conditions, but for a simple 2-parameter tool the description is quite 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?

Both parameters have 100% schema description coverage with examples for key ('subject_property') and value ('any text'). The description only reinforces the key-value pair concept without adding new semantics, which is appropriate since the schema already handles it.

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

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

The description uses the specific verb 'Save' and identifies the resource as 'data the agent will need to reuse later', clearly stating cross-session persistence. It distinguishes itself from siblings by explicitly naming 'recall' and 'forget' as paired 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?

It provides explicit guidance: 'Use when you discover something worth carrying forward' and lists concrete examples like 'a resolved ticker, a target address'. It also tells the agent when not to use it by pointing to alternatives ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint all true and destructiveHint false. The description adds significant behavioral context beyond these annotations: it explains the internal cascading lookup behavior, graceful degradation of LEI/FIGI enrichment, and how unresolved identifiers are reported explicitly. These are valuable behavioral traits not captured by annotations alone.

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

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

The description is moderately sized but front-loads examples effectively. Every sentence adds value, though the density of information around identifier sources and cascading behavior could be slightly streamlined without losing clarity.

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

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

Given the tool's complexity (multi-source resolution, multiple entity types, enrichment dependencies) and the absence of an output schema, the description is nearly complete. It covers all major scenarios except response format details (though the example output structures shown in the description help) and rate limits/error handling for failures.

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 well-documented in the schema. However, the description significantly adds meaning beyond the schema by providing concrete examples of accepted values (e.g., 'AAPL', '0000320193', 'CH0038863350', 'ozempic') and explaining the cross-source identity resolution logic that doesn't fit in parameter descriptions.

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

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

The description is exceptionally clear, specifying the verb 'resolve' and the resource 'entity', and lists multiple example user queries to disambiguate intent. It also explicitly distinguishes this tool from siblings by stating it replaces 2-3 manual lookups, making its purpose unmistakable.

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

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

The description explicitly states when to use this tool ('Use FIRST whenever you have a name but need an ID') and provides detailed coverage of what input types it accepts for each entity type. It also explains edge cases like graceful degradation when external APIs are unavailable and behavior for unresolved identifiers.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds process detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the safety hints and clarifies what the agent should expect.

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

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

Two sentences with no redundancy. It front-loads the primary action, includes a concrete example, and ends with the output format. Every clause contributes useful information.

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

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

With no output schema, the description compensates by specifying the ranked list and its fields (score, confidence, signal density). It also positions the tool in a competitive audit context and mentions the relationship to ai_visibility_check. Minor gaps like model-specific behavior are handled by the schema.

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

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

The input schema provides 100% parameter coverage with detailed descriptions for all four parameters. The description adds little semantic value beyond the schema: 'your brand + N competitors' restates the schema's 'first entry treated as subject' rule. Thus 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?

Description states a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes from sibling ai_visibility_check by explicitly referencing it as the underlying probe and by adding ranking/comparison semantics. The competitive-audit example further clarifies its unique role.

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

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

Provides a clear use case: competitive AI-marketing audits, with an illustrative question. It implies this tool is for multi-entity comparisons (your brand + competitors), distinguishing it from a single-entity check. However, it doesn't explicitly mention alternatives or when not to use it, 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?

Beyond the readOnly/idempotent annotations, the description discloses composite behavior across services, the exact summary block fields returned, partial failure degradation, and a 5-30s timeout for first-time bundlephobia measurements. It also notes that 'sources_failed' will list timed-out sources, adding valuable runtime 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 front-loaded with the core purpose ('Composite... check in ONE call'), followed by usage, return values, limitations, and failure behavior. Each sentence contributes substantive information, though the length is at the upper bound of what is 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?

Given the lack of an output schema, the description compensates by listing all summary block fields, per-advisory detail, links, and alternative versions. It also covers ecosystem scope, partial failures, and timeout behavior, making the tool's full behavior predictable to an agent.

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

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

Schema description coverage is 100% and both parameters are well-documented in the schema (package name and optional version). The description adds no parameter-specific syntax or examples beyond the schema, so it meets the baseline but does not elevate it.

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

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

The description clearly specifies the tool's purpose: a composite check for deciding whether to add an npm package, fanning out across deps.dev and bundlephobia. It includes concrete output fields (license, advisories, bundle size) and distinguishes itself from sibling tools by stating 'NPM ecosystem only in v1' and naming the alternative for other ecosystems.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also tells the agent what to do for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), providing a clear alternative.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral context beyond annotations by specifying the output structure (name, summary, record_count, owner/org, and Feature Service url) and that the url is meant for query_layer/layer_info. This adds value without contradicting the annotations.

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

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

The description is two sentences long, front-loaded with the core action and scope, then quickly covers the return format and downstream usage. Every word contributes information; no filler or redundancy.

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

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

Given the tool has no output schema, the description compensates by explicitly listing return fields (name, summary, record_count, owner/org, url) and clarifying the input scope (City of Kingston GIS). It also connects to sibling tools. Minor gaps like parameter interaction or edge cases are covered by the detailed schema and annotations, so a 4 is fitting.

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

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

Schema description coverage is 100%, with each parameter (limit, query, org_id) already fully described in the input schema. The tool description does not add additional meaning or context to the parameters themselves; it only mentions the returned url. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Search City of Kingston GIS open geospatial datasets... by keyword.' It also distinguishes itself from sibling tools like query_layer and layer_info by positioning itself as the discovery/search step, and lists the return fields, making its purpose unambiguous.

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

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

The description gives clear usage context: searching for datasets and then passing the returned Feature Service 'url' to query_layer or layer_info. It implies when to use this tool (to find datasets) versus when to use the query tools (to work with a specific dataset). However, it lacks explicit when-not or alternative exclusions, 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses substantial behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and caps input at 200K chars with truncation flagged. This exceeds the annotation coverage and provides important execution 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 long but information-dense, with each sentence serving a distinct purpose: stating the core function, providing use-case context, and explaining technical mechanisms and limits. It is front-loaded with the essential purpose 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?

Given there is no output schema, the description adequately explains return values (top-N passages with offsets and similarity scores). It also covers edge behavior (truncation flag), pairing with a sibling tool, and the practical benefit (context saving, quote verification). This is complete for a search tool of this complexity.

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

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

The input schema already has 100% coverage with descriptive text for all three parameters, including examples for the query. The description reinforces the semantics (e.g., 'text you already pulled') but adds no new parameter-level details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('semantic search') and resource ('a fetched record'), and provides concrete examples (SEC 10-K body, article). It distinguishes itself from siblings by emphasizing it operates on user-provided text, contrasting with tools that search external corpora or provide grounded answers.

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

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

The description gives explicit guidance on when to use the tool: 'Use when the record is too big to cram into the prompt.' It also specifies the workflow with a sibling tool ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'), clearly indicating when to choose this tool over 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?

Adds substantial behavioral context beyond annotations: OAuth account requirement, persistent feed always on, SMS delivery cap (10/day), phone verification prerequisite, and webhook auto-disable after consecutive failures. 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 compact and front-loaded with the primary action, then organizes supported types and delivery channels with clear delimiters. Every sentence contributes unique information; no filler.

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

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

For a tool with three parameters, five subscription types, and three delivery channels, this description covers return value, prerequisites, and operational nuances. The schema fills in further detail, but the description alone is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and already includes type-specific parameter examples. The description adds value by explaining the semantics of item codes (e.g., items:['5.02'] = officer change) and the always-on feed behavior, but largely complements rather than replaces schema details.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states what the tool does, returns the subscription id, and distinguishes from siblings like list_subscriptions (list) and unsubscribe (remove).

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

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

Provides clear context: account requirement, supported subscription types with concrete examples, and delivery channel options including feed retrieval via recent_alerts. It does not explicitly exclude alternatives but the purpose is unambiguous given sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior; the description adds that results are drawn from the live catalog and are category-bucketed. This is consistent and adds context about the return contents, though it does not disclose any additional side effects or limitations.

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

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

The description is long but front-loaded with the user-facing question and a list of related queries, then explains behavior and usage. Each sentence contributes unique information, and the structure is effective, though slightly verbose for a simple tool.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how to invoke it (no args or `topic`). For a suggestion tool, this provides sufficient context for an agent to use it correctly.

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

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

The input schema already provides 100% coverage with a detailed description of the optional `topic` parameter, listing all allowed values and the behavior when omitted. The description merely repeats these examples without adding new semantic meaning, 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 clearly states it is an onboarding entry point that returns category-bucketed example questions, including the exact tool and argument shape for each. It distinguishes itself from sibling tools by framing 'Use this FIRST' and referencing meta-tools, providing a specific verb and resource.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a `topic` versus omit it. It also names the meta-tools (ask_pipeworx, entity_profile, compare_entities) as alternatives to learn, giving clear when-to-use and what-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?

The description discloses key behavioral traits beyond the annotations: ownership enforcement and soft-delete behavior ('row is deactivated, not deleted'). This adds significant context about side effects and data retention that annotations alone do not convey. No contradiction with annotations.

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

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

The description is three sentences with no filler. It front-loads the primary action, then adds ownership and soft-delete details, each sentence earning its place. It is 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 one-parameter mutation tool, the description fully covers the tool's purpose, constraints, and side effects. It explains what happens to the underlying data and where historical events remain accessible. No output schema is present, so return-value details are not expected. The description is sufficiently complete.

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

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

The input schema already provides 100% description coverage for the 'id' parameter, including its type and origin ('returned by subscribe'). The description simply refers to 'by id' without adding new parameter-level details, so the high schema coverage keeps this at 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 the action ('Cancel a subscription by id') with a specific verb and resource. It also distinguishes this tool from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and the ownership constraint adds further specificity.

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

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

The description provides clear context on when to use the tool: to cancel your own subscriptions. It also indirectly references an alternative for viewing historical events ('recent_alerts'), but does not explicitly state when not to use this tool or compare it against other siblings like 'subscribe' or 'list_subscriptions'.

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 readOnly/idempotent hints, but the description adds critical behavioral details beyond that: 'could_not_verify means the check did not happen... and must not be shown as one,' and 'unsupported means we looked and cover no source for it.' It also explains the routing logic and return values, giving the agent essential context for interpreting results correctly.

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

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

The description is dense but every sentence earns its place: it opens with representative natural-language triggers, provides usage guidance, explains the routing logic, lists return verdicts, and highlights important caveats. It is front-loaded with a usage directive and clearly structured. No fluff or redundancy.

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

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

Despite having no output schema, the description fully explains the return verdicts ('confirmed / approximately_correct / refuted / inconclusive / unsupported / could_not_verify'), the error semantics for could_not_verify, and the difference between unsupported and refuted. It also covers the two processing pipelines, making it complete for a complex verification tool.

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

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

The input schema already provides 100% coverage of both parameters with detailed descriptions, so the baseline is 3. The description adds no new parameter-specific semantics beyond the schema; it mentions tolerance_pct implicitly ('exact percent-delta math', 'tolerance implied by the claim wording') but the schema already explains tolerance_pct fully. No value beyond schema is added.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It uses a specific verb ('verify', 'fact check') and resource ('claim'), and distinguishes itself from siblings by describing its unique claim-verification function and fast paths. It also differentiates between financial and non-financial claims, adding specificity.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also notes it 'Replaces 4–6 sequential calls.' However, it does not explicitly name alternatives or state when NOT to use, though it implies that other tools handle non-claim queries. Given the clear context and implied exclusion, 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.