Arcgis Orovalley

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: the default model is free, passing `_apiKey` enables Anthropic probes with direct billing, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. 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 about 60 words, front-loaded with the core purpose, then efficiently covers defaults, payment implications, output shape, and use cases. Every sentence contributes new information, with no redundancy or filler.

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

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

Given the tool's moderate complexity (multiple optional models, key handling, scoring) and the absence of an output schema, the description sufficiently discloses the return format (per-model and combined view) and operation details. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptive parameter explanations, so the baseline is 3. The description enhances this by explaining the default behavior of `models` (workers-ai), the pass-through nature of `_apiKey` to api.anthropic.com, and the disambiguation role of `context`. This adds practical meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly states the action, the object, and the output format. This distinguishes it from sibling tools like scan_competitor_ai_presence by emphasizing per-model LLM knowledge scoring.

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

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

The description provides clear use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't name alternatives or explicitly state when not to use the tool, but the listed scenarios give a strong sense of appropriate usage.

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

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

The annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: automatic routing across thousands of tools, argument filling, and stable pipeworx:// citation URIs. It does not mention potential failure modes or edge cases, but the added detail is substantial.

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

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

The description is front-loaded with a strong directive and useful examples, but it contains redundant repeated blocks: the 'START HERE...' sentence and the same example list appear multiple times. This bloats the description and reduces clarity, making it less concise than it should be.

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 routing tool with no output schema, the description is quite complete: it explains the input, the routing behavior, the output format (structured answer with stable citation URIs), and provides many concrete examples. The main gap is the lack of boundary-setting against sibling variations like ask_pipeworx_beta and ask_pipeworx_grounded, but an agent can still call this tool correctly.

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

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

Schema coverage is 100%, with all parameters documented as aliases for the single natural-language question parameter. The description reinforces the expected input with trigger phrases and examples, but these largely overlap with the schema examples. It does not add significant new constraints or format details 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 clearly identifies a specific behavior: ask a factual question in natural language, have it routed to an authoritative data source, and receive a structured answer with citations. It explicitly differentiates from web search and frames the tool as the default starting point, but it does not distinguish itself from sibling variants like ask_pipeworx_beta or 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 gives strong, concrete guidance on when to use the tool: for current/historical data, factual queries about real-world entities, and even cases where web search might also work. It names web search as an alternative to prefer this over, but it does not state when not to use it or how it compares to nearby siblings such as deep_research or ask_pipeworx_grounded.

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 valuable behavior: no candidate routing is currently active, the last was retired on a specific date, results are compared against the stable router, and there is no fallback because this is itself a complete working router. This is rich, honest 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 compact and front-loads the core identity, then gives current status, usage guidance, and a clarifying note about fallback. Every sentence adds information and none is filler.

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

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

For a beta router variant, the description covers identity, current state, usage relationship to ask_pipeworx, comparison purpose, and operational guarantee. No output schema exists, but the description's reference to the identical response shape as ask_pipeworx is sufficient given the explicit sibling relationship.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description only adds that the tool takes 'same arguments' as ask_pipeworx, which is useful context but not parameter-level meaning beyond the schema.

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

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

The description clearly identifies this as a beta version and an identical universal router to ask_pipeworx, with the same 5,798 tools and response shape. It names the parent sibling and makes clear that it is a full working router, not a stub or fallback.

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 it exactly like ask_pipeworx 'when you want the newest routing,' which gives a clear selection condition. It does not explicitly contrast against ask_pipeworx_grounded or list when to avoid this variant, so it stops just short of full when/when-not guidance.

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

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

Beyond the annotations, the description discloses key behavioral traits: the tool routes across 5,798 tools, fills arguments, fetches data, and extracts using only the tool result. It details both success and refusal return shapes, including specific refusal_reason values. The extra LLM call cost is also disclosed. No contradiction with the readOnlyHint/idempotentHint annotations exists.

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

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

The description is information-dense but every sentence earns its place: purpose is front-loaded, behavioral details follow, and usage guidance with cost tradeoff closes it. There is no filler or repetition of schema content. The length is justified by the tool's complexity and the absence of an output schema.

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

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

For a complex tool with no output schema, the description fully compensates by specifying the return shape on success and failure, refusal reasons, the grounding constraint, and the cost relative to ask_pipeworx. It also anchors the tool in the sibling family by saying it uses the same routing as ask_pipeworx. An agent has enough information to invoke it correctly and interpret results.

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

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

Schema description coverage is 100%, with the question parameter and all aliases already documented in the schema. The description adds context that the question routes across many tools and must be answerable from source data, but it does not add syntactic or format details beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly identifies a specific mode: a hallucination-resistant, grounded answer mode that extracts answers only from the fetched tool result. It distinguishes itself from ask_pipeworx by emphasizing evidence-backed extraction and explicit refusal behavior. The verb 'extracts' and the resource 'answer mode' give a concrete, non-tautological 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 explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements). It also provides a clear alternative recommendation: prefer ask_pipeworx for casual lookups, citing the one extra LLM call cost. This gives the agent direct decision criteria.

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

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

