Arcgis Albuquerque

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the free default model, BYO Anthropic key with direct billing, and return structure. This adds meaningful context about cost and invocation behavior. 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?

Three concise sentences front-load the action ('Probe... score visibility'), then add cost details, return format, and use cases. No wasted words; every sentence earns its place.

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

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

Since there is no output schema, the description compensates by listing the return fields (score, confidence, signals, raw_response, combined view) and use cases. It doesn't elaborate on 'signals' or scoring interpretation, but the essential context is covered.

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 describes all parameters with 100% coverage. The description repeats the default model and _apiKey purpose but does not add new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool probes LLMs and scores visibility (0-100) per model, with specific verbs and resource. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it lacks sibling distinction.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies default model behavior. It does not include exclusions or alternatives, so it falls short of full usage guidance.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description explains that the tool routes to other tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is one fast call. This adds useful behavioral context not in annotations.

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

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

The description is long but well-structured and front-loaded with the key message. Lists and examples make it actionable without wasted words, though some redundancy exists between the initial preference statement and later usage guidance.

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

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

Covers what the tool does, when to use it, examples, alternatives, and what the response includes (structured answer with citation URIs). No output schema exists, but the description compensates by describing the return format. It is complete for a broad routing tool.

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

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

The schema already has descriptions for all six alias parameters (question, q, text, input, query, prompt) with 100% coverage. The description does not add extra meaning about parameters beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool routes factual questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It explicitly differentiates from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with specific trigger phrases and examples. It also tells when to use alternatives (grounded for verbatim evidence, deep_research for broad multi-part questions).

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 and idempotent annotations, the description reveals that behavior may vary live when candidate routing improvements are under test, and that results are used for comparison to decide merges. It also clarifies it's a fully working router, not a stub, which prevents misassumptions about a beta version.

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 multi-sentence but each sentence earns its place: beta status, relationship to stable, current behavior, and usage guidance. There is minor redundancy in the parenthetical listing, but overall it is well-structured and front-loaded.

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

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

Provides complete operational context: what the tool is, when to use it, how it differs from stable, current behavior, and its role in the experimental pipeline. The absence of an output schema is mitigated by referencing the same response shape as ask_pipeworx.

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

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

The input schema already documents all parameters (100% coverage) as aliases for the single required 'question' field. The description adds only that it has the same arguments as ask_pipeworx, which is consistent but not additive, so the baseline 3 applies.

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

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

The description clearly identifies this as a beta version of the ask_pipeworx universal router, specifying it has the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by positioning itself as the experimental edge with candidate routing improvements.

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

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

Explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. Also clarifies the current state (no active candidate) so it behaves identically to the stable version, providing clear when-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the internal process: picks tool from 5,529 across 1455 sources, fills arguments, and extracts the answer using only tool result content. It details the exact return structure and refusal reasons like 'not_in_source' and 'data_truncated,' and reveals the extra LLM call cost, adding substantial behavioral context.

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

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

The description is dense but well-structured, front-loading the core value proposition ('Hallucination-resistant') before elaborating on mechanism, return format, and usage. At roughly 100 words, every sentence carries unique information with no filler.

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

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

The description covers purpose, usage, behavior, return structure, refusal scenarios, and cost tradeoffs. It is particularly strong for a tool with no output schema, as it pre-specifies the result shape and all possible refusal_reason values, 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?

Since the schema has 100% coverage with all parameters being aliases for 'question,' the baseline is 3. The description adds value by explaining that the question is routed across 5,529 tools and fills arguments, giving the agent a better understanding of how the question will be processed beyond the raw schema.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the tool as a grounded variant of ask_pipeworx. It distinguishes itself from the sibling ask_pipeworx by emphasizing evidence extraction and explicit refusal behavior, so it is specific and well-differentiated.

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

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

The description explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to-use guidance. It also names the alternative (ask_pipeworx) and explains the cost tradeoff.

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 read-only, idempotent, and non-destructive. The description adds substantial behavioral context: low-confidence matches short-circuit, closed markets skip fan-out, wide-spread markets are flagged, cancellation rule parsing, and GDELT rate-limit fallback details. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (RESOLVER CONTRACT, SAFETY, etc.) and front-loads the main use case. Every section adds operational detail needed for safe use, though it could likely be trimmed without losing key information.

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

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

With no output schema and high complexity, the description is highly complete: it documents response shapes (result.market, result.analysis, result.evidence), resolver match confidence, parent event extraction, statuses, and cancellation rules, covering edge cases and safety mechanisms.

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 all 3 parameters with descriptions (market, depth, include_raw). The tool description does not add new parameter-level semantics beyond what the schema states; fan-out examples are contextual, not parameter-specific. Baseline 3 is appropriate with 100% schema coverage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant data in one call, with explicit input formats (slug, URL, question text). It distinguishes from siblings by focusing on single-market research ('should I bet on X') rather than edge scanning or arbitrage.

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 lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples. However, it does not explicitly name alternative tools or when not to use this one, so it lacks the explicit exclusion part 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 adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output format with pipeworx:// citation URIs. This is genuinely useful and goes beyond the annotations.

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

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

