Arcgis Montana

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the description's value lies in disclosing the free default model, the direct-billing implication of passing a key, and the return structure. This adds economic and output context beyond the annotations. No contradiction.

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

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

The four-sentence description is tightly packed, starting with the core function, then model options, return format, and use cases. No filler; every sentence adds distinct 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?

The description covers the lack of an output schema by specifying per-model and combined response shapes, and outlines the tool's use cases. It could add more detail on 'signals' or error behavior, but it 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%, providing a baseline of 3. The description goes beyond by clarifying the default model, the direct payment implication for Anthropic, and the fact that _apiKey is passed straight through. This is meaningful additional context, especially around the models parameter.

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

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

The description uses a specific verb ('Probe'), defines the resource (one or more LLMs), the subject (business/brand/product/topic), and the output (visibility score 0-100). It clearly distinguishes itself from siblings by focusing on LLM awareness scoring rather than generic Q&A or research.

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

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

The description provides clear usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs BYO-key model choice. However, it does not explicitly mention 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?

Annotations already supply safety (readOnly, idempotent, non-destructive), and the description adds meaningful behavioral context: routing to thousands of sources, auto-filling arguments, returning stable pipeworx:// citation URIs, and being a fast single call. No contradiction with annotations.

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

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

The description is long but front-loaded with the 'PREFER OVER WEB SEARCH' call-to-action and organized into clear directive segments. Each sentence contributes usage guidance or examples, though it could be tightened without losing impact.

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

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

Given no output schema, the description sufficiently explains return format (structured answer with citation URIs) and covers domains, examples, and operational notes (all tiers, fast). It lacks only explicit limitations or failure modes, but overall is quite complete for a tool with this scope.

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 aliases well-documented, so the baseline is 3. The description adds value by providing real-world example questions and explaining that the tool fills arguments automatically, which enriches understanding of what the 'question' parameter should contain.

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

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

The description explicitly states the tool's function: routing questions to one of 5,529 tools across 1,455 verified sources and returning structured answers with citations. It uses specific verbs like 'routes' and 'returns', and clearly distinguishes itself from siblings by mentioning ask_pipeworx_grounded and deep_research as alternatives.

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?

Extensive when-to-use guidance is provided: 'PREFER OVER WEB SEARCH' with a list of domains, trigger phrases like 'what is' and 'look up', and concrete examples. It explicitly says 'START HERE for most questions' and contrasts with step-up alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part questions), including exclusions for breaking-news.

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

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

Beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description discloses it is an experimental router with candidate routing improvements enabled live only when under test, and currently matches ask_pipeworx exactly. It also mentions results are compared to stable router for merge decisions, adding valuable behavioral context.

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

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

The description is structured with a clear opening identifying it as a beta, followed by explaining the identical nature, current state, usage guidance, and experimental purpose. It is somewhat long but each sentence earns its place, and the key decision-making info is front-loaded.

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

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

The description fully covers what the tool does, its relationship to ask_pipeworx, its experimental nature, current active state, and how to use it. It explicitly states the response shape is identical to ask_pipeworx, covering return behavior without needing an output schema.

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

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

Schema coverage is 100% and the input schema thoroughly documents all six parameters, including aliases. The description does not add additional parameter details, but this is not necessary since the schema is self-sufficient. Baseline of 3 applies.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by highlighting its role as an experimental edge. The verb 'ask' and resource 'Pipeworx Beta' are specific.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison against the stable router and clarifies it is a full working router, not a fallback, which helps the agent decide when to select it over ask_pipeworx.

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 readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial behavioral context: it never invents facts, returns explicit refusal reasons on failure, provides an evidence verbatim quote, and notes the extra LLM call cost. This goes well beyond the structured hints.

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

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

The description is dense but well-structured, front-loading the core purpose before detailing return shapes and refusal reasons. Every sentence contributes necessary behavioral or usage information, though it is longer than strictly minimal.

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

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

With no output schema, the description fully specifies the success payload (answer, evidence, confidence, source, fetched_at, refusal_reason) and all refusal reasons. It also covers when to use, alternatives, and cost implications, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% and the description adds no new parameter-level meaning beyond restating that all fields are aliases for a natural-language question. The baseline of 3 applies because the schema fully documents the single logical parameter.

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

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

The description identifies a specific verb+resource+mode: a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and refusal behavior, 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?

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on' and 'must not invent facts') and provides a direct alternative: 'prefer ask_pipeworx for casual lookups.' It also names the cost tradeoff (one extra LLM call), giving clear decision criteria.

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

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

Beyond annotations (readOnly=true, openWorld, idempotent), the description discloses fan-out parallelism, resolver confidence gating (low_confidence_match short-circuit), closed-market status handling, wide-spread tradeability flag, news fallback behavior (_fallback_attempted), and cancellation-rule parsing. Rich context with no contradiction to annotations.

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

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