The description goes far beyond the readOnly/idempotent annotations, revealing fan-out strategies, resolver confidence contracts, news fallback handling, low-confidence short-circuiting, closed-market detection, spread illiquidity warnings, and cancellation-rule risk. This extensive behavioral disclosure aligns with the annotations and provides critical operational context for an agent.

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

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

The description is long but incredibly information-dense, with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that aid navigation. It front-loads the core purpose in the first sentence, though some detail could be trimmed without losing essential guidance, so it is not maximally concise.

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

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

Despite having no output schema, the description thoroughly documents response shapes, resolver contract, parent_event extraction, news fields, safety mechanisms, and resolution-rule risk. This makes the tool's behavior fully predictable and complete for an agent, even without structured output definitions.

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

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

The input schema already provides 100% coverage with detailed descriptions for all three parameters, so the baseline is 3. The description adds context through fan-out examples and response shapes, but it does not introduce new parameter-level semantics beyond what the schema already conveys.

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 statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on Polymarket bet research and one-call aggregation, with specific examples of input formats and output categories.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear usage scenarios. It does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5, but the 'Use for' guidance is unambiguous and practical.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds context about data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and returning citation URIs. This enriches beyond 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?

The description is longer than average but each sentence provides value: trigger phrases, use-case directive, per-type data details, sorting behavior, and output format. It's well-structured and front-loaded with the core purpose.

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

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

For a tool with only 2 parameters and rich annotations, the description covers the tool's purpose, usage, data sources, sorting, and return format, making it complete for selection and invocation. No output schema exists, but the description mentions paired data + citation URIs, which is sufficient.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this by detailing type-specific data pulls and providing examples (e.g., AAPL, MSFT, ozempic, mounjaro). This adds semantics about what each enum value does 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 trigger phrases and explicitly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It clearly distinguishes from siblings by naming entity types and contrasting with sequential single-pack lookups.

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

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

Provides an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and explains when to use with concrete metrics for each type. It lacks an explicit 'do not use when not comparing' statement, but the context is clear.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavior beyond that: parallel facet decomposition, routing to 5,798 tools, explicit gaps[] with never-invented findings, contradictions[] for standard/thorough, fetchable pipeworx:// citation URIs, semantic excerpting instead of head-truncation, latency expectations, and auth/tier restrictions. This all aligns with the annotations; no contradiction.

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

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

The description is dense and front-loaded with the most decision-critical fact: account required, and use ask_pipeworx if not signed in. Every major behavior is stated, but it is a long wall-of-text paragraph with some redundancy against the scheam's depth description (e.g., contradictions[] and gap-recovery). A structured list would improve scannability while preserving the content.

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

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

For a complex research tool with no output scheam, the description fully covers input syntax, output shape, failure representation (gaps[]), contradiction detection, citation fetchability, latency, auth/tier restrictions, and usage boundaries. An agent has enough information to decide whether to call it, how to call it, and what to expect back.

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?

Scheam coverage is 100%, so the baseline is 3. The description adds value beyond the scheam by giving example multi-part questions, tying the 'thorough' depth to a paid plan, explaining why depth levels matter ('multi-step questions resolve in one call'), and providing latency expectations per depth. It doesn't redefine the parameters, but it enriches the practical meaning of question and depth.

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

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

The description names a specific action — multi-source grounded research across Pipeworx's structured data sources — and specifies the output format (findings packet with citations, gaps, contradictions). It explicitly contrasts with open-web search and with ask_pipeworx, so an agent can distinguish it from siblings without opening schemas.

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

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

The description gives explicit usage boundaries: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx instead', and 'If you are not signed in, use ask_pipeworx'. It also states the account/tier prerequisite, making the selection criteria 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?

Annotations already declare read-only and idempotent behavior. The description adds meaningful behavioral detail: it returns top-N tools with names, descriptions, and full input schemas, and each result is ready to call directly without a second schema lookup. This goes beyond the annotations and helps the agent know exactly what to expect from the 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 three sentences, front-loaded with the core purpose and usage. The domain list is long but highly useful for an agent deciding whether to call this tool. Every sentence contributes value with no redundancy or filler.

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

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

There is no output schema, but the description compensates by specifying return contents (names, descriptions, full input schemas, examples), the top-N concept, and direct callability. Combined with rich annotations and a complete input schema, the description gives the agent everything needed to understand when and how to use the tool.

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

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

The input schema provides 100% parameter coverage, including aliases for `query` and the `limit` default/max. The description does not add parameter-level detail, but it doesn't need to because the schema already documents everything. Baseline 3 is appropriate.

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

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

The description states a specific verb-resource pair ('Find tools') and elaborates with concrete domains and tasks (SEC filings, FDA drugs, stocks, etc.), making it unmistakably distinct from sibling tools. It clearly frames discover_tools as a browsing/search/discovery tool rather than a specific data-access or analysis tool.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and adds 'Call this FIRST when you have many tools available.' It also gives a when-not boundary: 'not just one answer,' steering the agent to use this tool when exploring options rather than seeking a single direct result. This is strong actionable guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds rich behavioral context beyond that: parallel fan-out across many sources, source_used/sources_failed semantics, USPTO soft-fail behavior, FDA section legitimately returning none for small-molecule-only companies, and empty sections meaning real 'no data'. No contradiction with the annotations exists.

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 nearly every clause earns its place by explaining output fields, source behavior, or routing precedence. It front-loads the most decision-relevant information: usage intent, always-prefer guidance, and accepted input forms. Minor redundancy with the schema descriptions and the somewhat wall-of-text format keep it from a 5.

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

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