The description is dense but well-structured: it starts with trigger phrases, then states the core operation, then details data sources and behavior. Every sentence adds value with no fluff or repetition.

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

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

Even without an output schema, the description covers return format (paired data + citation URIs), sorting behavior, and the scope of data pulled. For a complex comparison tool, this is complete and self-sufficient.

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

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

The schema already documents both parameters with 100% coverage. The description further enriches semantics by providing concrete examples (tickers/CIKs, drug names), explaining the enum values ('company' pulls 10-K data, 'drug' pulls FAERS counts), and clarifying min/max item counts. This adds value above 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?

Description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single call, with specific trigger phrases ('compare X and Y', 'X vs Y' etc.) and data sources. It distinguishes itself from sequential lookups by explicitly saying it replaces 8–15 of them.

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

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

Provides explicit trigger examples, states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and clarifies when to use company vs drug types. This gives clear when-to-use guidance and an alternative approach.

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

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

Annotations already indicate read-only/open-world/idempotent, and the description adds rich context: auth/paid-tier requirements, latency, output packet structure, gap[] honesty ('never invented'), citation_uri fetchability guarantee, contradictions[], and semantic excerpting. 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 dense but every sentence contributes distinct information, front-loaded with the critical account requirement and organized logically (what/how, when to use, depth behavior, output details, latency). 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?

With no output schema, the description fully discloses the findings packet (evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), explains failure modes (empty gaps), depth semantics, and performance limits, leaving no significant gap in the agent's understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable beyond-schema meaning for depth ('standard re-angles unanswered gaps', 'thorough chases the best leads') and clarifies that question can be broad/multi-part, which justifies a stronger score.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and contrasts it with open-web search and sibling tool ask_pipeworx, making its unique function 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?

Explicit guidance is provided: 'Best for broad/multi-part questions over structured data', and exclusions are named ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). The account prerequisite is also stated upfront.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: results include 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' This clarifies the output format, which is essential since there is no output schema.

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

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

The description is two sentences, front-loaded with the core purpose, and every phrase earns its place. The list of data domains is useful but compact, and the 'ready to call' detail is valuable without being bloated.

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

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

Despite having no output schema, the description fully compensates by explaining what results contain (names, descriptions, full schemas, curated examples). It also explains the tool's role as a first-step discovery mechanism, covers usage timing, and lists covered domains, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond what the schema already documents (e.g., the 'query' parameter's aliases and examples are in the schema). The mention of 'top-N' and 'curated examples' pertains to output semantics, not parameter semantics.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource pair that clearly identifies this as a discovery/meta-tool. It further distinguishes from siblings by listing concrete domains (SEC filings, FDA drugs, etc.) and stating 'Call this FIRST when you have many tools available,' making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: '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.' It does not explicitly state when not to use or name alternative sibling tools, so it falls short of a 5.

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

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

Annotations declare read-only, non-destructive, idempotent behavior, and the description adds substantial detail beyond that: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) in parallel, mentions the USPTO PatentsView API sunset and soft-fail behavior, and describes the GDELT→GNews fallback. This gives the agent useful expectations about internal behavior and resilience.

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

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

The description is dense but every sentence contributes meaningful information—trigger examples, preference guidance, fan-out sources, return fields, and input constraints. It uses a semicolon-separated list for return items, which aids scannability. Slightly long, but no wasted words.

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

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

For a complex tool with no output schema, the description provides a thorough overview: what inputs are accepted, what outputs are returned (with URI format), how it behaves in edge cases (patent soft-fail, news fallback), and when to use alternatives. This is complete enough for an agent to select and invoke the tool effectively.

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

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

Schema coverage is 100% with both parameters described, so the baseline is 3. The description adds extra semantic value by providing concrete examples ('AAPL' or '0000320193'), specifying zero-padded CIK format, and reiterating the name-unsupported caveat with a pointer to resolve_entity. This goes beyond the schema's 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 multiple natural-language trigger phrases and states 'full cross-source profile of a US public company in ONE parallel call,' making the tool's purpose unmistakable. It also differentiates itself from sibling tools by explicitly preferring this tool over chaining single-pack SEC/XBRL/news lookups, and contrasts with resolve_entity for name resolution.

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

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

Provides clear when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an exclusion: 'names not supported (use resolve_entity first if you only have a name),' which names the alternative tool. The example queries further signal appropriate invocation.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds a note about clearing 'sensitive data', but otherwise relies on annotations and does not disclose additional behaviors like permanence of deletion or error handling. No contradiction with annotations.

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

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

The description is three short sentences. The first states the core purpose, the second gives usage conditions, and the third mentions complementary tools. No fluff or repetition.

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

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

