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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context beyond that: routing to 5,529 tools, filling arguments, returning stable citation URIs, one fast call, works on every tier. It does not add risk-related details, but the annotation coverage reduces the burden; this is solid context.

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

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

The description is long but front-loaded with the key 'PREFER OVER WEB SEARCH' message. Every sentence carries unique value (examples, alternatives, performance hints). It is structured logically from guidance to usage to escalation paths, earning its length, though it could be slightly tighter.

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 that routes to thousands of sources and has no output schema, the description covers scope, use cases, limitations, examples, and alternative upgrades. It gives a complete picture of when and how to use it, making it robust for an agent.

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

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

Schema coverage is 100% for the required question parameter, but all six parameters are just aliases of the same question. The description adds no deeper parameter semantics beyond restating that it accepts natural language. With high schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to 5,529 tools and returning structured answers with citations. It explicitly differentiates from web search and sibling tools like ask_pipeworx_grounded and deep_research, so it distinguishes within the sibling set.

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 'PREFER OVER WEB SEARCH' guidance, lists trigger phrases, gives concrete examples, and explains when to step up to alternatives (grounded for hallucination-resistance, deep_research for broad questions). This is exemplary usage guidance.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description adds context beyond those: it explains the beta nature, the live testing of routing candidates, the current equivalence to ask_pipeworx, and the fact that it is a full working router with no fallback. This goes beyond the annotation baseline and provides useful behavioral caveats without contradicting the annotations.

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

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

The description is three well-structured sentences, front-loaded with the core purpose. Each sentence is purposeful: the first defines the tool, the second provides current status, and the third clarifies usage and functionality. There is no fluff, and the structure is easy to parse, making it highly concise for the amount of information delivered.

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

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

The description covers the tool's beta status, its current behavior (matching ask_pipeworx), how to use it, and its full functionality. It references the same response shape as ask_pipeworx, which is acceptable given the sibling context, but it does not describe specific return values or error behavior. Given the tool's complexity and lack of output schema, the description is reasonably complete for making an informed decision.

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

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

The input schema fully documents all parameters with 100% coverage, including the required 'question' and its five aliases. The description does not add parameter-level details beyond saying 'same arguments' as ask_pipeworx, which is not directly helpful since ask_pipeworx's schema is not provided. Thus, the schema carries the burden, and the description adds no extra semantic value, meriting the baseline score of 3.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router supporting the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing its experimental edge and the fact that it currently matches ask_pipeworx exactly, making its purpose specific and well-defined.

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 instructs to 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear when-to-use context. It also notes that results are compared against the stable router and that no candidate is active right now, implying the stable router is the alternative. However, it does not explicitly name alternatives for other sibling tools or state exclusionary conditions, so it stops short of a perfect score.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses significant behavioral traits: the exact success return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the extra LLM call cost. This gives the agent a thorough understanding of what to expect and how to interpret refusals.

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 composed of five dense, information-rich sentences, front-loaded with the core value proposition. Each sentence contributes unique data—mechanism, output shape, usage guidance, and cost trade-off—without redundancy or unnecessary filler. It is concise for the complexity it covers.

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 provides a complete contract: the full return structure, refusal reason enums, and failure handling. It also covers performance trade-offs (extra LLM call) and concrete use cases, making it comprehensive for an agent to decide when to invoke the tool and what to expect from 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?

The input schema already fully documents the 'question' parameter and all aliases (q, text, input, query, prompt) with 100% coverage. The description does not add any parameter-specific semantics beyond what the schema provides, so a baseline score of 3 is appropriate. The schema is doing the heavy lifting here.

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 and descriptive phrase 'Hallucination-resistant answer mode for high-stakes reads' and elaborates that it extracts answers using ONLY what the tool result contains. It clearly differentiates from the sibling ask_pipeworx by emphasizing the grounded extraction and explicit refusal behavior, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and contrasts it with the alternative: 'prefer ask_pipeworx for casual lookups.' It also mentions the extra LLM call cost, giving clear decision criteria for choosing between this tool and its sibling.

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

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

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?

The annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, and the description goes far beyond: it discloses latency (15-60s), the never-invented gaps[] behavior, contradiction[] scanning, semantic excerpting instead of head-truncation, citation_uri only when resolvable, and hop recovery differences between depth levels. This rich behavioral context is absent from structured fields and adds significant transparency.

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

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

The description is long but densely packed with essential operational details (account requirements, latency, output packet contents, limitations). It is structured from account note to core function to alternative comparisons to depth specifics. Slight redundancy (gaps[]/contradictions mentioned twice) and a heavy opening sentence prevent a perfect score, but every sentence contributes useful guidance.

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

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

For a tool with no output schema, the description thoroughly covers return semantics: evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also specifies latency, account tiers, and how it differs from open-web search and sibling tools. Given the tool complexity, the context is complete and actionable.

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

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