Because there is no output schema, the description correctly carries the full burden of explaining the return shape, including cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also explains what counts as expected emptiness versus failure. An agent has enough information to invoke this tool and correctly interpret its results in context.

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

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

The input schema already describes both parameters and covers them 100%, so the baseline is 3. The description adds operational meaning: type accepts 'company' or 'ticker' interchangeably, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR. This extra detail justifies a score above the baseline, though much of it overlaps with the schema.

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

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

The description states a clear mission: produce a full cross-source profile of a US public company in one call, with concrete user-phrase examples that map to it. It distinguishes itself from single-pack SEC/XBRL/news lookups by explicitly saying it is preferred for holistic views. This goes well beyond a tautology and gives the agent a specific resource and scope.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when the user asks for a holistic view, providing clear selection guidance. It also documents when a private company yields resolved:false with a notes line, helping the agent interpret edge cases rather than treating them as hard errors. No when-not-to-use gaps remain for the intended main use case.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description need not repeat them. It adds useful context about what is deleted (memory by key) and the motivation for deletion (clearing sensitive data), without contradicting any annotations.

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

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

The description is only two sentences, each earning its place with concrete guidance. It is front-loaded with the action and resource, followed by use cases and related tools, 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?

For a simple 1-parameter destructive tool with no output schema, the description covers the action, key semantics, and usage scenarios. It could mention return values or error behavior, but the annotations and simplicity make this adequate.

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

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

Schema coverage is 100% for the single 'key' parameter, which is well-documented as 'Memory key to delete'. The description enhances this by noting the key refers to a 'previously stored memory', implying it should exist from a prior remember call.

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 'Delete' with a clear resource 'previously stored memory' and method 'by key'. It clearly distinguishes itself from sibling tools like remember (store) and recall (retrieve).

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

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

Provides explicit when-to-use conditions: 'context is stale, the task is done, or you want to clear sensitive data'. Also mentions paired tools 'remember and recall', giving related alternatives for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about the operational flow (fetches page, extracts title/description/key links) and the output format (single text blob). It does not contradict annotations and provides behavior beyond what annotations cover.

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

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

The description is concise and front-loaded, with two sentences and a short list of use cases. Every sentence adds meaningful information, and there is no redundancy or filler.

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

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

For a simple 2-parameter tool with no output schema, the description covers the input (any URL), the process (fetch, extract, emit), the output format (llms.txt markdown blob), and the use cases. It is fully complete for an agent to understand when and how to invoke the tool.

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

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

Both parameters are fully described in the schema (100% coverage). The description does not add additional parameter-specific semantics beyond what the schema provides, but it implicitly reinforces the tool's purpose. 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 states a specific action ('Generate a production-ready llms.txt file for any URL') and details the process and output format. It is clearly distinct from sibling tools, which focus on AI visibility checks, research, or other tasks, with no ambiguity about what this tool does.

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

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

The description provides explicit use cases: indexing a client's site, drafting llms.txt for a project, and auditing a competitor's AI visibility. It does not mention when not to use the tool or name alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, covering the safety profile. The description adds useful context about the return contents (fields, geometry type, count, capabilities) but does not disclose potential performance implications of counting records or other behavioral traits.

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

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

The description is a single, tightly packed sentence that front-loads the action and resource, then lists the specific output components. Every word earns its place with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description thoroughly covers what the tool does, what it requires (URL), and what it returns. Combined with the strong annotations, the description is complete for an agent to use 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?

With 100% schema description coverage for the single 'url' parameter, the schema already documents its meaning. The description simply says 'by url', adding no significant semantic detail beyond what is already in the input 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 ('Get') and resource ('ArcadGIS Feature/Map Service layer's schema'), and enumerates the exact information returned (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like query_layer, which would query data rather than schema.

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

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

The description clearly implies the tool is for retrieving layer schema information by URL, providing clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it (e.g., for querying actual features), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context by listing return fields and mentioning that it's scoped to the caller. It doesn't discuss the include_inactive parameter behavior, but the schema covers that. This goes beyond annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the purpose, and includes return fields and usage guidance without any fluff. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, and return fields. It is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and the single parameter include_inactive is fully described in the schema. The description's mention of 'active subscriptions' implies the default behavior but adds no additional 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 lists the caller's active subscriptions, with specific fields returned, distinguishing it from mutation siblings like subscribe and unsubscribe.

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

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

Explicit usage guidance is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use it and implies 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that filing without an account returns a claim_token, describes the read-mode behavior when passing the token, and exposes rate limits ('5 per identifier per day'). It also clarifies the tool is free and doesn't count against quota, adding operational context not available in structured metadata.

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

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

The description is longer than ideal but every sentence adds value: it front-loads the purpose, then systematically covers use cases, exclusions, token-based retrieval, rate limits, and pricing. There is no filler, though it could be trimmed for brevity.

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 is complete for a tool with no output schema: it explains both operational modes (new feedback and status retrieval), the type taxonomy is mapped to concrete situations, and context fields are optional. It also addresses edge cases like wrong server and gives a fallback for identification. This fills all gaps left by annotations and schema.

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

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

Even though the schema describes all parameters (100% coverage), the description adds meaningful guidance: for `message` it says to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts; for `claim_token` it explains the two-step flow of submitting then reading the result. This contextual instruction goes beyond the schema's field formatting details.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by emphasizing it is only for Pipeworx-served tools, unlike other tools like ask_pipeworx.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.'). It also provides a verification method ('Not sure? Pipeworx tool names are the ones this connection lists.')

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the bar is lower. The description adds valuable context beyond annotations: data is derived from 'CF analytics-engine', contains 'no PII', and is 'Cached 5min-1h depending on window'. This gives the agent useful operational 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 concise yet informative, front-loading the core output, then providing a bulleted list of use cases, and ending with important data-source and caching details. Every sentence serves a purpose without fluff.

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

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