For a simple one-parameter destructive tool with annotations covering safety, the description covers purpose, usage, and tool relationships. It does not specify the return value, but there is no output schema, and a minimal return indication (e.g., success/failure) is not stated, which is a minor gap.

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 describes the only parameter 'key' as 'Memory key to delete' (100% coverage). The description simply repeats 'by key' and adds no additional semantic detail 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 'Delete' and clearly identifies the resource as 'a previously stored memory by key'. It distinguishes from sibling tools like remember and recall by being the delete counterpart, explicitly mentioning pairing with them.

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

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

The description provides explicit when-to-use conditions: 'context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, but does not explicitly state when not to use the tool or name an alternative in a direct 'instead use' manner.

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 value by revealing the underlying workflow: fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. This complements the annotations without 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?

Three sentences, front-loaded with the primary action, followed by process and use cases. No filler; each sentence earns its place.

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

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

The tool has two simple parameters, no output schema, and strong annotations. The description explains what the output looks like ('single text blob ready to drop at site-root/llms.txt'), the extraction process, and practical applications, making it complete enough for an agent to 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?

Both parameters (url and max_links) are fully described in the schema (100% coverage), so the baseline is 3. The description adds minimal extra semantic value beyond the schema—it refers to 'key links' but does not elaborate on max_links behavior. It is sufficient but not enhancing.

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

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

The description opens with a specific action—'Generate a production-ready llms.txt file for any URL'—and clearly distinguishes the tool's purpose from siblings by detailing the extraction and output process. It names the exact resource (llms.txt) and the standard format, making it 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 use cases: getting a client's site indexed, drafting your own llms.txt, or auditing a competitor's AI visibility. It does not explicitly mention alternatives or exclusions, but the context is enough to know when to invoke 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific return fields, which is useful context, but it does not discuss auth requirements, error behavior, or rate limits. 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, well-structured sentence that front-loads the verb and resource. It contains zero filler and every word contributes meaning.

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

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

For a simple read-only metadata tool with one parameter and no output schema, listing the returned items (fields, geometry type, record count, capabilities) is fairly complete. It could mention error handling or URL format specifics, but those are secondary given the straightforward 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 description coverage is 100%; the url parameter is fully described in the schema with an example. The description repeats 'by url' but adds no additional semantic detail, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'Get an ArcGIS Feature/Map Service layer's schema by url' and enumerates the specific schema components returned (fields with name+type, geometry type, total record count, capabilities). This distinguishes it from sibling tools like query_layer, which likely retrieves actual features rather than metadata.

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

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

The description implies the tool is for schema inspection rather than data querying, but it does not explicitly state when to use it or mention alternatives. Sibling tool names like query_layer suggest the distinction, but the description itself lacks explicit usage guidance or 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?

Beyond the readOnly/idempotent annotations, the description discloses the specific fields returned (id, type, params, created_at, last_fired_at, fire_count) and scopes results to the caller's subscriptions, adding meaningful behavioral 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?

Two tightly focused sentences: the first defines the purpose and output, the second gives practical usage guidance. No wasted words and the key information is front-loaded.

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

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

For a simple read-only list tool with a single optional parameter and no output schema, the description covers what it does, what it returns, and when to use it. The guidance for pre-subscription review and cancellation is sufficient and 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 only parameter (include_inactive) is fully described in the schema with a clear description and default, achieving 100% schema description coverage. The tool description does not repeat parameter details, so the baseline 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the exact return fields, distinguishing it from the subscribe/unsubscribe siblings by its read-only enumeration purpose.

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

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

It explicitly says to use this tool to review existing subscriptions before adding more and to find an id to cancel, providing concrete when-to-use guidance and implying the alternatives (subscribe/unsubscribe).

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

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

With annotations providing minimal behavioral info (all false), the description compensates richly by disclosing rate limits (5 per identifier per day), cost (free, no quota impact), claim_token behavior for unauthenticated submissions, and how to use the token to read later status. It also reveals that the team reads digests daily and signal affects roadmap—useful for setting 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 dense but every sentence earns its place: purpose, use cases, exclusions, content guidance, token workflow, rate limits, and cost. It is front-loaded with the core purpose and well-structured for an AI agent to parse. No fluff or redundancy.

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

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

Despite having no output schema, the description explains the key return-value behavior (claim_token) and the lifecycle of a feedback report. It covers operational details like rate limits and cost, and areas the agent might need (what is acceptable content). The tool is moderately complex with nested params and optional context, but the description fully equips an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial value beyond parameter descriptions. It explains the claim_token parameter's usage pattern (pass it back with no other arguments to read status) and elaborates on the type enum semantics. This goes beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the scope (issues with Pipeworx tools/packs), distinguishing it from sibling tools like ask_pipeworx which are for using Pipeworx data rather than providing feedback about the service itself.

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?

Offers explicit when-to-use scenarios: bug, feature/data_gap, and praise. Provides a clear when-not-to-use: for tools from other MCP servers, directing users to file with that server instead. Also instructs what to include (describe in terms of Pipeworx tools/packs, not end-user prompts), making usage criteria unambiguous.

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

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