Long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). Each section contains specific operational detail. A few sections (resolver and safety) overlap slightly, but the density 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 thoroughly by documenting response shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extraction, news fields, and edge-case statuses. It covers safety, illiquid markets, and cancellation risk, making it complete for a complex tool.

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

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

Schema already covers all 3 parameters with descriptions. The description adds value with concrete input examples (slug, URL, question text), explains classification-driven fan-out, and details include_raw's behavior (payload sizes, recommended false). This exceeds the schema baseline.

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

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

The description opens with a specific verb ('Research') and resource ('a Polymarket bet') plus scope ('pulling the relevant Pipeworx data for it in one call'). It clearly distinguishes the tool from siblings like ask_pipeworx and polymarket_edges by targeting bet-specific research with fan-out.

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 'Use for' phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') provide clear context. It also warns when to check cancellation rules before sizing event bets. However, it does not explicitly name when-not-to-use or alternative tools, so it stops short of 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?

Even though annotations already declare read-only/idempotent behavior, the description adds substantial behavioral detail: company type pulls 10-K revenue/net income/cash/debt from SEC EDGAR/XBRL with off-calendar fiscal years handled correctly, drug type pulls FAERS/FDA/trial counts, results are sorted by primary metric, and paired data includes citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases and the core instruction in the first two sentences, and later sentences are information-dense. It is slightly long but every sentence contributes useful behavior or context, so it remains well-structured.

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

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