For a simple tool with one optional parameter, rich annotations, and no output schema, this description covers the return values (top tools, packs, call volume), use cases, and operational details. It is thorough enough for an agent to invoke correctly without needing additional documentation.

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

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

Schema coverage for the single 'window' parameter is 100%, including an enum and a description of behavior. The tool description repeats the window options but doesn't add substantial new semantics beyond what the schema already provides. 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 opens with 'What other AI agents are calling on Pipeworx right now' and concretely states that it 'Returns the top tools, top packs, and total call volume', giving a specific verb and resource. This clearly distinguishes it from sibling tools like 'discover_tools' or 'entity_profile' by focusing on aggregated usage trends.

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

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

The 'Useful for' section provides three explicit scenarios for when to invoke this tool, such as discovering hot data sources or confirming a canonical tool. It lacks explicit when-not-to-use guidance or named alternative tools, but the context is clear enough for an AI agent to make an informed choice.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral context: how partition checks work, placeholder filtering, semantic similarity thresholds, fill-check integration with live CLOB depth, and the exact meaning of realizable_edge <= 0.

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

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

Though lengthy, the description is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) and every sentence adds value. It leads with the core purpose and then logically expands into modes, caveats, and edge cases.

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 return fields (opportunities[], partition_check), internal fill-check sub-calls, edge cases (placeholder slugs, low similarity, thin legs), and refers to sibling tools for custom sizing. This is highly complete given the complexity and lack of an output schema.

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

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

Schema descriptions are already rich (100% coverage), but the tool description goes further by providing concrete example slugs ('fed-decision-may-2026'), explaining which mode each parameter triggers, and describing the semantic anchor and partition filter behavior tied to those parameters.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes among three modes (default scan, event, topic) and differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly recommends when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It also references an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and clarifies when not to trade (realizable_edge_pp <= 0).

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/idempotent annotations, the description discloses numerous behavioral traits: the 24h-move warning ('your edge may already be in the price'), the parent-level kelly_fraction_half=0 design for partition arbs, the rare-by-design nature of concentrated longshots, the caching at KV level keyed on knobs, and the diagnostics structure for empty segments. It also clearly explains that slippage is subtracted before ranking.

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

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

The description is long, but it is structured with clear sections (model families, knobs, response top-level, diagnostics) and is front-loaded with the core purpose. Each sentence adds substantive information, and the length is warranted by the tool's complexity. It loses one point for being a dense wall of text that could be broken up more cleanly.

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 must explain the return structure, and it does so thoroughly: 'EVERY OPPORTUNITY carries edge_pp_net...', 'RESPONSE TOP-LEVEL: by_segment{...}, fed_candidates/fed_note, and _diagnostics{...}' plus diagnostics funnel counters. It covers edge cases (Fed bets, placeholder filters, empty segments) and caching, making it complete for an agent to understand behavior without additional documentation.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value beyond the schema by explaining the purpose and interplay of knobs: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly' and clarifies the nuanced behavior of min_kelly vs min_partition_leg_kelly. This adds context not present in the schema.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies scope with 'what should I bet on today' and details three model segments, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker through its unique data-source and response structure.

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

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

The description clearly states the use case: 'agents discover opportunities without paging hundreds of markets.' It also provides an explicit limitation guidance, excluding Fed bets from ranking with reasoning about unreliable signal without paid data. However, it does not name alternative sibling tools or provide explicit when-not-to-use instructions beyond that, so it stops short of a full 5.

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

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

Annotations declare read-only/idempotent, but the description adds critical behavioral context: snapshots are written only on cache-miss (gaps mean no scan), a 60-day TTL bounds history, and decay is computed from daily closes, not intraday. This goes well 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-organized into Args, RESPONSE, and LIMITS sections. Every sentence delivers useful information, and the structured format 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?

With no output schema, the description fully explains the response format: tracked[] with time-series, first_seen, trend, decay; expired[] with lifespan; snapshot_dates[]. It also covers limitations (TTL, snapshot gaps, daily closes). This is complete for a complex telemetry tool.

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

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