The description adds valuable context beyond annotations: it is self-aggregating from CF analytics-engine, contains no PII, returns '(pack, tool, count)' data, and discloses caching behavior (5min-1h depending on window). Annotations already indicated read-only, idempotent, non-destructive, and the description is consistent with 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 front-loaded with the core purpose, followed by a bulleted list of use cases and a concise technical note. Every sentence adds relevant information with no filler, and the structure is clear and appropriately sized.

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 only one optional parameter and no output schema, the description sufficiently explains the return contents (top tools, top packs, total call volume) and the tuple format (pack, tool, count). It also covers caching and privacy, making it complete for the tool's simple 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?

The single `window` parameter is already fully documented in the schema with enum values and a clear description of trade-offs. The tool description merely restates the window options and adds no new meaning beyond the schema, so the baseline of 3 for high schema coverage 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 opens with a clear verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It clearly distinguishes from siblings by focusing on aggregated agent call trends, not just listing available tools like `discover_tools`.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming canonical tool choice, and aligning with typical agent needs. This provides clear when-to-use context, but it doesn't explicitly mention alternatives or when-not-to-use scenarios, stopping 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?

With readOnlyHint=true and idempotentHint=true already in annotations, the description adds substantial behavioral context: the fill check with live CLOB depth, the warning that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it,' the semantic anchor threshold, and the partition filter with placeholder slugs. This goes well beyond the basic annotations and helps agents understand the tool's actual behavior, including edge cases.

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

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

The description is long but every section serves a purpose: mode selection, methodology, semantic anchoring, filtering, response structure, and fill-check warning are all clearly labeled and front-loaded. The dense use of capitalization and section markers makes it scannable, and there is no filler or repetition. It is appropriately detailed for a complex arbitrage detection tool.

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

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

The tool has no output schema and two optional parameters, yet the description fully covers what the tool returns (opportunities[], partition_check, fill check details), when to use each mode, and how to interpret signals. It also addresses potential pitfalls (thin legs, placeholder filters, low similarity) and directs users to a sibling tool for further custom sizing. This makes the description self-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?

Although the input schema already provides 100% coverage for both 'event' and 'topic', the description significantly enriches this by explaining exactly how each parameter is used, providing example values like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal,' and detailing the mode-specific behavior triggered by each parameter. This adds meaning beyond the schema's minimal descriptions.

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

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

The description opens with a specific, informative statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly defines the tool's resource (Polymarket markets) and scope, and goes on to distinguish between trending, event, and topic modes, giving concrete examples. The description also names the sibling tool 'polymarket_fill_risk' for custom sizing, which differentiates it from related tools.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends 'event' for a specific market, describes when 'topic' is preferable, and even identifies cross-event scanning advantages. It also directs users to 'polymarket_fill_risk' for custom sizing, giving a clear when-to-use-alternative.

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

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

Beyond the readOnly/idempotent annotations, the description discloses extensive behavioral details: caching at KV level for 1 hour keyed on knobs, three response segments, diagnostics for empty results, per-leg Kelly behavior for partitions, and a 24h-move warning. It also explains that Fed bets are excluded due to unreliable signals. 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 densely packed with necessary information given the tool's complexity (5 model families, 9 parameters, diagnostics). It front-loads the primary purpose in the first sentence. However, it is a single block of text that could benefit from bullet points or segmentation to improve scanability.

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

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

With no output schema, the description thoroughly explains the response structure: top-level by_segment, fed_candidates, and _diagnostics with funnel counters. It details the fields returned (edge_pp_net, kelly_fraction, market liquidity/spread/volume) and the 24h-move warning. This is complete for an agent to understand what to expect.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds high-level context about tradeable-edge filters and per-leg Kelly, but these concepts are also present in the schema. It does not introduce new parameter-level semantics beyond what the schema already offers.

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

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

The description states the tool's core function with a specific verb: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery across five model families. The phrase 'Built for "what should I bet on today"' reinforces the intended 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?

The description provides clear context for when to use the tool: discovering betting opportunities without paging through markets. It explains tradeable-edge knobs and mentions that Fed bets are excluded from ranking, which guides filtering. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses critical behavioral details: history depth bounded by a 60-day snapshot TTL, gaps due to cache-miss writes, decay computed from daily closes not intraday, and the exact semantics of expired[] and snapshot_dates[]. This goes well 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 long but well-structured with clear ARGS, RESPONSE, and LIMITS sections. Every sentence provides value, explaining response fields and limitations. It could be slightly trimmed, but the labeled structure makes 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?

Given the lack of an output schema, the description fully specifies the three response arrays (tracked, expired, snapshot_dates), their fields, and interpretation of decay and lifespan. It also explains the underlying data pipeline (snapshots written on cache-miss) and limitations, making the tool's behavior comprehensively understandable.

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

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

Both parameters are fully described in the schema with defaults and ranges (days: default 14, clamp 2-30; window: enum 24hr|1wk|1mo). The description repeats 'lookback, default 14, max 30' and 'snapshot family, default 1wk' but adds no substantive new meaning beyond the schema, hence baseline 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?', which distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage (arbitrage detection).

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

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