With no output schema, the description covers the key return characteristics (paired data and pipeworx:// citation URIs) and result ordering. It also covers type-specific behavior, fiscal-year handling, and input constraints, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters, and the description supplements the enum by explaining exactly what each type ('company' vs 'drug') retrieves. It also clarifies the values array sizing (2–5) with examples, adding real semantic value beyond the schema.

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

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

The description clearly identifies a compare verb with a bounded resource (2–5 companies or drugs) and provides concrete trigger phrases. It distinguishes itself from single-entity lookup tools by emphasizing one parallel call and 'ALWAYS PREFER over sequential single-pack lookups.'

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

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

Explicit usage guidance is given via query patterns ('X vs Y', 'which is bigger...') and a direct instruction to prefer this tool over sequential lookups when comparing entities. It also names the count replacement ('Replaces 8–15 sequential lookups'), giving clear context for when to choose it.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral traits: account/paid-tier requirements, expected latency (15-60s, up to ~90s), parallel tool routing, explicit gaps[] never invented, contradictions[], semantic excerpting, and citation_uri only when fetchable. This far exceeds the annotation baseline and fully informs the agent of operational nuances.

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 dense and front-loaded with the critical account requirement and primary alternative. Every sentence contributes contextual value (limitations, timing, output contents, differentiating from siblings). It is not padded, though a shorter version could exist; 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?

Given the tool's complexity, no output schema, and rich annotations, the description is exceptionally complete. It explains the return format (findings packet with evidence, confidence, source, gaps, contradictions), the use of hop/citation_uri, latency, account tiers, and when to prefer alternatives. This leaves no critical gap for an agent deciding to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining the semantic differences among depth options ('quick=3... standard=5... thorough=8'), the paid requirement for thorough, and the gap-recovery/contradictions behavior per depth. It also clarifies that the question should be broad/multi-part, which is not explicit in the schema.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call. It differentiates from siblings by explicitly noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups or live news, making its scope and resource 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides a fallback alternative: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas including curated examples, and states 'no second schema lookup needed.' This is actionable 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 three sentences: purpose, usage context, and return behavior. It is front-loaded with the core 'Find tools by describing the data or task' and every sentence carries distinct, essential information. The domain list is compact but informative.

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

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

Given no output schema, the description thoroughly explains what the agent will receive (top-N tools with full schemas and examples) and how to use the tool first. It fully covers purpose, usage, output, and placement relative to other tools, making it 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 description coverage is 100%, with detailed descriptions for query, limit, and alias parameters. The description does not add meaningful semantics beyond the schema—it reinforces that query is a natural language description but does not introduce new details. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It lists specific domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes itself from sibling search/research tools by positioning as a meta-tool that returns tool schemas.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides concrete when-to-use context and implies when not to use (when you already know the specific tool).

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds valuable context: it reveals parallel fan-out across multiple sources, the USPTO PatentsView API sunset soft-fail, GDELT→GNews fallback chain, and the exact output structure (e.g., fundamentals sorted by period_end DESC, URIs for filings). This goes beyond annotations without contradicting them.

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

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

The description is dense but well-structured: it starts with trigger phrases, states the core behavior, provides a strong usage preference, lists return fields with concrete examples, and closes with parameter constraints. Every sentence carries useful 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?

Without an output schema, the description carries the full burden of explaining return values, and it does so thoroughly: enumerates all return fields, their sources, limits (up to 5), and formatting (sorted period_end DESC, pipeworx URIs). It also covers error-prone input conditions (name not supported) and external API status (USPTO sunset). For a complex tool with no output schema, this is exceptional.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value here by explicitly naming examples ('AAPL', '0000320193') and reiterating the constraint that names are not supported (matching the schema). It does not add syntax details beyond examples, but it reinforces the critical format requirement.

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 highly specific: it names the exact verb ('profile', 'brief me') and resource ('US public company') and lists concrete outputs (cik, recent_filings, fundamentals, patents, news, LEI). It also distinguishes from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity as a prerequisite 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?

Provides explicit when-to-use: 'when the user asks for a holistic view' of a company. It gives clear alternatives: names are not supported; use resolve_entity first. It also warns about the USPTO API sunset and soft-fail behavior. This is excellent guidance for an agent deciding between this and similar research 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 destructiveHint=true and idempotentHint=true, so the agent knows the operation is destructive and repeatable. The description adds the 'clear sensitive data' use case but does not detail further behavioral traits, so transparency is adequate but not enriched beyond annotations.

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

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

Three short sentences, front-loaded with the action. No filler or redundant information.

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

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

For a simple one-parameter delete tool, the description covers purpose, usage scenarios, and relationships. It doesn't specify idempotent behavior or error handling, but annotations fill that gap, making it mostly complete.

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

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

The schema covers 100% of parameters with a clear description ('Memory key to delete'). The description only echoes 'by key' and does not add 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 opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly states the tool's function and distinguishes it from sibling tools like remember and recall.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also advises pairing with remember and recall, giving contextual guidance.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context: it fetches the page, extracts key content, and emits a single text blob for site-root placement. This goes beyond annotations by explaining the internal workflow and output format.

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

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

Three sentences, front-loaded with the primary action. Every sentence earns its place: what it does, how it works, and when to use it. No filler or repetition.

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

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

Despite lacking an output schema, the description explains the output format ('standard llms.txt markdown', 'single text blob ready to drop at site-root/llms.txt'). It covers input, process, output, and use cases, making it complete for a tool of this complexity with rich annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'key links' which relates to max_links, but it doesn't add much beyond the schema's own parameter descriptions. The schema already documents url and max_links adequately.

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

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

The description uses a specific verb ('Generate') and names the exact resource (llms.txt file for any URL), clearly distinguishing it from sibling tools. It states what the tool does: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This is a specific, non-tautological purpose statement.

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

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

The description provides clear use cases: indexing a client's site, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough to 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety profile is clear. The description adds useful behavioral detail about what the tool returns (fields, geometry type, record count, capabilities), providing value beyond annotations.

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

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

The description is a single, well-structured sentence. It front-loads the primary action and lists the returned data components without unnecessary words.

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

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

The tool is simple (one parameter) and annotations cover safety. The description lists the expected return components, which is important given no output schema. It does not elaborate on potential errors or 'capabilities' meaning, but it is sufficiently complete for a straightforward schema-inspection 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% for the single url parameter, with a clear example and type description. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves an ArcGIS Feature/Map Service layer's schema via URL, listing specific returned components (fields, geometry type, record count, capabilities). This is specific and distinguishes it from sibling tools like query_layer.

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

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

The description implies when to use the tool (when schema information is needed for a layer) but does not explicitly state when not to use it or mention alternatives. The sibling tool names suggest related functionality, but the description lacks explicit 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 destructiveHint=false, so safety is covered. The description adds useful context beyond that: it specifies the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope ('active subscriptions'). This enriches the agent's understanding of what the tool returns 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, each earning its place: purpose+scope, return fields, and usage guidance. It is front-loaded with the verb-resource pair, structured logically, and contains 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 simple list tool with one optional parameter, no enums, and no output schema, the description is complete. It explicitly lists the return fields, which compensates for the missing output schema, and provides usage context. The annotations cover safety, so no further behavioral disclosure is needed.

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

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

Schema description coverage is 100% with the single parameter include_inactive fully documented. The description does not add additional parameter syntax or format details beyond the schema, but it reinforces the default behavior by saying 'active subscriptions'. This meets the baseline for schema-covered params.

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: to list the caller's active subscriptions. It uses a specific verb ('List') and resource ('subscriptions'), and specifies the scope ('caller's active'), which distinguishes it from potential siblings like subscribe/unsubscribe. It also enumerates the exact fields returned, leaving no ambiguity.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly ties to the subscribe/unsubscribe workflow, making it clear this is a read-only precursor to mutations.

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

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