Schema coverage is 100% with good parameter descriptions. The description reinforces defaults but adds semantic nuance: 'window (snapshot family)' clarifies that the parameter selects a family of snapshots, not just a time window. This adds 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 and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from siblings like polymarket_edges by focusing on time-series behavior ('how long has this edge existed and is it shrinking?').

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

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

The description gives clear context for when to use this tool: to evaluate edge persistence/decay, with a concrete example of fresh vs. old wide edges. It does not explicitly name alternatives or exclusions, but the context makes the use case clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond that by detailing behavior: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict (clean|degraded|cannot_fill),' plus basket-mode details like thin_legs and forced_directional_risk. This adds 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, with clear mode sections (SINGLE-MARKET/BASKET) and a strong front-loaded purpose. While long, every sentence earns its place given the tool's complexity. Minor deduction for wall-of-text formatting that could benefit from bullet points, but content is efficient.

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

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

For a complex two-mode tool with no output schema, the description is remarkably complete. It enumerates return fields, explains verdict values, interprets size_usd differently per mode, and warns about failure modes. The only minor omission is error handling for missing parameters, but 'REQUIRES one of' covers that. Extremely comprehensive.

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

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

Schema covers 100% of parameters with basic descriptions, but the tool description enriches them: 'size_usd' is explained as 'max spend on buys, target proceeds on sells' in single market and 'settlement notional S (shares per leg)' in basket mode. It clarifies 'side' defaults per mode and the one-of requirement for market/event, adding meaning beyond the schema.

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

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

The description opens with a specific verb-resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' naming the exact sibling tools and 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?

Usage guidance is explicit: 'USE THIS before acting on...' tells when to use, and the two modes (single-market vs basket) explain parameters and interpretation. It also provides rationale by warning that 'theoretical overround on thin books is not capturable' and that partial fills create unhedged positions, giving clear context and implied exclusions.

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

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

Annotations already mark it read-only and non-destructive, and the description adds substantial behavioral disclosure: the token-overlap matcher, safety codes and their meanings, the fact that unknown metric_type/match_subtype legs are never paired, the fees_note that spreads are gross, and the temporal_alignment null semantics. 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 deliberately organized (modes, response, safety fields, codes, fee note, counters) and front-loads the purpose. Some repetition of warnings (e.g., EITHER mode, pre-mapped not tradeable) could be trimmed, but every major section adds operational value for a complex tool.

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

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

For a tool with no output schema and a complex response, the description fully covers return semantics, safety fields, flag meanings, fee caveat, skipped-leg counters, and limitations. An agent has enough information to call it correctly and interpret the result safely.

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 three parameters at 100% coverage. The description adds valuable semantics beyond the schema: topic is an enumerated set of macro shortcuts, explicit ticker/slug override the topic-mapped sides, and both modes run the identical matcher with the same caveats.

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 identifies both the resource and the computation. The two modes further scope what it operates on, and the 'same resolving question' qualifier distinguishes it from generic arbitrage or edge 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 gives clear context for how to invoke it: either pick a pre-mapped topic or supply an explicit kalshi_event_ticker and polymarket_event_slug, and it warns that most pre-mapped topics currently return a compatibility_warning and that pre-mapped does not mean tradeable. It stops short of naming sibling tools or stating explicit when-not-to-use conditions, hence not 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 annotations already indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds useful context about returns ('attribute rows (and geometry)') and sampling. However, it does not disclose potential pitfalls like service availability, pagination limits beyond schema, or performance considerations. The annotation coverage reduces the burden, but the description could still add more value.

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 extremely concise—three sentences that cover purpose, parameters, return type, and a usage tip. Every sentence adds value with no redundancy or filler.

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

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

Given the tool's moderate complexity, the schema includes examples and full parameter descriptions, and annotations cover the safety profile. The description adds the return type and sampling tip, making it fairly complete. However, it could briefly mention limitations (e.g., only queries a single layer at a time) or clarify the relationship to sibling tools like search_within, so it's not a 5.

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 a meaningful usage pattern beyond the schema: 'Use where="1=1" + out_fields="*" to sample.' This practical hint helps the agent understand how to use the parameters effectively, exceeding the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Query an ArcGIS Feature Service / Map Service layer by its url (from search_datasets).' This specifies a distinct verb (query) and resource (ArcGIS layer), and the mention of 'from search_datasets' differentiates it from sibling tools like search_datasets and layer_info.

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 by referencing 'from search_datasets' and provides a practical tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly state when to avoid this tool or mention alternatives like search_within, leaving some room for interpretation.

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

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

Annotations already declare readOnly/idempotent/non-destructive. Description adds scoping behavior ('Scoped to your identifier') and the dual mode of operation (retrieve vs list all keys), which are useful beyond annotations.

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

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

Two concise sentences that front-load the core action, then add usage context, scoping, and tool relationships. Zero wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and related tools. It doesn't detail return format, but the behavior is unambiguous from the description.

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

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

Schema coverage is 100% and the property description already explains the 'key' parameter. Description adds minimal value by clarifying the key was previously saved via 'remember', but the schema carries most of the 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?

Description uses specific verbs ('Retrieve', 'list') with a clear resource (previously saved values via 'remember'). It explicitly distinguishes from sibling tools by naming 'remember' and 'forget' as counterparts.

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

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