The description provides context on when to use it by contrasting fresh vs 3-week-old edges, implying this tool is for assessing edge age and decay. It doesn't explicitly name alternatives, but the mention of being built from polymarket_edges snapshots and the question it answers clearly differentiate it from siblings.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the computational behavior: it walks the order-book ladder, computes VWAP fill prices, returns a verdict, and identifies forced directional risk. It explains that size_usd means different things in each mode and how partial fills convert an arb into a directional position. No contradiction with annotations.

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

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

The description is long but every sentence carries information. It uses clear section headers (SINGLE-MARKET, BASKET) and lists outputs in a scannable way. It's front-loaded with the core purpose and ends with the use-case recommendation. No filler or repetition.

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

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

For a tool with no output schema, the description thoroughly lists all return fields per mode, explains edge cases (thin legs, forced_directional_risk, max_clean_notional_usd), and states the protocol requirements (one of market/event). It leaves little ambiguity about behavior or outputs, making it highly complete given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly enriches parameter semantics. It clarifies mutual exclusivity/requirement of market vs event, defines side options and defaults for each mode, explains size_usd semantics (max spend vs target proceeds vs settlement notional), and mentions the default/clamp. This far exceeds the schema descriptions.

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

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

The description opens with a precise verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then details two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role as the pre-trade risk check. This clearly separates it from the sibling tools.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable; partial basket fills create directional risk). However, it doesn't name alternatives for when not to use it, and the 'when-not' is only implied by the threshold, so it stops short of a fully explicit 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 details the response structure (leg-by-leg prices, matched spreads), two compatibility_warning scenarios, temporal_alignment semantics, and the skipped_cross_type/subtype counters, giving the agent comprehensive expectations about the tool's behavior 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?

Despite its length, the description is meticulously structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence delivers operational value. It front-loads the core purpose and then systematically walks through modes, output, safety, and pitfalls, making the density appropriate for the tool's complexity.

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

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

With no output schema and high complexity, the description fully compensates by explaining what the response contains, the exact conditions for compatibility_warning, what temporal_alignment indicates, and what the skipped counters reveal. It gives the agent everything needed to invoke the tool and interpret results 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?

Although the schema already describes all three parameters, the description adds crucial semantics: 'topic' auto-fetches pre-mapped events on both venues, explicit kalshi_event_ticker/polymarket_event_slug override the mapped side, and the two modes are mutually exclusive via override. It also provides concrete format examples like 'KXFED-26OCT' and 'fed-decision-in-june-825', which are only partial 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 opening sentence defines the tool as a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly differentiates it from sibling tools focused on single venues or other analyses. It also explains the core value (2-25pp price differences due to participant pools) and immediately conditions that the signal is real only when bet shapes are equivalent.

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 presents two modes (topic shortcuts vs. explicit ticker/slug) and when each should be used, and it warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternative tools like polymarket_arbitrage, but it clearly tells the agent when the tool will report no arb exists and when spreads are unreliable.

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 adds that the tool 'Returns attribute rows (and geometry)', disclosing the output format. It also gives a practical sampling tip, providing behavioral context not present in the schema or annotations.

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

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

The description is two sentences, front-loaded with purpose and parameters, followed by a practical usage tip. Every word contributes value, with no filler or redundancy.

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

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

With a comprehensive schema (100% coverage) and rich annotations, the description fills key gaps by stating the return type (attribute rows and geometry) and referencing the search_datasets workflow. It adequately covers the tool's behavior for a query operation, though no output schema exists.

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 descriptive parameter definitions. The description lists parameter names and some semantics (e.g., 'SQL-like where', 'comma-separated out_fields') but largely echoes schema information, adding little new meaning 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 explicitly states the verb 'Query' and the resource 'ArcGIS Feature Service / Map Service layer', making the tool's function immediately clear. It distinguishes itself from siblings like search_datasets by specifying it operates on a layer URL and returns attribute rows/geometry, not dataset discovery.

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

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

It provides contextual guidance by noting the URL comes from search_datasets, implying a typical workflow. The tip to use `where="1=1"` and `out_fields="*"` to sample gives a concrete usage scenario, though it does not explicitly name alternative tools or exclusion criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that it is 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and explains the two modes (retrieve vs. list). This goes beyond the annotations without contradicting them.

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

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

Three sentences: action, use case, scope/related tools. Each sentence adds distinct value; no redundant filler. Front-loaded with the core verb.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and related commands. It does not specify the return format for missing keys but is otherwise sufficient.

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

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

The schema already provides a description for the key parameter with 100% coverage. The description restates the 'omit the key argument' behavior seen in the schema but adds no new parameter-level semantics. Per rubric, baseline 3 is appropriate.

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

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

The description uses specific verbs 'Retrieve' and 'list' and names the resource 'value previously saved via remember' or 'all saved keys'. It clearly differentiates from sibling tools by referencing remember and forget, establishing this as the read operation in the memory pair.

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

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