With all annotations set to false, the description carries the full burden. It discloses the claim_token flow (filing without an account returns a token; passing it back later reads status), rate limiting (5 per identifier per day), quota impact (free, doesn't count), and the team's daily digest cycle. These are meaningful behavioral traits beyond what annotations convey.

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

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

The description is appropriately sized for the tool's complexity and stays front-loaded: it opens with the core purpose, then flows into use cases, exclusions, mechanics, and operational details. Every sentence carries useful information—none are filler. The rate limit and quota note are concise and relevant.

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

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

Despite having no output schema, the description explains what a filing returns (a claim_token) and how to later retrieve status/changes. It covers the tool's key behavioral edges (scope limitation to Pipeworx, rate limits, quota) and complements the rich input schema. For a feedback tool of this complexity, the description is fully complete.

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

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

Schema coverage is 100% with strong individual descriptions, so the baseline is 3. The description adds extra value by explaining the claim_token round-trip pattern (e.g., 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving content guidance for the message field (don't paste end-user prompt, be specific). While the schema already covers basics, this supplementary context helps the agent invoke parameters correctly.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from siblings like ask_pipeworx or discover_tools, and explicitly enumerates the categories (bug, feature, data_gap, praise).

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

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

The description provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well'). It also gives a strong when-not-to-use rule: do not report tools from other MCP servers, and tells the user to file those elsewhere. Additional instructions (describe in terms of Pipeworx tools, don't paste user prompt) further clarify usage.

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

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

Annotations already indicate readOnly/idempotent/non-destructive. The description adds meaningful context: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window,' which informs the agent about data provenance, privacy, and freshness beyond the structured hints.

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

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

The description is well-structured, front-loaded with the core capability, and uses a compact bulleted list for use cases. Every sentence adds value; it is informative without being verbose.

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 read-only tool with one optional parameter and no output schema, the description thoroughly covers what it returns, use cases, data source, privacy, and caching. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single window parameter, including an enum and description. The tool description only restates the window options without adding further semantics, 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?

Description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' 'What other AI agents are calling on Pipeworx right now' provides a specific, vivid resource and distinguishes it from siblings like discover_tools or search_datasets by focusing on trending call volume.

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?

'Useful for:' explicitly lists three distinct use cases, giving clear context for when to use the tool. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context beyond those: it explains partition_check mechanics, the >3pp deviation threshold, placeholders filtering, fill check against live CLOB depth at 1000 shares/leg, and the meaning of realizable_edge_pp ≤ 0. It also discloses that skipped_low_similarity surfaces rejected pair counts, enhancing transparency.

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

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

The description is long but densely packed with unique, non-redundant information. It is front-loaded with a crisp definition, then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid scanning. A minor deduction because the length may be overwhelming, but all content is valuable.

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

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

Given the tool's complexity (two modes, filters, fill check) and the absence of an output schema, the description thoroughly covers return shapes (opportunities[], partition_check details), edge cases (placeholder thresholds, low similarity), and practical trading guidance. It provides enough context for correct invocation and interpretation.

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?

While schema coverage is 100%, the description adds significant meaning for both parameters: event includes concrete slug examples and mentions full URLs are accepted; topic explains it as a seed question and gives examples. It details the behaviors triggered by each mode, which the schema's brief descriptions do not convey.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by naming its unique approach and modes (trending_scan, event, topic).

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass event... or topic.' It recommends event for a specific market, topic for cross-event scans, and explicitly names an alternative for custom sizing: 'use polymarket_fill_risk.' It also includes an exclusion/condition: 'realizable_edge_pp ≤ 0 means... do not trade it.'

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context beyond that: response segment structure, caching at KV level, the placeholder-slug filter, per-sport bias corrections, the 24h-move warning, and diagnostics for why segments might be empty. It also explains the fed_candidates exclusion and unreliable signals.

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

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

The description is very long, dense, and uses all-caps segment names and bullets. It is front-loaded with the core purpose, but subsequent details (e.g., model family explanations, response structure) are verbose and could be trimmed. However, given the complexity and absence of an output schema, the length is partly justified.

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

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

With no output schema, the description must explain return values and it does so thoroughly, listing top-level fields (by_segment, fed_candidates, _diagnostics), the model families, and edge metrics. It also explains caching, knob effects, and why segments may be empty, providing a complete picture for an agent to correctly invoke and interpret 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 description coverage is 100% and each parameter already has a rich description (e.g., slippage_pp explains bid/ask context, min_partition_leg_kelly explains per-leg behavior). The description groups parameters into 'tradeable-edge knobs' and explains their interplay, but this is mostly redundant with the schema. It adds marginal value beyond what the schema already provides.

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

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

The description uses a specific verb ('Scan') and resource ('top Polymarket markets') with a clear outcome ('return opportunities where Pipeworx data disagrees with market price'). It also states the intended use case ('what should I bet on today'), distinguishing it from sibling tools like polymarket_arbitrage or 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?

Clear context is given for when to use the tool, including its purpose to avoid paging hundreds of markets and its knob settings for filtering. It also provides a caution about fed bets being unreliable. However, it does not explicitly name alternative tools or say 'use instead of X', so it misses the top bar for explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavioral context: snapshot writing on cache-miss, 60-day TTL, daily closes vs. intraday, and detailed explanation of response fields like trend and decay_pp_per_day. 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 dense yet well-structured: purpose, args, response details, and limits are clearly separated. Every sentence adds value—no filler or redundant repetition of annotations. It remains readable despite its length.

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

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

Despite having no output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and their fields. It covers limitations, data freshness, and interpretive guidance (median lifespan as competition clock). This makes the tool fully understandable without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context: how 'days' maps to snapshot history, how 'window' selects snapshot family, and how these parameters interact with cache-miss gaps and TTL. It goes beyond the schema's default/clamp information.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It uses specific terms like 'tracked[]', 'expired[]', and 'snapshot_dates[]' and contrasts with fresh vs. old edges, distinguishing it from the sibling polymarket_edges tool.

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

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

The description implies when to use this tool (to assess how long an edge has existed and whether it's shrinking) and contrasts it with current-edge data. It doesn't explicitly name alternatives, but the context makes the distinction clear, and it includes limitations like snapshot TTL and cache-miss gaps.

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

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

Annotations already signal readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavioral context: live order-book walking, partial-fill conversion to unhedged directional risk, forced_directional_risk naming, and verdict states (clean|degraded|cannot_fill). No contradiction with annotations.

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

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

The description is a single dense run-on, but every clause contributes critical information and it is front-loaded with the core purpose and mode requirements. It would benefit from paragraph breaks or bullet formatting, but it wastes no 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?

With no output schema, the description fully enumerates return fields for both modes, explains size_usd interpretation per mode, identifies risk indicators (thin_legs, forced_directional_risk), and justifies the tool's purpose. This is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% and already documents each parameter, but the description adds the critical constraint that exactly one of `market` or `event` is required, which the schema does not convey (required params = 0). It also reinforces mode-dependent size_usd semantics and default side behavior, going beyond the structured 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb and resource that clearly distinguishes it from theoretical edge tools like polymarket_edges and polymarket_arbitrage. It also names concrete outputs (verdict, slippage_pp, capture_ratio) and explains both single-market and basket modes.

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

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

It explicitly states mode selection requirements ('REQUIRES one of `market` or `event`'), provides mode-specific usage details, and directly tells the agent when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. This clear when-to-use guidance differentiates it from 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by thoroughly explaining the tool's behavior: how compatibility_warning works with two distinct cases, what temporal_alignment means, and what skipped_cross_type/subtype counters indicate. It even acknowledges limitations, such as most topics returning warnings, which is excellent transparency.

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

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

The description is long but well-organized with bold section labels (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose and each section adds necessary information for a complex tool. It could be slightly tightened, but the density is justified by the tool's behavior.

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

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

There is no output schema, so the description carries the full burden of explaining the return shape and edge cases. It clearly explains the response format (leg-by-leg prices, matched spread), the meaning of compatibility_warning, temporal_alignment, and the skip counters. Given the tool's complexity, the description is exceptionally complete, leaving no major gaps.

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

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

The schema already documents all three parameters with a 100% coverage, so the baseline is 3. The description adds value by framing the 'TWO MODES' concept, explaining how the `topic` parameter relates to the explicit overrides (`kalshi_event_ticker` and `polymarket_event_slug`), and clarifying that explicit params override the mapped side. This conceptual grouping goes beyond the schema's per-field descriptions.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the resource (cross-venue spread on the same question) and differentiates itself from sibling tools like polymarket_arbitrage by explicitly stating that when bet shapes are non-equivalent, 'no arb exists.' The purpose is unmistakable.

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

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

The description provides explicit when/when-not guidance. It details two usage modes (`topic` shortcuts and explicit tickers) and warns that 'pre-mapped ≠ tradeable' and 'most pre-mapped topics return compatibility_warning today.' It also explains that temporal_alignment:false means 'spreads are mathematically meaningless,' telling users when the tool's output should not be used.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds behavioral detail beyond that: it returns attribute rows with geometry, supports SQL-like syntax, and hints at pagination via offset. It doesn't discuss rate limits or errors, but the annotation coverage lowers the burden.

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

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

Two sentences, front-loaded with the core purpose, and the second sentence is a valuable tip without redundancy. No wasted words.

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

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

Despite no output schema, the description states the return type (attribute rows and geometry) and shows how to sample data. Together with the comprehensive parameter schema and strong annotations, the tool is well-specified. Minor gaps like error handling are not critical for a read-only query 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 covers 100% of parameters with clear descriptions, so the description adds little new parameter meaning. It summarizes the parameter names and the SQL-like style, but the schema already provides the full semantic detail. The sampling tip does demonstrate parameter usage.

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

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

The description precisely states the action ('Query') and the resource ('ArcGIS Feature Service / Map Service layer') and notes the URL comes from search_datasets. This distinguishes it from sibling tools like layer_info or search_within.

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 explains the URL comes from search_datasets and provides a concrete example pattern ('where="1=1" + out_fields="*"' to sample). While not explicitly naming alternatives, the sibling context makes it clear this is the querying tool versus metadata/info 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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context beyond these: scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the dual-mode behavior (retrieve single value vs. list all keys). This goes beyond the annotations and enriches the agent's understanding.

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

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

Two sentences, front-loaded with the primary action, then usage guidance and scoping. Every word earns its place; there is no fluff or repetition of schema 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?

For a simple tool with one optional parameter, the description covers purpose, usage, scoping, and sibling relationships. It explicitly states the two invocation modes (with and without key). The lack of an output schema is not a gap because the return behavior is implied clearly ('retrieve a value' or 'list 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?

The schema already covers the single 'key' parameter with a description, so baseline is 3. The description adds semantic richness by explaining the 'omit to list' behavior in the first sentence and providing concrete examples of stored values (ticker, address, research notes), which helps the agent map intent to the parameter without adding bulk.

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 and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes from sibling tools (remember, forget) by explicitly framing recall as the retrieval counterpart, so there is no ambiguity about its function.

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

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

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the paired tools (remember, forget) and their relationship, giving clear context for when to use recall versus the 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses key behaviors: mark_read:true causes returned events to be flagged read, affecting subsequent calls; polling is explicitly stated as safe; and the same data is available via HTTP, providing useful context. No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, then details on return fields, filtering, and mark_read. Every sentence adds meaningful information without waste, making it both concise and well-structured.

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

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

With 5 optional parameters and no output schema, the description covers the return format, filtering options (type, since), mark_read behavior, polling safety, and an alternative HTTP endpoint. This is sufficient for an agent to select and invoke the tool effectively without additional 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%, so the baseline is 3. The description adds value by explaining the effect of mark_read on future calls, giving a concrete example for type ('sec_8k'), and describing the since parameter as an ISO timestamp. These addition extras justify a 4.

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

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

The description opens with a specific verb+resource ('Pull fired events from your subscription feed'), clearly identifying the tool's function. It further specifies the return contents (source, citation_uri, raw event payload), distinguishing it from sibling tools like list_subscriptions or recent_changes.

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 use: it's for polling recent alerts, with filtering options and a mark_read mechanism. It also mentions an alternative HTTP endpoint for scripts/dashboards, implying this tool is for AI agent use. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already mark the tool read-only, open-world, and idempotent, but the description adds substantial behavioral context: source fan-out to SEC EDGAR, GDELT/GNews fallback, USPTO sunset soft-fail, and the parallel-call nature. 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?

Every sentence contributes unique information—query examples, source behavior, parameter formats, output structure, and alternative tool. It is long but dense, with user intent examples front-loaded for quick comprehension.

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?

Even without an output schema, the description specifies the return structure (changes[], total_changes, citation URIs). It also covers edge cases like rate limits, API sunset, and the single-type limitation, making the tool self-explanatory for a complex multi-source fan-out.

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

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

Schema covers all three parameters with descriptions, so the bar starts at 3. The description adds extra value by giving concrete examples for `since` (ISO/relative) and recommending '30d' or '1m' for monitoring, plus clarifying `value` as ticker/CIK.

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 natural-language query patterns ("What's new with X") and clearly identifies the tool as a change feed for a company over a time window. It explicitly differentiates from sibling entity_profile by naming the alternative use case.

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

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

Provides explicit when-to-use guidance: 'Use entity_profile instead when you want the static profile...' and illustrates query phrasing. Also explains fallback behavior (GDELT→GNews) and the USPTO soft-fail, clarifying when results may be limited.

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 a write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds valuable behavioral context beyond annotations: persistence scoping by user identifier, retention policy (24 hours for anonymous, persistent for authenticated), and key-value storage format. It doesn't mention overwrite behavior, but annotations cover idempotency, so the added context is useful without being exhaustive.

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

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

The description is four sentences, each earning its place: purpose, usage triggers, behavioral details, and companion tools. It is front-loaded with the core function and avoids redundancy or fluff. Every sentence contributes to understanding.

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 (2 required params, no output schema, no nested objects), the description covers everything needed: what it does, when to use it, how data is stored (key-value scoped to identifier), persistence rules, and how it relates to recall/forget. It is complete for an agent to select and invoke correctly.

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

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

Schema covers both parameters fully (100% coverage), so description doesn't need to re-explain them. However, it adds meaningful examples for key naming conventions ('subject_property', 'target_ticker') and clarifies the value type ('any text — findings, addresses, preferences, notes'), which goes beyond the schema's generic descriptions. This adds practical guidance for tool invocation.

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

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

The description opens with a clear verb-object structure: 'Save data the agent will need to reuse later' and immediately distinguishes itself from sibling tools by naming recall and forget. It gives concrete examples (resolved ticker, target address, user preference) that make 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?

It explicitly states when to use it ('Use when you discover something worth carrying forward...') and provides examples of appropriate use cases. It also references sibling tools ('Pair with recall to retrieve later, forget to delete'), giving clear contextual guidance on how it fits into a workflow.

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

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

The description adds significant behavioral detail beyond the annotations: it discloses cascading internal lookups, graceful degradation when LEI/FIGI sources are unavailable, that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and that identifiers are labelled with source provenance. These insights are not present in the annotations and greatly improve agent 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?

The description is long but densely informative, with clear structure: examples, a direct usage directive, and detailed treatment of supported types. Every sentence adds value, though the opening example list could be trimmed. Overall it is appropriately sized for a multi-entity resolver.

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

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

With no output schema, the description must explain what the tool returns, and it does thoroughly: it lists CIK, ticker, company_name, LEI, FIGI, parent/ownership info, RxCUI, ingredient, brand, and source labels. It also covers timeout/cascade behavior and unresolved output, making the tool's behavior predictable enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides useful context about what each type returns (e.g., company yields CIK, ticker, LEI, FIGI; drug yields RxCUI, ingredient, brand), but it largely repeats the input forms already described in the schema. No new parameter-level syntax or constraints are introduced 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 uses the specific verb 'resolve' and specifies the resource: converting user-spoken names into canonical/official identifiers. It includes concrete examples ('What's the ticker for…') and explicitly distinguishes its purpose from sibling tools by stating it provides IDs that 'other tools require as input.'

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 a clear, explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' It also explains when each entity type applies (company vs. drug). It does not explicitly mention when not to use the tool or name alternative tools, but the context is strong enough to 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?

The description details that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. This goes beyond the annotations (readOnly, idempotent, etc.) by explaining the composite call and output structure.

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

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

Three sentences, each with clear purpose: what, mechanism, use case/return. 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?

Despite no output schema, the description specifies return contents and the composite nature of the tool. Combined with rich schema annotations, it provides sufficient context for correct usage.

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 thorough descriptions for all 4 parameters (100% coverage), so the description adds little beyond framing the first entity as the subject. The baseline of 3 applies.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' and explains the ranking and output, distinguishing it from single-entity tools like ai_visibility_check.

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

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

It provides a concrete use case 'competitive AI-marketing audits' and implies when to use (for multiple entities) versus ai_visibility_check. However, it does not explicitly list exclusions or alternative tools beyond the implied single-entity check.

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 transparency beyond the read-only/idempotent annotations by disclosing composite fan-out behavior, partial failure degradation, and the 5-30s first-measurement timeout with sources_failed reporting. This gives the agent a clear model of what to expect at runtime 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 a single dense paragraph but every sentence carries distinct information: purpose, usage triggers, return fields, ecosystem scope, and failure behavior. It is longer than ideal but the density of new facts justifies the length; a slight structural breakdown into sections would improve scannability but is not required.

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

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

With no output schema, the description takes on the responsibility of explaining return values, listing exact summary fields (`is_latest`, `license`, `advisory_count`, etc.), per-advisory details, links, and alternative versions. It also covers edge cases like partial failures and ecosystem limitations, making it fully self-contained 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?

The input schema already provides 100% coverage of both parameters (`package` and `version`) with descriptions. The tool description does not add meaningful parameter-level detail beyond what the schema says; it mentions the default version behavior but that is already in the schema. 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 begins with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call' and clearly enumerates the underlying sources (deps.dev and bundlephobia) and outputs (summary block, advisories, links, alternatives). This sharply distinguishes it from sibling tools by describing a unique composite 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?

The description explicitly states when to use the tool: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also provides exclusion guidance in 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', steering users to an alternative approach for other ecosystems.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds useful context by disclosing the return fields (name, summary, record_count, owner/org, URL) and the chaining workflow, which goes beyond what annotations or schema provide.

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

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

The description is two sentences long. The first states the action and resource, the second lists the output and downstream usage. Every phrase is necessary, 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?

For a read-only search tool with three optional parameters and no output schema, the description effectively lists the return fields and directs the user to query_layer/layer_info. Combined with the schema, the agent has sufficient information to invoke the tool and interpret results. The open-world hint is also consistent with the unspecific keyword search.

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?

All three parameters are fully documented in the schema with descriptions (100% coverage), so the baseline is 3. The description adds the domain context of keyword search and the purpose of the returned URL, but it does not elaborate on limit or org_id beyond the schema, so it meets but does not exceed the baseline.

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

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

The description clearly states the tool's function: 'Search Montana State GIS open geospatial datasets' by keyword, with specific examples (parcels, zoning, transport). It also distinguishes itself from sibling tools by noting the returned Feature Service URL is meant for query_layer/layer_info, 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 gives clear context for when to use this tool: to search and discover datasets, then pass the returned URL to query_layer/layer_info. This implies a workflow and differentiates from those sibling tools, though it does not explicitly list exclusions or alternative search methods.

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 behavioral details beyond the annotations: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, enforces a 200K character cap with truncation flagging, and returns passages with character offsets and similarity scores. These details disclose how the tool executes and what limitations exist, consistent with the readOnly and idempotent hints.

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

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

The description is four sentences, each earning its place: the first establishes the core action, the second explains when to use, the third provides a companion workflow, and the fourth details technical behavior. No filler or redundant phrasing.

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 specifies the return format (top-N passages with character offsets and similarity scores). It also covers the input size limit, truncation behavior, and safety profile (read-only). For a tool with only three parameters, this description is fully complete.

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

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

The schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds value by giving concrete examples of text inputs (SEC 10-K body, article, long tool result) and clarifying the query as 'natural-language query.' This enriches the meaning of the 'text' and 'query' parameters.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing it operates on text you already have, not a global knowledge base. The verb 'search' and resource 'fetched record' are specific and unambiguous.

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

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

The description explicitly advises when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides an alternative workflow, pairing with ask_pipeworx_grounded, to ground over relevant passages. This gives the agent clear decision 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 extensively discloses behavioral traits beyond the annotations, such as requiring a Pipeworx OAuth account, delivery channel mechanics (always-on feed, email/SMS/webhook options), phone verification, the 10/day SMS cap, webhook auto-disabling after 10 consecutive failures, and one-time delivery of the signing secret. This level of detail far exceeds the basic safety hints provided by 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 well-structured and dense, with each sentence adding meaningful context. It front-loads the core purpose, then details requirements, types, and delivery options. While not brief, it earns its length given the tool's complexity and nested parameters.

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 moderate complexity (3 parameters, nested objects, no output schema), the description is exceptionally complete: it covers subscription types, parameter requirements, delivery channels, and constraints. The only minor gap is that it does not describe the full return response shape beyond the subscription id, but this is acceptable for a creation 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% parameter coverage, so the baseline is 3. The description adds value by giving concrete examples for each subscription type (e.g., items:["5.02"] = officer change), clarifying optionality rules (e.g., sponsor or condition required for clinical_trial), and explaining delivery channel nuances, although some information is redundant with the schema.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action, and enumerates the supported subscription types, 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 provides clear context on when to use the tool, including prerequisites (OAuth account, phone verification) and supported types. However, it lacks explicit 'when not to use' guidance or direct alternatives like 'use list_subscriptions to view existing subscriptions,' though the context strongly implies these.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals the output structure (category-bucketed example questions), the dynamic source (live catalog of thousands of tools), and the optional topic filter. Adds meaningful context 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 dense but well-structured: it opens with natural user queries, then provides a clear explanation of outputs and usage. It's slightly long but every sentence carries useful information, earning a 4 rather than a 5.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and expected output shape. It is fully sufficient for an agent to decide when and how to invoke it, and even names associated meta-tools it teaches.

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 valuable semantics by explaining omitted vs provided behavior ('Call with no arguments for the full spread, or pass topic to focus') and provides concrete examples (finance, pharma, betting), elevating it above the baseline.

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

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

The description clearly defines the tool as the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It lists specific categories and distinguishes itself from siblings by emphasizing its role as the 'first step' when unfamiliar with Pipeworx.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to learn to call meta-tools. Also clarifies behavior when called with no arguments vs with a topic, providing concrete examples.

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

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

The description goes beyond the annotations by explicitly disclosing ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('row is deactivated (not deleted)'). These are meaningful behavioral traits not captured by readOnlyHint or destructiveHint.

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 deliver the core purpose, a critical constraint (ownership), and a key behavioral detail (soft delete) without any fluff. The description is front-loaded with the verb and resource, and every clause carries information.

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

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

For a single-parameter mutation tool with no output schema, the description explains the action, the ownership rule, and the post-cancellation behavior, making it self-contained. The reference to recent_alerts provides additional context for the tool's effect.

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

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

The input schema fully documents the single parameter 'id' with a clear description. The tool description adds no parameter-specific detail beyond what the schema provides, and 100% schema coverage sets the baseline at 3.

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

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

The description clearly states the action ('Cancel a subscription by id') and the specific resource. It differentiates from siblings by noting ownership enforcement and deactivation instead of deletion, making the tool's scope unmistakable.

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

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

The description provides clear context for when to use the tool (canceling subscriptions) and implies exclusion via the soft-delete note (historical events remain available via recent_alerts). However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behavioral nuances: the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), and the warning not to treat 'could_not_verify' as evidence. It also explains the two pipeline behaviors and the return format, which significantly aids correct use.

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 detailed but every sentence earns its place: query phrasings, use case, routing logic, return values, failure semantics, and efficiency note. It is front-loaded with the purpose and uses clear structural cues (e.g., 'IMPORTANT for callers'), making it easy to scan.

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

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

Even without an output schema, the description enumerates all possible verdicts ('confirmed / approximately_correct / refuted / inconclusive / unsupported / could_not_verify'), explains the meaning of the ambiguous ones, and describes the citation and reasoning returned. It covers both fast-path and grounded flows, making the tool fully self-contained 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?

Parameter schema coverage is 100%, but the description adds valuable semantics: it explains how tolerance_pct overrides claim-implied tolerance, caps at 5, and recommends 1–2 for hallucination detection. It also embeds concrete examples for the claim parameter, going beyond the schema's basic documentation.

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 explicit natural-language query phrasings and a clear verb+resource pairing: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by detailing the two routing paths (SEC EDGAR fast path vs. grounded pipeline) and its efficiency ('Replaces 4–6 sequential calls').

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

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

It provides a clear use case: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims and any other factual claim. However, it does not name alternative tools or explicitly state when not to use the tool, so it stops short of a 5.

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