Clearly states when to use (look up context stored earlier) and even suggests an alternative ('without re-deriving it from scratch'). Explicitly mentions pairing with 'remember' and 'forget' for related operations.

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

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

Annotations already declare read-only and idempotent, but the description adds the critical nuance that mark_read:true mutates state by flagging returned events as read, affecting future calls. It also discloses the event payload structure (source, citation_uri, raw payload) and that polling works fine, which goes beyond annotation data.

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 purpose, then filtering, then side-effect/alternative. No wasted words; each sentence carries distinct information.

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

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

For a tool with no output schema, it specifies the returned event fields (source, citation_uri, payload). It also covers filtering, limit/ordering via mark_read semantics, polling, and the alternative HTTP endpoint, making it 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 covers all five parameters, so baseline is 3. The description adds meaningful context by providing a type example ('sec_8k'), explaining mark_read's effect on subsequent calls, and clarifying the 'since' timestamp format as ISO.

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 verb 'Pull' with 'fired events from your subscription feed' clearly states the operation and resource. It distinguishes itself from siblings like list_subscriptions by focusing on delivered alert events rather than subscription management.

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 notes that the same feed is also available via GET registry.pipeworx.io/alerts.json for scripts/dashboards, implying this tool is for interactive/agent use. It also explains when to use mark_read and filtering for incremental polling, though it doesn't name explicit sibling 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 readOnlyHint and idempotentHint annotations, the description discloses the fan-out to SEC EDGAR, GDELT→GNews fallback (when rate-limited or 5xx), and the USPTO soft-fail due to PatentsView API sunset. It also describes the return structure, adding valuable 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?

The description is appropriately sized for a multi-source aggregation tool and front-loaded with use-case examples. Every sentence adds operational value (sources, fallback logic, date formats, return structure, alternative tool), with no extraneous content.

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

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