It explicitly states 'Use to look up context the agent stored earlier' and gives examples (target ticker, address, research notes). It also mentions pairing with remember and forget, providing workflow guidance. However, it does not explicitly name alternative tools or exclusions, so it stops short of a 5.

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

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

The description discloses the mark_read side effect ('flag returned events read so the next call only shows newer ones'), which is valuable behavior context. However, this directly contradicts the annotation readOnlyHint: true, which states the tool does not modify state. This is an annotation contradiction, so score is 1.

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

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

The description is efficiently written, front-loads the purpose, and each sentence adds value (returns, filtering, mark_read, polling/alternative endpoint). 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?

The description explains what the tool returns (source, citation_uri, raw payload), how to filter, mark_read behavior, and polling suitability. With 5 optional params and no output schema, this is reasonably complete. The unread_only param is left to schema, which is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a concrete example type 'sec_8k' and explains the effect of mark_read, but the schema already describes all parameters. No significant extra parameter meaning.

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.' It clearly identifies the tool's scope (alerts from subscription feed) and distinguishes it from sibling tools like list_subscriptions (which manages subscriptions) and recent_changes (which may be about 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: filter by type and since, and mentions that polling works fine, plus an alternative access method via GET endpoint. However, it doesn't explicitly contrast with sibling tools like list_subscriptions, so no 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing behavioral details: parallel fan-out, GDELT preferred with GNews fallback on rate-limit/5xx, USPTO patent API sunset causing soft-fail, and the structured return shape (changes[], total_changes, citation URIs). This adds significant context not available in annotations.

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

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

The description is somewhat long but every sentence conveys necessary information—examples, source details, fallback logic, and return structure. It is front-loaded with user-intent phrasing, making it easy to scan. The density is justified by the tool's multi-source complexity, though a more compact structure could improve readability.

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

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

Given the absence of an output schema, the description adequately explains the return format (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers the tool's multi-source nature, fallbacks, and known API limitations, leaving no critical gap for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by elaborating on `since` with ISO and relative shorthand examples ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also clarifies `value` as ticker or CIK, which the schema already mentions, so the incremental insight is moderate but still useful.

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 queries ('What's new with X') and clearly defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes itself from the sibling entity_profile by contrasting windowed changes versus static profile, leaving no ambiguity about the tool's 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?

The description provides rich usage context: it explains the fan-out to SEC EDGAR, GDELT→GNews fallback with specific failure conditions, USPTO soft-fail behavior, and the `since` parameter formats. It explicitly names an alternative tool: 'Use entity_profile instead when you want the static profile...', giving clear when-to-use vs. when-not-to-use guidance.

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

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

Beyond the annotations, the description adds meaningful behavioral context: key-value storage, scoping by identifier, persistence differences for authenticated vs anonymous sessions, and retention time. This helps the agent understand side effects 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 well-structured and appropriately sized, starting with the core purpose, then use cases, then storage details, and finally related tools. No redundant or filler sentences.

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

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

For a simple two-parameter write tool with no output schema, the description covers the essential semantics: what is stored, why, when, how it is scoped, retention behavior, and how to retrieve/delete. It is fully sufficient for an agent to act correctly.

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

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

Schema description coverage is 100% and the schema already documents both parameters with clear descriptions and examples. The description reinforces the key-value pairing and mentions scoping, but does not need to add much more 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 a specific verb ('Save') and resource ('data the agent will need to reuse later') and clearly explains the tool's purpose. It also distinguishes itself from sibling tools by explicitly mentioning sync with recall and forget.

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

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

It provides explicit guidance on when to use the tool ('when you discover something worth carrying forward') and gives concrete examples. It does not explicitly say when not to use it, but the alternatives/complements (recall, forget) are named.

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 read-only, open-world, and idempotent, but the description adds substantial context: internal cascading through multiple endpoints, source labeling, explicit reporting of unresolved identifiers, and graceful degradation when GLEIF/OpenFIGI are unavailable. This far exceeds the annotation baseline and informs the agent about edge cases.

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

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

The description is long and dense, with a large block of parenthetical details. While front-loaded with examples and well-organized, it repeats information already present in the schema (e.g., accepted inputs) and could be tightened without losing essential context.

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

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

With no output schema, the description adequately explains return values for each supported type, including source-specific fields, unresolved handling, and the drug citation. It covers inputs, outputs, and error behavior comprehensively, though it stops short of specifying an exact response structure.

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

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

The input schema already provides 100% coverage with detailed descriptions and examples for both parameters. The description reinforces the accepted input formats for company and drug but does not add significant new meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with example queries and detailed supported types. It distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID' and noting other tools require these IDs 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?

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use signal. It also mentions replacing 2-3 manual lookups and graceful degradation, but does not name specific alternative tools or provide explicit when-not-to-use scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful operational detail: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the return fields (ranked list with score, confidence, signal density), which is valuable 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?

Three sentences, each earning its place: the first defines the action, the second explains mechanism and output, the third gives a concrete use case and quotes an example. Front-loaded with the main verb and 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?

The description covers the process (probes with ai_visibility_check, ranks) and return value composition (ranked list with score, confidence, signal density), which is essential since there is no output schema. It does not mention ordering direction (e.g., descending by score), error cases, or model selection behavior, but those are partially covered by schema annotations. Overall, it is sufficient for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific meaning beyond the schema; it repeats 'entities' concept ('your brand + N competitors') but does not clarify parameter syntax, formats, or edge cases beyond what property descriptions already provide. The schema itself is thorough, so no extra credit needed.

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: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from siblings like ai_visibility_check (single-entity probe) and compare_entities (generic comparison) by focusing on AI visibility and naming the underlying probe tool. The competitive audit example further anchors its purpose.

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

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

The description states a clear use case: 'Useful for competitive AI-marketing audits' with a concrete question ('does Claude know about us as well as our competitors?'). It mentions probing with ai_visibility_check, implying the single-entity alternative, but does not explicitly say 'use this instead of ai_visibility_check when comparing multiple entities' or provide exclusions. Still, the context is clear enough for an agent to choose appropriately.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses partial failure behavior, the 5-30s timeout for bundlephobia first measurements, the sources_failed field, and graceful degradation. This provides valuable context that annotations alone would not 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 dense but front-loaded: it opens with the core purpose, then usage guidance, then return payload, then limitations/failure behavior. Every sentence adds value, and no information is wasted.

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 enumerates the summary block fields, per-advisory detail, links, and recent alternative versions. It also covers ecosystem limitations, latency expectations, and failure handling, making the tool's behavior fully understood 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 with clear descriptions for both 'package' and 'version' including scoped package support and default version behavior. The description does not need to add parameter details, 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's purpose: a composite 'should I add this npm package' check combining deps.dev and bundlephobia data. This specific verb+resource (scan dependency) and explicit mention of data sources distinguish it from sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly says 'Use whenever an agent asks...' with concrete example questions, and also states exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly communicates when to use this tool versus alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior. The description adds useful context beyond that: it enumerates the return fields (name, summary, record_count, owner/org, Feature Service url) and provides workflow integration, which helps the agent anticipate outputs. No contradictions with annotations.

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

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

Two concise, front-loaded sentences. The first states purpose and scope; the second describes return fields and next steps. No wasted words, every sentence earns its place.

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

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

Given no output schema, the description compensates by listing the key return fields and indicating how to use the output with sibling tools. It covers purpose, scope, and return format adequately. Minor omissions like pagination behavior or empty-result handling exist, but they are not critical for this search 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%, with each parameter (query, limit, org_id) already well-documented. The description adds minimal extra parameter detail, only reinforcing the 'by keyword' nature of the query. Baseline 3 is appropriate as schema handles the heavy lifting.

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

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

The description uses a specific verb ('Search') and resource ('City of Albuquerque GIS open geospatial datasets') with clear scope (parcels, zoning, public works & city services). It distinguishes from sibling tools by noting the returned Feature Service url is meant for query_layer / layer_info, making the tool's role clear.

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: use this tool to discover datasets, then pass the returned url to query_layer or layer_info for further access. It names specific sibling tools as next steps, but does not explicitly state when not to use this tool (e.g., if you already have a url, go directly to query_layer).

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

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

The description discloses technical behavior beyond the annotations, including the BGE-base-en embedding model, cosine similarity, 500-char overlapping windows, and the 200K char truncation with a flag. This adds useful context about performance and data handling, with no contradiction to 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?

Every sentence contributes value: purpose, usage context, technical details, and pairing with a related tool. The description is dense but not verbose, and the key information is front-loaded in the first sentence.

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

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

Given the tool's complexity and lack of an output schema, the description compensates by explaining return values (passages with offsets), input constraints, truncation behavior, and how it fits with ask_pipeworx_grounded. It is complete enough for an agent to use 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 adds only minimal extra nuance about the text being a fetched record and query being natural-language, but the schema already provides these details and examples, so the description adds little beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with the specific output of top-N passages with character offsets and similarity scores. It distinguishes itself from the sibling tool ask_pipeworx_grounded by positioning search_within as the passage-extraction step after fetching.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains it saves context by returning only relevant passages. It also pairs the tool with ask_pipeworx_grounded, providing clear workflow context and an explicit alternative.

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

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

The description goes well beyond annotations by disclosing important behavioral traits: auth requirement, account persistence limitation, phone verification, SMS daily cap, and the always-on feed behavior. It also states what the tool returns ('the new subscription id'). No contradiction with annotations; idempotentHint is not contradicted, though not explicitly explained.

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

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

The description is a single dense paragraph that front-loads the purpose and then adds supporting details. Every sentence carries information, but the density might be overwhelming. It could be structured with bullet points, but it's still well-organized and does not waste 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?

It covers the central aspects: subscription types, params, delivery channels, return value, and account prerequisites. However, it omits the webhook delivery channel entirely from the main description (though the schema includes it), which is a slight completeness gap. Without an output schema, it does clarify the return value, so overall it is quite complete.

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

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

Schema coverage is 100%, but the description adds meaningful examples for each subscription type, such as items:['5.02'] meaning officer change, and clarifies the structure of `params` with concrete JSON snippets. It also explains delivery channel requirements (e.g., phone must be verified). This provides 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly identifies the tool's function and differentiates it from siblings like list_subscriptions and unsubscribe by using the verb 'Create' and naming subscription types.

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 clearly states the context: requires a Pipeworx OAuth account, and explicitly notes that anonymous + BYO cannot persist subscriptions. It also mentions the always-on feed and alternatives like recent_alerts or a direct JSON endpoint. However, it does not explicitly say when not to use this tool (e.g., for one-off queries) or compare with other alerting tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context beyond this: it returns category-bucketed examples drawn from a live catalog, includes the exact tool and argument shape, and describes the optional topic-scoping behavior. It does not contradict the annotations and provides reasonable transparency for a read-only tool.

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

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

The description is longer than average but front-loads the most important user-intent phrases and quickly gets to the point. It covers purpose, usage, return value, and examples in a compact block. Some redundancy exists in listing many query phrasings and categories, but this is useful for an onboarding tool and not wasteful.

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

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

Given there is no output schema, the description fully explains what the tool returns (category-bucketed example questions, each with tool + argument shape). It also covers argument behavior, the full vs focused call, and the intended first-use scenario. Combined with strong annotations, the description is complete and self-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 description coverage is 100%, so the baseline is 3. The description adds minor reinforcing detail ('pass topic to focus') and examples ('finance', 'pharma', 'betting'), but these largely mirror the schema's own description of the optional focus area and omitting for a cross-category spread. It does not provide meaningful new semantics beyond the schema.

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

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

The description clearly identifies this as an onboarding tool that returns category-bucketed example questions, and distinguishes it by explicitly stating the intended first-use scenario ('Use this FIRST when you do not yet know what Pipeworx can do for you'). It names the exact output (example questions with tool + argument shape) and references specific sibling meta-tools, making its purpose and differentiation clear.

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 usage context: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains both calling modes (no arguments for full spread, or pass a topic to focus). It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the guidance is clear and actionable.

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

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

The description goes beyond the annotations by revealing that cancellation is a soft delete ('deactivated, not deleted') and that ownership is enforced. It also connects the side effect to recent_alerts, which is valuable behavioral context not present in the annotations or schema.

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

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

Two sentences, front-loaded with the core action. Every sentence carries essential information without redundancy or fluff.

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

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

The description covers purpose, ownership constraint, and the soft-delete behavior. It does not state the return value or error cases, but given the simple single-parameter interface and strong annotations, this is a minor gap. Overall, the agent receives enough to select and invoke the tool correctly.

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

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

The schema already provides a complete description for id ('Subscription id (uuid) returned by subscribe'). The description adds an extra semantic: the id must be a subscription you own. This adds meaning beyond the schema's type and provenance.

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

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

The description states a clear, specific action: 'Cancel a subscription by id.' It also distinguishes the tool by adding ownership enforcement and the soft-delete behavior, which sets it apart from related tools like subscribe and list_subscriptions.

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

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

The description implies usage context: use this to cancel a subscription you own, and the deactivation behavior ensures historical events remain available via recent_alerts. It does not explicitly name alternatives or exclusions, but the ownership and soft-delete details provide sufficient usage guidance.

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

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

Beyond annotations (read-only, open-world, idempotent, non-destructive), the description adds crucial behavioral details: the exact meaning of 'could_not_verify' (check did not happen, includes verification_error, must not be shown as evidence), the meaning of 'unsupported' (no source covers it), and the automatic routing between SEC EDGAR and the grounded pipeline. It also discloses the return structure with verdict, value, citation, and reasoning.

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

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

The description is information-dense and well-organized: examples first, then core purpose, routing logic, output specification, and important caveats. Though slightly long, every sentence contributes value—especially the critical clarifications about could_not_verify and unsupported. No wasted words, but the example list in the first sentence could be trimmed for slightly better front-loading.

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

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

Given there is no output schema, the description fully describes the return values and error semantics. It covers the two processing paths, the verdict categories, the citation and reasoning elements, and the key distinction between 'could_not_verify' and 'unsupported'. For a tool of this complexity, the description is complete and self-contained.

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 both parameters already have clear descriptions. The description adds only marginal extra meaning, such as 'exact percent-delta math' for tolerance handling, but it does not substantially go beyond what the schema states about claim and tolerance_pct. A baseline of 3 is appropriate given high schema coverage.

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

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

The description starts with a clear verb+resource: 'natural-language claim verification against authoritative sources.' It provides example query phrasings, specifies the SEC EDGAR path for company-financial claims and a grounded pipeline for other claims, and lists the exact verdict types returned. This unambiguously distinguishes it from sibling tools like ask_pipeworx_grounded.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates usage based on claim type (company-financial vs. other) and explains what 'could_not_verify' and 'unsupported' mean to guide interpretation. It also notes it replaces 4–6 sequential calls, giving a clear efficiency-oriented reason to choose this tool.

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