Schema coverage is 100% with strong descriptions for both parameters, giving baseline 3. The tool description adds context above the schema by explaining practical implications: 'thorough' is paid, 'standard' does gap-recovery and contradiction scan, and 'thorough' chases leads. This enriches the enum semantics beyond the schema's direct wording.

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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition and parallel routing behavior. It clearly distinguishes from sibling tools by naming ask_pipeworx as the alternative for single lookups and current-news topics, and it specifies the tool's unique value: broad/multi-part questions over structured data with citations and gaps[].

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions' and for single lookup or breaking news 'prefer ask_pipeworx'. Also details prerequisites (account/sign-in, paid tier for thorough) and alternatives if not signed in. Depth level explanations clarify which mode suits iterative follow-up needs.

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 declare read-only and idempotent, but the description goes further by disclosing internal fan-out across multiple sources, fallback behavior (GDELT→GNews), and limitations (USPTO sunset soft-fail). No contradiction with annotations.

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

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

The description is long but front-loaded with examples and every sentence adds functional detail. The semi-colon-separated list of return fields is dense but efficient; nothing feels redundant.

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

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

No output schema exists, so the description carries the burden of explaining return values. It enumerates all return fields (cik, recent_filings, fundamentals, patents, news, LEI), including URIs and sorting, plus input constraints and fallbacks. Complete for a multi-source read-only tool.

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

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

Schema covers both parameters with descriptions, but the description adds concrete examples ('AAPL' or '0000320193') and reiterates the names-not-supported constraint with pointer to resolve_entity. This adds practical usage 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 uses specific verbs and resources: 'full cross-source profile of a US public company' with explicit examples of user intents. It distinguishes itself from siblings like compare_entities and resolve_entity by stating it prefers holistically over chaining 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?

Explicitly states when to use: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' Also provides exclusions: names not supported, use resolve_entity first, and notes patent API sunset yielding soft-fail.

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 declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It details response behavior (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning logic, temporal_alignment, skipped_cross_type/subtype counters), and even explains what aligned:false means. It also openly states that pre-mapped topics often return warnings, setting realistic expectations. No contradictions with annotations.

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

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

The description is long (300+ words) but well-structured with capitalized labels (TWO MODES, RESPONSE, SAFETY FIELDS) and bullet-like explanations. Every sentence contributes essential information about behavior, modes, and safety fields. It is front-loaded with the purpose statement. However, it is somewhat dense and could be tightened without losing key details, so it earns a 4 rather than a 5.

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

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

Given the tool's complexity (3 optional parameters, no output schema), the description is remarkably complete. It explains the return structure (prices, top_spreads_pp), conditional warnings (compatibility_warning in two scenarios), temporal alignment semantics, and skip counters. It also clarifies the implications of aligned:false and the rarity of tradeable spreads. No output schema exists, so the description carries the full burden of explaining outputs, and it succeeds thoroughly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by framing the three parameters as two distinct modes (topic vs explicit) and explaining that explicit tickers and slugs override the topic-mapped side. It also lists example topics and reinforces the override behavior, though the schema already contains per-parameter descriptions. The added value is the mode distinction and the caution about pre-mapped topics, which elevates it to a 4.

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

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

The description opens with a specific verb+resource: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." This clearly distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edges by emphasizing cross-venue comparison. It also elaborates on the exact function (spread calculation) and the nuance of equivalent vs non-equivalent bet shapes, leaving no ambiguity 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 provides clear context on when to use the tool: it explains the two modes (topic shortcuts vs explicit tickers/slugs) and warns that most pre-mapped topics return compatibility_warning today, implying caution. However, it does not explicitly contrast with alternative tools (e.g., when to use polymarket_arbitrage instead) or give a clear "when not to use" beyond the pre-mapped caveat. Thus it falls short of a full 5 but is well above merely implied 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?

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?

Beyond annotations (readOnly, openWorld, idempotent), the description reveals key behaviors: identifiers are labelled with their source, unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and LEI/FIGI enrichment degrades gracefully with fallback to EDGAR identifiers. It also discloses that each call cascades through multiple lookup endpoints.

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

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

The description is longer than average but front-loaded with query examples and structured by SUPPORTED TYPES. Every sentence contributes valuable context, though the initial list of example queries is slightly redundant and could be trimmed without loss of meaning.

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

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

With no output schema, the description fully compensates by explaining return characteristics: source-labelled identifiers, explicit `unresolved` field, source coverage (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), and graceful degradation. It also covers both entity types and input variations, making it complete for an agent.

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

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

Even though schema coverage is 100%, the description enriches both parameters: for `type` it details what each enum value returns (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand), and for `value` it gives concrete examples ("AAPL", "0000320193", "ozempic", "metformin") and clarifies accepted formats (ticker, CIK, name; brand or generic).

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: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It provides multiple natural-language query examples and clearly explains supported types (company, drug), distinguishing it from sibling tools by positioning it as the initial ID-resolution step.

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," which establishes a clear when-to-use condition. It also notes that the tool "replaces 2-3 manual lookups," implying it should be the primary choice over sequential lookups. The condition inherently covers when-not-to-use (when you already have the ID).

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.