With no output schema, the description adequately explains the return values (changes[] grouped by source, total_changes, pipeworx:// URIs). It also covers parameters, sources, failure modes, and the alternative tool, making it complete for the tool's complexity and openWorldHint annotation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the `since` formats (ISO date or relative shorthand) and entity identifiers already in the schema, but adds little new meaning beyond what is documented in the input 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 defines the tool as a change feed for a company in a given time window, with concrete examples of queries ('What's new with X'). It distinguishes itself from the sibling entity_profile by explicitly stating that entity_profile is for static profiles, making the 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 provides explicit use cases with examples and directly says when to use entity_profile instead ('Use entity_profile instead when you want the static profile...'). It also explains the parallel call behavior and the fallback logic, giving clear guidance on invocation and expectations.

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: memory is scoped by identifier, persists across sessions for authenticated users, and has a 24-hour expiry for anonymous sessions. These are not in the annotations and help the agent understand side effects and limitations.

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

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

The description is well-structured, front-loaded with purpose, and each sentence adds distinct information (usage, storage, persistence, related tools). There is no redundancy or filler.

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

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

For a simple key-value store tool, the description covers purpose, usage, persistence details, and integrations with sibling tools. It fully addresses the tool's behavior and context, requiring no further clarification.

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

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

Schema coverage is 100% with descriptions for both key and value, so the baseline is 3. The description elevates this by providing concrete examples ('subject_property', 'target_ticker') and clarifying that the value can be any text, adding semantic guidance beyond the schema.

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

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

The description states precisely what the tool does: 'Save data the agent will need to reuse later.' It identifies the verb (save), the resource (data), and the purpose (reuse later), and distinguishes from siblings by explicitly pairing 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?

Provides clear when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also explains when memory persists (authenticated) vs. expires (anonymous 24h), and mentions complementary tools (recall, forget).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral detail: the internal cascade through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, non-assertion and returning figi_candidates on ambiguity, and explicit labeling of unresolved identifiers. This goes well beyond the annotations and informs the agent about side-effect-free yet multi-step resolution.

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 front-loaded with illustrative queries and the primary rule, and it is organized with SUPPORTED TYPES and enrichment sections. It is long, but nearly every sentence adds useful behavioral or semantic detail. Some repetition exists among the example phrasings, which slightly reduces conciseness.

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 covers the return behavior sufficiently: which identifiers are returned, how unresolved items are reported, what happens on ambiguous matches, and what to expect during upstream outages. For a complex entity-resolution tool with two parameters, this is complete enough for an agent to call 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?

Schema coverage is 100%, so baseline is 3, but the description adds high-value semantics for both parameters. It explains the type enum in depth, including behavior per type, and gives critical value-format guidance for bonds (exact issuer string, not the noun phrase). This is essential information that the schema description alone does not convey.

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

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

Purpose is explicitly stated: resolve a user-spoken name to canonical/official identifiers that other tools require. Multiple example phrasings make the intent unmistakable, and the opening line "resolve a user-spoken NAME to the canonical/official identifiers" is specific about the verb and resource. The tool is clearly distinguishable from siblings like entity_profile, which likely consumes the identifiers produced here.

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 FIRST whenever you have a name but need an ID," providing a clear trigger condition. It also explains how the tool replaces 2-3 manual lookups. However, it does not name specific sibling tools to prefer when an ID is already available, so the when-not guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by revealing that it delegates to ai_visibility_check, ranks results, and returns a ranked list with specific fields. This goes beyond annotations without contradicting them.

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

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

Three sentences, each earning its place: the first states the core function, the second describes the mechanics and output, and the third gives a concrete use-case example. No wasted words, front-loaded with purpose, and highly scannable.

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

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

With no output schema, the description compensates by naming the return elements ('ranked list with score, confidence, signal density per entity'). It also provides real-world context. It could go further by detailing edge cases (e.g., what happens if an entity fails to probe), but given the annotations and schema coverage, this is sufficiently complete.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description enhances this by explaining the entities array structure: 'First entry treated as the "subject" for narrative; rest are competitors'. It also clarifies that models and _apiKey are for probe configuration, adding meaning 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 clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side'. It specifies the method (probes with ai_visibility_check, ranks by score) and the output (which is most/least recognized). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides explicit use-case context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"'. It also implies the relationship to ai_visibility_check by mentioning it as the probing mechanism. However, it doesn't explicitly state when not to use it or name alternative tools for single-entity checks, 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 read-only, idempotent, open-world annotations, the description discloses valuable runtime behavior: it fans out across two external services, partial failures degrade gracefully, and the first bundlephobia measurement can take 5-30s with a sources_failed field to indicate timeouts. This is more than the annotations alone provide, covering latency and partial success scenarios. It stops short of mentioning potential rate limits or authentication needs, but the additional context is strong.

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 front-loaded with the core purpose, followed by usage, return format, ecosystem scope, and caveats. It is longer than the two-sentence ideal, but every sentence contributes distinct, non-redundant value, such as the timing note and failure handling. It earns a solid 4 for structure and economy.

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

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

With no output schema, the description fully covers return values by naming the summary block fields, per-advisory details, links, and alternative versions. It also addresses ecosystem limitations and error behavior (bundlephobia timeout, sources_failed). Combined with the existing annotations and input schema, this gives an agent complete context to select and invoke the tool correctly.

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

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

The input schema already has 100% description coverage for both parameters, including scoped package support and defaulting behavior. The tool description does not add any new parameter meaning beyond what the schema states; it simply references the concept of checking a package and version. Given the high schema coverage, the baseline score of 3 is appropriate.

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

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

The description opens with a specific, action-oriented phrase: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly states the tool checks npm packages across deps.dev and bundlephobia, and it distinguishes itself from sibling research tools by focusing on npm package viability. The returned fields are enumerated, making the tool's scope unmistakable.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion boundary: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' directing users to an alternative for non-NPM ecosystems. This is clear when-to-use versus when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the return format (name, summary, record_count, owner/org, Feature Service URL) and the workflow, providing some value beyond annotations. However, it does not disclose page size, error handling, or behavior in no-result cases, so the description adds only modest behavioral context beyond the structured hints.

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

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

The description is two sentences. The first sentence states the purpose concisely; the second explains the return structure and next steps. Every sentence earns its place, with no fluff or redundancy. 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?

The tool has three optional params, no output schema, and strong annotations. The description covers the tool's purpose, output, and integration with downstream tools. It does not explain edge cases like empty result sets or rate limits, but for a simple discovery tool with good schema and annotations, the description is sufficiently complete.

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

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

The input schema covers 100% of parameter descriptions with examples for query and limit, and a clear definition for org_id. The description reinforces the keyword search intent and examples, but adds no new parameter-specific meaning beyond what the schema already provides. With complete schema coverage, a 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 searches Town of Oro Valley GIS open geospatial datasets by keyword, with specific examples (parcels, zoning, public works, city services). It also distinguishes the tool from siblings by explaining it returns dataset metadata and URLs for use with query_layer/layer_info, establishing a clear discovery role.

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

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

The description provides clear context for when to use this tool: to find datasets before querying them. It explicitly points to query_layer/layer_info as the next steps for using the returned Feature Service URL, implying the appropriate workflow. However, it does not explicitly state when not to use it or contrast with other search-like siblings, so it lacks full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output includes character offsets and similarity scores for verification.

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

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

The description is compact yet information-dense, with three sentences covering core function, usage condition, pairing, and technical details. It is front-loaded with the purpose, and every sentence contributes meaningful value without unnecessary repetition.

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

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

Despite lacking an output schema, the description fully explains what is returned (top-N passages with character offsets and similarity scores), the acceptable input type, the truncation cap/flag, and how the tool integrates with ask_pipeworx_grounded. This is comprehensive enough for an agent to decide when and how to use it.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description enriches semantics by providing real-world examples (SEC 10-K, article) and explaining the output's character offsets and similarity scores, which directly relate to the limit parameter. It also adds the truncation behavior beyond the schema's max.

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

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

The description explicitly states the tool 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K body, article, long tool result). It clearly distinguishes from siblings by emphasizing search within an already-fetched text and contrasts with ask_pipeworx_grounded.

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

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

It provides a clear usage condition: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also mentions pairing with ask_pipeworx_grounded, indicating a complementary workflow, but does not explicitly state when to prefer alternatives over this tool.

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

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

The description contradicts the idempotentHint=true annotation. It says 'Returns the new subscription id,' implying each call creates a distinct subscription, which is not idempotent. This is a serious inconsistency. Although the description otherwise richly discloses behaviors (OAuth requirement, SMS cap, webhook auto-disable, secret returned once), the contradiction forces a score of 1.

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

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

The description is dense but every sentence earns its place. It is front-loaded with the main action and return value, then systematically covers requirements, supported types, and delivery options. No fluff or redundancy.

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

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

Given the tool's complexity (nested objects, no output schema), the description is exceptionally complete. It covers prerequisites, return value, side effects (persistence), delivery constraints (SMS cap, webhook auto-disable), and even error-prone details like the one-time webhook signing secret. The only issue is the idempotency contradiction, which is a behavioral transparency problem, not a completeness 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?

While the schema covers 100% of parameters, the description adds substantial meaning: it gives concrete examples for each subscription type (e.g., items:["5.02"] = officer change), explains delivery channel requirements (verified phone, 10/day cap), and details webhook HMAC signing. This goes far beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (create), the resource (subscription), and the return value (new subscription id). This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit prerequisites (requires Pipeworx OAuth account), supported subscription types with examples, and delivery channel details. It also differentiates from pulling via recent_alerts or the public feed, guiding the user on when to subscribe vs. when to pull.

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. The description adds valuable behavioral context beyond annotations: the output includes 'the exact tool + argument shape' and is 'drawn from the live catalog of thousands of tools.' No contradiction with annotations.

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

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

The description is front-loaded with example queries, then efficiently explains purpose, output, invocation, and usage timing. Although long, every sentence adds relevant information, and the category list is compactly integrated. 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?

With one optional param and no output schema, the description fully covers the tool: what it returns (category-bucketed examples with tool+argument shapes), when to use (first connection/onboarding), how to call (with/without topic), and the dynamic nature ('live catalog'). No important gaps.

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

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

Schema coverage is 100% with a well-described optional `topic` param. The description adds semantic value by giving examples ('finance', 'pharma', 'betting') and explaining the behavioral difference between omitting (full spread) vs. passing a topic (focus). This exceeds the baseline.

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

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

The description starts with concrete user intents ('What can I ask Pipeworx?', 'what is Pipeworx good for?'), then clearly states it is the 'onboarding entry point' that 'Returns category-bucketed example questions... each with the exact tool + argument shape.' This distinguishes it from siblings like discover_tools by emphasizing example questions with tool mappings.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to vary invocation (no args vs. topic). It does not mention exclusions or alternatives, but the context is clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds critical behavioral details: ownership enforcement, deactivation instead of deletion, and that historical events remain available via recent_alerts. This enriches the agent's understanding of side effects.

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

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

The description is three concise sentences, with the primary action in the first sentence. It includes only the necessary behavioral details without redundancy or filler.

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

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

For a simple one-parameter tool with no output schema, the description fully covers ownership, behavior, and downstream effects on historical data. It provides sufficient context for an agent to invoke it correctly.

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

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

The schema already fully describes the single 'id' parameter (uuid returned by subscribe). The description mentions 'by id' but doesn't add new semantic meaning beyond the schema, so the high schema coverage keeps this at the baseline.

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

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

The description explicitly states 'Cancel a subscription by id' with a clear verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on the cancellation action, and even clarifies the deactivation behavior.

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

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

The description provides clear context on usage: you can only cancel your own subscriptions, and it deactivates rather than deletes. However, it doesn't explicitly name alternative tools or state when not to use it, so it lacks a full exclusionary guideline.

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?

Despite annotations already indicating read-only, idempotent, and open-world behavior, the description adds crucial semantics: it explains the meaning of 'could_not_verify' (check did not happen, carries verification_error, must not be shown as evidence), the meaning of 'unsupported' (no source coverage), and the internal routing logic. It also notes that it 'replaces 4–6 sequential calls,' which helps the agent anticipate latency and behavior. 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 longer than average but every section earns its place: trigger phrases, usage context, dual-path behavior, output summary, and critical error semantics. It is front-loaded with the most important purpose and usage cues. A slight tightening could remove repetition (e.g., 'confirm or refute' and 'true or false' are similar), but it remains efficient and well-organized for the tool's complexity.

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

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

Given the tool's complexity (2 params, no output schema), the description covers all essential aspects: what the tool does, when to use it, how it routes different claim types, what it returns (verdicts, actual value, citation, reasoning), and the critical distinction between could_not_verify and unsupported. An agent has enough context to select and invoke this tool correctly without needing additional documentation.

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

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

Schema coverage is 100%, providing baseline descriptions for both parameters. The tool description adds value beyond the schema by explaining tolerance_pct's override behavior, default ('implied by wording, capped at 5'), and use case ('set 1–2 for hallucination detection'). It also provides example claims that illustrate the claim parameter format. This is a meaningful addition over 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 explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states it performs 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from siblings by focusing on claim verification with a structured verdict and by describing the two routing paths (SEC EDGAR XBRL vs. grounded pipeline). This is a specific verb+resource+scope that leaves no doubt about what the tool does.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives example user phrasings. It also clarifies the sub-routing for company-financial claims vs. other factual claims. However, it does not explicitly name alternative tools or say when NOT to use this tool, so it's clear but lacks explicit exclusions.

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