Arcgis Flagstaff

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. Description adds valuable behavioral details: the default model is free, _apiKey is passed straight to Anthropic, and the response shape includes per-model score, confidence, signals, raw_response plus a combined view. No contradictions.

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

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

The description is compact yet information-dense, front-loading the core function and result format, then adding key config details. Every sentence earns its place with no fluff or repetition of schema content.

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

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

Despite having no output schema, the description explicitly states the return structure and covers key operational aspects (default model, cost implications of _apiKey, example use cases). It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are well-documented. Description adds meaning by explaining the dependency between models and _apiKey, the default when models is omitted, and how context supports disambiguation beyond the schema descriptions.

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

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

Description uses a specific verb ('Probe') and resource ('one or more LLMs') with concrete outcome ('score visibility 0-100 per model'). It clearly distinguishes itself from siblings by focusing on LLM knowledge scoring rather than search or entity resolution.

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

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

Provides clear usage context: default model, optional Anthropic probe with BYO key, and example use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Does not explicitly list when NOT to use or name alternatives, but enough context is given for an agent to decide.

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 behavioral context: routes to a large tool set, fills arguments, returns citations, works on every tier, and makes 'one fast call'. It does not discuss failure modes or limitations, but the annotation coverage is strong and the description enhances understanding 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 long but the length is justified by the need to differentiate from many siblings and provide clear usage guidance. It is front-loaded with the core purpose, followed by examples and escalation paths. Slight redundancy exists (e.g., listing domains twice implicitly), but overall 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 tool with no output schema and many siblings, the description is remarkably complete: it covers when to use, specific alternatives, examples, return format (structured answer with citations), and even edge cases like breaking news. It addresses tier availability and performance. This level of completeness exceeds what is typical for such a broad 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 all parameters described, including aliases, so the baseline is 3. The description adds useful example questions but no new param-level details beyond the schema. It does not compensate for anything missing in the schema, so it remains 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 clearly states the tool's function: it answers factual questions by routing to one of 5,462 tools across 1,419 sources and returning structured answers with citation URIs. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, and names the categories of data it handles, making the purpose unmistakable.

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

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

The description is explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...'. It also names specific alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions) and clarifies breaking-news handling. 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the live-swapping behavior: 'candidate routing improvements enabled live whenever one is under test' and the current status 'No candidate is active right now... matches ask_pipeworx exactly'. This adds useful uncertainty/experimental context, though the response format is only alluded to as 'same response shape'.

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

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

The description is four sentences but each carries distinct value: beta status, behavioral identity, current state, and usage guidance. It is well-structured and information-dense, though slightly verbose in the middle.

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 (universal router with 5,462 tools) and no output schema, the description covers the essential context: experimental nature, identical to stable version, current state, and relationship to ask_pipeworx. It does not detail response shape explicitly, but the sibling comparison compensates.

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% coverage with clear aliases and descriptions for all parameters. The description adds no parameter-specific details beyond mentioning 'same arguments', so it does not significantly supplement the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with an explicit definition: 'identical universal router (same 5,462 tools, same arguments, same response shape)'. It differentiates from the sibling ask_pipeworx by emphasizing experimental candidate routing and current equivalence.

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 direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also clarifies the tool is fully functional ('Falls back to nothing — this IS a full working router'), but it does not explicitly list when not to use it or mention other siblings like ask_pipeworx_grounded.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the refusal behavior (structured refusal_reason codes), the extra LLM call cost, the evidence/verbatim quote return, and the strict grounding to tool results. This significantly enriches the behavioral model 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?

Although longer than average, every sentence provides distinct value: purpose, mechanism, output format, refusal handling, use cases, and cost comparison. The structure is logical and front-loaded with the core concept, earning a high score.

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 supplies complete return-structure details including success and refusal shapes. It also covers cost, use cases, and alternative tools, making it fully sufficient for correct tool selection and invocation.

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 each alias (q, text, input, query, prompt, question) already described in the schema. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode that extracts answers using only tool-results, with explicit differentiation from its sibling ask_pipeworx ('Same routing as ask_pipeworx' but grounded). It specifies the exact function: routing to a tool, fetching data, and extracting an evidence-based answer.

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 whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also explains the cost trade-off, providing a clear decision rule between siblings.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals numerous behavioral traits: fan-out to external data sources in parallel, short-circuiting on low-confidence matches, status codes like 'market_closed_or_inactive' and 'illiquid_wide_spread', cancellation-rule parsing, and fallback/retry behavior for news sources. It also notes blocking behavior and safety guards against sizing phantom matches.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. Every sentence adds specific information, though some details like exact FRED series IDs could be considered extraneous for tool selection. The length is justified by complexity, but it's 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?

With no output schema, the description fully documents response shapes: result.market, result.analysis, result.evidence, resolver contract (match_confidence, match_score, alternatives), parent_event, news fields, and statuses. It covers edge cases (low confidence, closed markets, wide spreads) and cancellation risk. The description is thorough enough for an agent to understand expected results and handle exceptions.

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, including examples and enums. The description doesn't add meaning beyond the schema; it reinforces accepted formats for 'market' but doesn't introduce new semantics. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by mentioning market-vs-model comparison and evidence packets. The explicit use cases 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z' cement its purpose.

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

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

The description gives explicit when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides numerous fan-out examples for different bet types, giving clear context. However, it doesn't explicitly state when not to use this tool versus specific alternatives like polymarket_edges or validate_claim, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds rich behavioral detail: it pulls data from SEC EDGAR/XBRL for companies and FAERS for drugs, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data plus pipeworx:// citation URIs. This goes far beyond what annotations convey.

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

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

The description is dense but well-structured, front-loading trigger phrases and using dashes to separate ideas. While longer than the ideal two-sentence example, every sentence adds value (data sources, edge cases, sorting, return format). It is appropriately sized for the tool's complexity, but slightly compact and could benefit from clearer paragraph breaks.

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 carries the burden of explaining what the agent can expect. It covers the return format ('paired data + pipeworx:// citation URIs'), sorting behavior, data sources, and even an edge case (fiscal year handling). Given the tool's complexity and lack of output schema, this is a complete and sufficient 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?

The schema already covers both parameters (type, values) with descriptions and constraints, so the baseline is 3. The description adds meaningful type-specific semantics: for type='company' it pulls 10-K financials, and for type='drug' it pulls FAERS/trial counts. It also clarifies the range of values (2–5). This extra context pushes the score above baseline.

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

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

The description clearly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs and resources, and explicitly distinguishes from siblings by saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This makes the tool's scope and use case 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 trigger phrases ('Compare X and Y', 'X vs Y'), a clear usage condition ('when comparing entities'), and an explicit preference over alternatives ('ALWAYS PREFER over sequential single-pack lookups'). It also explains the type-specific usage for companies vs. drugs, giving the agent clear guidance on when to invoke 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?

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds crucial context beyond annotations: account/auth requirements, paid tier for thorough depth, latency expectations, the gaps[] and contradictions[] fields, citation_uri fetchability guarantee, and semantic excerpting. 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 exceptionally information-dense; nearly every sentence contributes operational or selection value. It loses a point for being a single dense paragraph where account requirements precede the core purpose, slightly reducing front-loading, but overall it is well structured for the complexity.

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

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

With no output schema, the description fully compensates by describing the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], latency, and depth semantics. The tool is completely self-contained for an agent to decide when and how to invoke it.

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

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

Schema already covers both parameters at 100%, but the description adds significant meaning: it explains depth values (quick=3, standard=5, thorough=8) with hop and contradiction behaviors, and clarifies that the question can be broad/multi-part. This goes well beyond the schema's raw definitions.

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 grounded multi-source research engine that decomposes questions into facets and routes them in parallel across 5,462 tools. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx for single lookups, 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?

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly steers users to ask_pipeworx for single lookups or breaking current-news topics. Also notes account tier requirements, further helping selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about return content — top-N relevant tools with names, descriptions, full input schemas and curated examples — and that results are ready to call directly. This exceeds the baseline but doesn't cover all edge cases like empty results.

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

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

The description is three sentences with a clear hierarchy: purpose, use cases with return details, and strategic instruction. It is front-loaded with the verb and resource, and each sentence earns its place.

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

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

Given the tool's simplicity and rich annotations/schema, the description covers purpose, input, output format, and when to invoke, which is largely complete. However, it doesn't mention behavior for edge cases such as no matching tools or whether the domain list is exhaustive, leaving a small 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?

Schema coverage is 100%; every parameter (query and aliases, limit) has a description. The description reinforces that the query is a natural-language task description but adds no new parameter-specific 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 uses the specific verb 'Find' with resource 'tools by describing the data or task,' clearly defining a discovery tool. It differentiates from sibling tools by positioning itself as the meta-search over all available tools, listing numerous domains.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and even instructs to 'Call this FIRST when you have many tools available.' Provides a concrete list of covered data domains, giving clear context vs alternatives.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: multi-source fan-out, soft-fail for the USPTO PatentsView API (sunset May 2025), GDELT→GNews fallback, and the specific structured fields returned. This goes beyond what annotations offer.

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 dense single paragraph with multiple example prompts that could be condensed. While it is front-loaded with the core purpose, the lengthy list of example utterances adds bulk without adding much semantic value beyond the first few examples.

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

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

Despite no output schema, the description thoroughly enumerates exactly what the tool returns (CIK, recent filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patents sunset, name unsupported). This is complete for a complex multi-source 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 detailed parameter descriptions. The description adds value by giving concrete examples ('AAPL', '0000320193') and reiterating the constraint that names are not supported, which reinforces the schema's meaning.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific example prompts and distinguishes itself from sibling tools by explicitly recommending it over chaining single-pack lookups and referring to resolve_entity for name-only queries.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives exclusions and alternatives: 'names not supported (use resolve_entity first if you only have a name).'

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's 'Delete' simply reinforces this. It adds some context (clearing sensitive data) but does not elaborate on behavior like missing keys or return values. 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?

Three compact sentences, each earning its place: action, usage scenarios, and complementary tools. 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?

Simple tool with full schema coverage and informative annotations. Description covers functionality and usage, and names sibling tools. Lack of output schema means return behavior is unstated, but for deletion this is low risk. Overall complete for the tool's simplicity.

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 the sole 'key' parameter. The description repeats 'by key' without adding further semantic meaning. Baseline 3 is appropriate since schema fully documents the parameter.

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

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

States 'Delete a previously stored memory by key' – a specific verb+resource that clearly distinguishes it from siblings 'remember' and 'recall'. The description is unambiguous about the tool's function.

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

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

Provides explicit use cases ('context is stale, the task is done, or you want to clear sensitive data') and advises pairing with remember/recall. However, it lacks explicit 'when not to use' exclusions, though the sibling reference partially covers alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds process details ('Fetches the page, extracts title/description/key links') and output format ('single text blob ready to drop at site-root/llms.txt'), going 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 compact: a clear first sentence stating the tool's purpose, a second sentence describing the process, and a 'Useful for' list of use cases. No wasted words, and the most important information is front-loaded.

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

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

The tool has a simple 2-parameter schema with full annotations and no output schema. The description compensates by explaining the return format ('single text blob'), the process, and intended use cases. This is complete enough for an agent to understand the tool's behavior and output without additional context.

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

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

Schema description coverage is 100%, so the schema already documents both url and max_links with examples and defaults. The description does not add parameter-specific details beyond the schema, though it implies the url parameter is the target page. This meets the baseline for full 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 uses a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly states the tool's primary function and distinguishes it from siblings by emphasizing AI crawler indexing and use cases like auditing competitor visibility, which relates to sibling tools like scan_competitor_ai_presence.

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

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

The 'Useful for:' section lists three concrete scenarios (client site indexing, drafting own llms.txt, auditing competitor). This provides clear context for when to use the tool, but it does not explicitly mention alternatives or when not to use it, hence not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the concrete data returned (fields, geometry type, record count, capabilities), which is useful context. No contradictions.

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

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

One sentence, front-loaded with verb, no unnecessary words. Efficient and clear.

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

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

One parameter with full schema coverage, annotations cover behavior, and the description lists the key return elements. Output schema is absent but description compensates by naming the outputs. Sufficient for a simple read-only tool.

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

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

Schema coverage is 100% with a detailed description of the url parameter. The description merely restates 'by url' without adding extra semantic detail, so baseline 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 uses a specific verb 'Get' and names the exact resource 'ArcGIS Feature/Map Service layer's schema', listing concrete outputs (fields, geometry type, record count, capabilities). This clearly differentiates it from siblings like query_layer.

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

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

The description clearly implies use when you need layer schema information, and the 'by url' hint explains input. However, it does not explicitly mention alternatives or exclusions, so it lacks full usage guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by listing the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are listed by default, which implies inactive are excluded unless requested.

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

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

Two sentences, front-loaded with the primary action, followed by return fields and a clear use case. Every sentence earns its place with no redundant wording.

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

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

The tool is simple: one optional parameter, no output schema, and strong annotations. The description covers purpose, return format, and use case, making it fully sufficient 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?

The input schema covers 100% of the single parameter (include_inactive) with a clear description. The tool description adds minimal extra meaning, only implicitly noting the default scope (active) which is consistent with the schema's default false. Baseline 3 applies as schema does the heavy lifting.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing and mentions its role in reviewing monitoring before adding more or finding an id to cancel.

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

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

Provides explicit guidance: use to review what you're monitoring before adding more, or to find an id to cancel. This directly references common workflows involving sibling tools (subscribe/unsubscribe) and clarifies when this tool is appropriate.

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

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

Annotations are all false, so the description carries the full burden. It discloses the claim_token workflow, asynchronous nature ('team reads digests daily'), rate limit ('5 per identifier per day'), non-quota status, and the instruction not to paste end-user prompts. This goes well beyond the sparse annotation 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?

Although longer than typical, every sentence earns its place: purpose, use cases, exclusion scope, claim_token mechanism, and rate limits. The first sentence front-loads the core verb, and the structure is logical 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?

Given no output schema, the description sufficiently covers return behavior (claim_token), resolution checking ('read whether it was fixed'), and operational expectations (daily digest, rate limit). An agent has everything needed to invoke correctly and know what to expect.

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

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

While schema coverage is 100%, the description adds meaningful usage context: it maps the 'type' parameter to real-world scenarios ('bug... feature... praise'), instructs to describe issues in terms of Pipeworx tools/packs for the context object, and provides a concrete invocation example for claim_token: 'pipeworx_feedback({claim_token:"pwfb_…"})'. This exceeds baseline schema-only semantics.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool as a feedback channel. It distinguishes from siblings by being the sole feedback tool and enumerating specific feedback types (bug, feature/data_gap, praise).

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug)...' and when not: 'ONLY for tools served by this Pipeworx connection' with the alternative 'file it with that server instead.' Also provides a disambiguation rule: '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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses additional behavioral traits: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This enriches the agent's understanding of data provenance, privacy, and caching 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 moderately long but every sentence earns its place. It uses a numbered list for use cases, making it easy to parse. There is no redundant repetition of annotations or schema, and the structure is clear 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 description covers what the tool returns, the data source, caching behavior, and privacy. Even without an output schema, it hints at the return structure ('(pack, tool, count)'). For a relatively simple tool with one optional parameter, this description is complete and self-sufficient.

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

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

Although the schema already describes the single 'window' parameter with an enum and description, the tool description adds extra meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This explains the trade-off between windows, going beyond the schema's basic list of values.

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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' The verb 'returns' and resource specificity are present, and the tool is easily distinguished from siblings like discover_tools or recent_alerts.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' This gives clear when-to-use guidance and implicit differentiation from alternative tools.

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

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

Beyond the readOnly/annotations, it discloses specific thresholds and conditions: deviations >3pp emit a signal, Jaccard similarity ≥0.30 filters pairs, >20% placeholder fraction returns null, and the fill check will indicate 'realizable_edge_pp ≤ 0 means...do not trade it.' This is rich behavioral detail 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 long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence provides actionable information—thresholds, examples, response details—without filler. The front-loaded mode guidance makes it easy to parse.

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 explicitly listing response fields (opportunities[], partition_check, fill_check), describing all three modes, and covering edge cases like placeholder filtering and thin legs. It is self-contained for a complex tool.

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

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

Although the schema already covers both parameters, the description adds substantial meaning: it explains the side effects of each mode, gives concrete examples ('fed-decision-may-2026'), and details what the tool does with these parameters (walks child markets, flattens markets, etc.). This goes far beyond the schema's concise 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This specific verb+resource+method distinguishes it from sibling tools like polymarket_edges, which focus on market edges, while this tool targets arbitrage across related markets.

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 mode guidance is given: 'Call with NO args for a trending_scan...; pass `event` for...; or `topic` for...'. It also provides decision rules (event for a specific market, topic for cross-event) and references an alternative tool for sizing: 'For custom sizing use polymarket_fill_risk.' This is clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses substantial behavioral traits: 1-hour KV caching keyed on all knobs, output segmentation with diagnostics ('_diagnostics{...funnel counters,category_counts,filter_skips}'), and caveats like Fed bets being excluded due to unreliable signal. It also explains edge calculation and slippage handling, providing deep transparency into how the tool operates.

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 highly detailed and well-organized into sections (purpose, model families, response structure, knobs, diagnostics), but it is excessively long with specific details like per-sport alpha values (tennis 1.02, soccer 1.10, MMA 1.15) that are not needed for invocation. It earns a middle score for structure but loses points for verbosity.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively covers the response structure (by_segment with three segments, top-level fields, diagnostics) and caching behavior. It explains what callers can expect to receive and why segments might be empty, making it highly complete for an agent to understand the tool's behavior without external 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 description coverage is 100%, so all parameters are documented. The description adds additional semantic value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining their purpose (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'), and clarifying how min_partition_leg_kelly interacts with partition buckets. This goes beyond the raw schema without being redundant.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and differentiates itself from siblings by focusing on broad discovery ('what should I bet on today') rather than execution or specific arbitrage strategies.

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 intended usage is implied through 'Built for "what should I bet on today"' and 'agents discover opportunities without paging hundreds of markets,' but there is no explicit guidance on when to use this tool compared to alternatives like polymarket_arbitrage or polymarket_edge_tracker. No exclusions or 'when not to use' instructions are provided.

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 safety, and the description adds valuable behavioral context: snapshots depend on cache-miss execution (gaps mean no scan), history is bounded by a 60-day TTL, 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?

Well-structured and front-loaded: opens with purpose, then explains response format in detail, then lists limitations. Every sentence carries nontrivial information for a complex tool, 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?

With no output schema, the description fully documents the response structure (tracked[], expired[], snapshot_dates[]) and its semantic nuances (e.g., edge_pp_net signed by direction, lifespan as competition clock). It also covers limits like TTL and snapshot gaps, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, with days and window already fully described (lookback/clamp and enum options). The description repeats defaults and adds 'snapshot family' context, but does not meaningfully extend parameter meaning. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' built from daily snapshots, and directly answers a specific analytical question ('how long has this edge existed and is it shrinking?'). This verb-driven purpose distinguishes it from sibling tools like polymarket_edges, which likely focus on current edge detection.

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

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

Clear usage context is implied by the question it answers, making it obvious when an agent should invoke it. However, it doesn't explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, but the description goes far beyond this. It discloses the internal walk of the order-book ladder, lists precise return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and explains semantics for both modes, including how size_usd is interpreted differently. This significantly enriches behavioral transparency 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 long and dense, but well-structured with clear mode labels (SINGLE-MARKET, BASKET) and a final usage directive. It front-loads the core purpose in the first sentence and then systematically covers modes, parameters, outputs, and risk. Every sentence adds necessary information for a complex dual-mode tool, though the ALL-CAPS emphasis and lengthy run-on structure slightly reduce readability.

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

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

Given the tool's complexity, the absence of an output schema, and the richness of the input schema, the description is exceptionally complete. It explains both modes, parameter semantics, return values in detail, and even the risk context (partial basket fills converting arb into unhedged positions). No critical behavioral aspect is left unexplained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the dual-mode semantics of size_usd (max spend/target proceeds vs settlement notional S) and explaining the meaning of side in basket mode (sell_yes captures overround, buy_yes captures underround). While the schema already provides concise descriptions, the description adds the reasoning and interaction between parameters, justifying a score above baseline.

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

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

The description opens with a specific, action-oriented summary: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the resource (CLOB order-book depth) and the verb (check), and distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as tools this should precede. The two modes (single-market and basket) are also clearly distinguished.

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 and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why—theoretical overround on thin books is not capturable, and partial basket fills create unhedged directional risk—which effectively tells the agent when to choose this tool over alternatives.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing specific behavioral nuances: compatibility_warning fires in two distinct cases, temporal_alignment indicates whether spreads are meaningful, and skipped_cross_type/subtype counters expose dropped comparisons. This gives the agent a thorough understanding of edge cases and result validity.

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

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

The description is long but well-structured with headers (TWO MODES, RESPONSE, SAFETY FIELDS) and dense, relevant information. Every sentence contributes value, though a few phrases could be tightened (e.g., 'pre-mapped ≠ tradeable' at the end). For a tool with this complexity, the length is justified.

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

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

There is no output schema, so the description fully compensates by explaining the response contents (leg-by-leg prices, matched spread with top_spreads_pp) and all safety fields. It also addresses temporal alignment and skipped comparisons, making it sufficiently complete for an agent to interpret results reliably.

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 input schema already describes each parameter (100% coverage), the description enriches semantics by explaining the topic shortcuts list, the overriding behavior of kalshi_event_ticker and polymarket_event_slug, and the response format for custom pairings. It adds meaningful guidance beyond 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on cross-venue comparison and explicitly describing two modes (topic shortcuts vs. custom pairings), making it unambiguous 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, including two modes (topic vs. explicit tickers) and a critical caveat that real cross-venue spreads are rarer than the shortcut list suggests, with most pre-mapped topics returning compatibility_warning. It does not name alternatives directly, but it covers when-not-to-trade based on safety fields, so it is almost a 5 minus the lack of explicit alternative references.

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, destructiveHint=false, idempotentHint=true. The description adds that the tool 'Returns attribute rows (and geometry)', which is useful behavioral context. It also clarifies the query style as 'SQL-like', 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 a single sentence, front-loaded with the core action and source. It efficiently mentions all key parameters and gives a usage tip without 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?

The description covers the essential behavior (querying an ArcGIS layer), return type (attribute rows and geometry), and prerequisite (url from search_datasets). While there is no output schema, the description and annotations provide sufficient context for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, with each parameter already documented. The description merely lists parameter names and gives a usage example, adding no new semantics beyond the schema. 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 'Query an ArcGIS Feature Service / Map Service layer by its url', with a specific verb and resource. It also mentions the URL source 'from search_datasets', which distinguishes it from sibling tools like search_datasets or 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 when to use the tool: after obtaining a URL from search_datasets. It also provides a practical sampling tip ('Use where="1=1" + out_fields="*" to sample'). It doesn't explicitly list exclusions but gives clear context for use.

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, lowering the bar. The description adds useful context beyond these: scoping to 'anonymous IP, BYO key hash, or account ID' and the lifecycle pairing with remember/forget. This is genuine added behavioral information.

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

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

The description is two sentences, front-loaded with the core action ('Retrieve a value... or list all saved keys'), followed by use-case and scoping. Every sentence earns its place; 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 tool with one optional parameter and strong annotations, the description covers purpose, usage context, scoping, and pairing with related tools. The absence of return-value explanation is acceptable given the simplicity of the tool 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?

With 100% schema description coverage, the baseline is 3. However, the description adds meaning by providing concrete examples of keys ('target ticker, an address, prior research notes') and clarifying the omit-the-key argument to list all keys, which goes beyond the schema's terse parameter description.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys, using the specific verb 'Retrieve' and resource ('value previously saved via remember'). It differentiates from siblings by explicitly pairing with 'remember' and 'forget', making its role in the toolset unambiguous.

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

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

The description provides clear when-to-use context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, but does not explicitly name alternative tools or provide when-not-to-use guidance, 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=true and idempotentHint=true, so the description adds significant context: mark_read:true flags events as read and affects subsequent calls, each event carries source/citation_uri/payload, and polling is supported. There is no contradiction with annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds unique value: return payload structure, filtering, read flag behavior, and an alternative HTTP endpoint. There is no filler or redundancy.

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

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

The description explains the return structure (source, citation_uri, raw event payload), key parameters (type, since, mark_read), side effects (mark_read), and alternative access method. With annotations covering safety, this is complete for a simple read 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%, so the baseline is 3. The description adds an example for type ('sec_8k') and clarifies the behavioral effect of mark_read, which is helpful. It does not add much for limit, since, or unread_only beyond the schema, but the added value is sufficient for 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 'Pull fired events from your subscription feed', clearly naming the action (pull) and the resource (fired events from the subscription feed). It distinguishes this from sibling tools like list_subscriptions by focusing on event retrieval 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 notes 'Polls work fine' and mentions the same feed is available at GET registry.pipeworx.io/alerts.json, giving context on when to use the tool versus a direct HTTP fetch. It also explains filtering options, though it does not explicitly reference sibling tools.

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

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

The description discloses rich behavioral details beyond the annotations: multi-source fan-out, GDELT→GNews fallback conditioned on rate-limiting/5xx, USPTO soft-fail due to PatentsView API sunset, and the exact return structure (grouped changes[] + total_changes + citation URIs). This goes far beyond the readOnly/idempotent hints already provided.

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, with each section (sources, fallback, soft-fail, alternative tool) adding value. However, it is somewhat verbose due to the opening query examples and detailed source explanations, which prevents a perfect 5 for conciseness.

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

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

Given the tool's complexity and the lack of an output schema, the description compensates thoroughly. It covers the multi-source fan-out, fallback behavior, failure mode, time-window syntax, and return format. All essential context is provided for an agent to invoke the tool correctly.

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

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

The schema covers all three parameters with 100% description coverage, including `since` formats and `value` as ticker/CIK. The description essentially restates the `since` formats and does not add materially new parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and explicitly lists the data sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling tool entity_profile by noting when to use that instead, satisfying a clear verb+resource definition.

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 entity_profile instead when you want the static profile ... regardless of window,' providing a clear when-not directive. The opening query examples (e.g., 'What's new with X', 'updates on Acme') establish the intended use case for recent-change queries, making the usage context explicit.

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

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

Annotations already convey read/write and idempotency traits, but the description adds valuable behavioral context: storage as key-value pairs, scoping by agent identifier, and the 24-hour retention window for anonymous sessions. This goes beyond the structured data without contradicting it.

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 efficiently structured: first the core action, then usage guidance, then persistence details and sibling pairing. Every sentence contributes meaningful 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?

For a tool with only two string parameters and no output schema, the description fully covers the necessary context: purpose, when to use, persistence behavior, and relationship to sibling tools. No gaps remain.

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 descriptive parameter definitions for both 'key' and 'value'. The description reinforces the key-value nature but does not add new parameter-level details, so 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 clearly states the tool's function with a specific verb ('Save') and resource ('data'), and distinguishes itself from sibling tools by explicitly naming recall and forget as companion operations for retrieval and deletion. This directly clarifies scope and differentiates from alternatives.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and names the complementary tools ('Pair with recall to retrieve later, forget to delete'). It also adds context about persistence differences for authenticated vs. anonymous sessions, giving clear situational 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 behavior, and the description adds internal details such as 'cascades through several lookup endpoints internally' and returns citation URIs from specific sources (SEC EDGAR, RxNorm). This transparency goes beyond the structured hints 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?

Though longer than typical, the description is front-loaded with intent examples and a clear directive, then provides type-specific details. Every sentence adds useful information about usage or return values; no fluff.

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

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

No output schema exists, so the description compensates by enumerating exact returned fields for each type (ticker+CIK+company_name, RxCUI+ingredient+brand) and citing source databases. It also explains the multi-lookup cascade, making tool behavior fully predictable. Contextually complete for its complexity.

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

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

Schema covers both parameters at 100% with type/value descriptions. The description adds semantic richness by specifying accepted input formats (ticker, CIK, or name for company; brand/generic for drug) and auto-disambiguation, which clarifies the 'value' parameter's expected content beyond the schema's examples.

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 'resolve[s] a user-spoken NAME to the canonical/official identifier other tools require as input,' with concrete example queries. It also breaks down supported entity types (company, drug) and their output identifiers, making the purpose unmistakable and distinct from downstream tools.

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

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

Gives an explicit directive: 'Use FIRST whenever you have a name but need an ID,' which clearly indicates when to invoke. It also lists example user phrasings to trigger the tool, providing practical guidance. No explicit exclusions, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it reveals that the tool internally probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond what annotations convey and helps the agent predict side effects and behavior.

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

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

The description is three sentences long and front-loaded with the main purpose. Every sentence adds value: what it does, how it does it (sub-probe + ranking), and what it returns. No filler or redundancy.

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

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

Given no output schema, the description sufficiently explains the return format ('ranked list with score, confidence, signal density per entity'). It also covers the use case, process, and setup. It could go deeper on edge cases or potential costs of probing multiple models, but for its complexity level it is reasonably complete.

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

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

Schema description coverage is 100%, with all four parameters clearly documented in the input schema. The description adds a little framing (e.g., 'your brand + N competitors' for entities), but it does not provide new syntax or details beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from the sibling tool ai_visibility_check by focusing on comparison across multiple entities, and further clarifies the process (probes each entity, ranks by score) and outcome (surfaces most/least recognized).

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

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

Provides a clear use case: 'useful for competitive AI-marketing audits' and gives an example query ('does Claude know about us as well as our competitors?'). However, it does not explicitly state when not to use it or point to ai_visibility_check for single-entity checks, though the comparison with a sibling is implied rather than directly stated.

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; the description adds unique behavioral details: fans out across two APIs, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed field 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?

Five sentences, each carrying unique info: composite nature, usage triggers, return summary fields, ecosystem limitation, and failure behavior. Front-loaded with the core purpose and no wasted words.

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

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

Covers main purpose, usage, output field names, failure modes, and ecosystem boundaries. Despite no output schema, the description compensates with an explicit field list, making it complete for an agent to invoke correctly.

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

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

Schema covers both params 100%, so baseline 3. The description mentions 'version history' and 'recent alternative versions' but doesn't add syntax or semantics beyond the schema's already clear package/version definitions.

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

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

The description clearly states it's a composite check for npm packages, aggregating deps.dev and bundlephobia data to answer 'should I add this npm package' questions. It distinguishes itself from sibling tools by its specific function and output fields.

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

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

Explicitly says 'Use whenever an agent asks...' providing clear trigger conditions. It also states NPM-only scope and directs non-NPM ecosystems to deps.dev:version directly, giving an exclusion path and alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by enumerating the exact return fields (name, summary, record_count, owner/org, url) and explaining how the output should be consumed, going beyond what annotations provide.

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

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

Two tightly-packed sentences deliver the purpose, scope, return value, and downstream usage without any fluff. The information is front-loaded and every clause 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?

Even without an output schema, the description fully explains what the tool returns and how to use that result with sibling tools. It provides sufficient context for an agent to know when to invoke this tool and what to do with the output, making it complete for its complexity.

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

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

The input schema already covers all three parameters with clear descriptions (query, limit, org_id), achieving 100% coverage. The description adds minimal extra semantics—mainly context about the types of datasets searched—but does not illustrate parameter examples or edge cases beyond the schema examples.

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 search over City of Flagstaff GIS open geospatial datasets by keyword, with specific examples of dataset types. It distinguishes itself from sibling tools by explicitly noting that the returned Feature Service URL should be passed to query_layer/layer_info, which is unique and actionable.

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

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

The description implies the primary use case (discovering datasets by keyword) and provides a clear next-step guidance by telling the agent to pass the resulting URL to query_layer or layer_info. It does not explicitly state when not to use this tool, but the naming and sibling context make the intended scope 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 the read-only/idempotent hints, the description discloses the embedding model (BGE-base-en), the windowing mechanism (500-char overlapping windows), and the 200K character cap with truncation and flagging. It also explains that passages carry character offsets so the agent can verify verbatim quotes, which is crucial behavioral information for an AI 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 structured with a clear lead sentence followed by usage guidance and then technical details. It is slightly longer than necessary but every sentence adds a distinct piece of information, 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 that there is no output schema, the description fully covers what the tool returns (passages with offsets and similarity scores) and its constraints (200K cap, truncation). The pairing with ask_pipeworx_grounded also gives contextual completeness about the broader workflow.

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 defines all three parameters with full descriptions, so the baseline is a 3. The description adds value by giving concrete examples for the text parameter (SEC 10-K body, article, long tool result) and clarifying that the limit controls the number of top-N passages with offsets and similarity scores, which goes beyond the schema's 'Max passages to return.'

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 'Semantic search INSIDE a fetched record,' clearly stating the verb (search) and resource (a record you already pulled). It distinguishes from siblings by framing the use case ('when the record is too big to cram into the prompt') and explicitly pairing with ask_pipeworx_grounded for grounding over passages rather than the whole document.

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 states exactly when to use this tool ('Use when the record is too big to cram into the prompt') and explains how it saves context and returns only relevant passages. It also provides an alternative workflow by naming ask_pipeworx_grounded as the grounding counterpart, giving the agent a clear decision path.

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 behavioral details beyond the annotations, such as the OAuth account requirement, the return of a subscription id, the SMS phone verification and 10/day cap, and the always-on feed behavior. These disclose operational constraints not visible from readOnlyHint/destructiveHint alone.

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

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

The description is long but information-dense, with a clear front-loaded purpose statement followed by structured sections for types and delivery channels. Each sentence adds unique value (e.g., examples, constraints, fallback methods) without 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?

Together with the rich schema and annotations, the description covers the essential aspects of a subscribe tool: auth requirements, return value, type-specific parameters, delivery options, and consumption mechanisms. No output schema exists, but the return id is stated. Sibling tools handle listing and unsubscribing, so management is covered.

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

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

Schema coverage is 100%, and the schema's own descriptions already provide type-specific params and delivery channel details (e.g., sec_8k items, sms cap, webhook behavior). The description only repeats examples already in the schema, so it adds no new parameter semantics beyond 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 opens with a specific verb phrase: 'Create a proactive monitoring subscription to a live-data event stream,' which clearly states the tool's function and resource. It also mentions returning the new subscription id, distinguishing 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?

Provides clear context by stating the authentication prerequisite (Pipeworx OAuth account, no anonymous/BYO) and explaining delivery channels, including a pointer to recent_alerts for the always-on feed. It does not explicitly name alternative tools, but the implied usage versus list/unsubscribe is clear.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so credit is given for added context. The description discloses that results are drawn from the live catalog of thousands of tools and that it returns exact tool+argument shapes—useful behavioral detail not in 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 front-loaded with example prompts and purpose, followed by return details and usage instructions. Every sentence earns its place: the example questions illustrate intent, the second sentence explains output structure, and the final two sentences cover invocation and prioritization. No fluff or repetition.

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

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

Despite having no output schema, the description fully explains what the tool returns (category-bucketed examples with tool+shape), how to call it (with and without topic), and when to use it (onboarding). It also names related meta-tools, making it complete for a simple one-parameter tool.

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

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

Schema coverage is 100% and the schema description already lists all valid topic values and the omission behavior. The description adds example topics ('finance', 'pharma', 'betting') but these are redundant with the schema's enum-like list. It does not provide additional semantic depth 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 explicitly states the tool's purpose: it returns category-bucketed example questions with exact tool and argument shapes, serving as the onboarding entry point. It also distinguishes from siblings by positioning it as the 'FIRST' tool when unsure, and references alternatives like ask_pipeworx, entity_profile, and compare_entities.

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 strong usage guidance: use it FIRST when you don't know what Pipeworx can do, and explicitly explains the two invocation modes (no args for full spread, or pass topic for focus). It also mentions that it helps learn how to call meta-tools, clarifying its role relative to siblings.

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

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

The description goes beyond annotations by disclosing ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('row is deactivated (not deleted) so its historical events stay available via recent_alerts'). This adds valuable context about permissions and side effects, which is not present in the annotations.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence contributes meaningful information. It is concise and well-structured without 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 single-parameter tool with no output schema, the description covers the purpose, ownership constraint, and the non-destructive deactivation behavior, making it sufficiently complete for an agent to understand 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?

The input schema already provides 100% coverage for the sole parameter, describing it as a 'Subscription id (uuid) returned by subscribe.' The description reiterates this by mentioning 'by id' and ownership but does not add additional semantic details beyond what the schema already states.

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: 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription), and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by describing the cancellation action and the ownership constraint.

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

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

The description provides clear context for when to use the tool, such as ownership enforcement and the fact that subscriptions are deactivated rather than deleted, implying it's for canceling existing subscriptions. However, it doesn't explicitly mention alternatives or when not to use it, so it misses the 'when-not' guidance that would earn a 5.

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

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

Annotations already signal read-only and idempotent behavior. The description adds substantial context: the structured vs. grounded fallback, tolerance handling, verdict types, citation format, and the fact that it consolidates multiple steps. This goes well beyond the annotations and fully discloses the tool's behavioral scope.

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 structured with examples, routing logic, output summary, and a performance note. Every sentence adds information; no filler. It could be slightly more compact, but the detail is useful, keeping it within a reasonable length.

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

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

For a tool with two simple parameters, the description covers return values (verdicts, actual value, citation), edge cases (any non-financial claim), and operational details (tolerance cap). Since there is no output schema, this description carries the full burden of explaining results and does so comprehensively.

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 both parameters with examples and defaults. The description adds extra value by explaining how tolerance_pct affects grading (e.g., hallucination detection) and how the claim wording implies tolerance. This goes beyond a mere restatement of schema definitions.

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 claim verification with specific verbs like "fact check" and "verify the claim that." It distinguishes from siblings by describing a two-path architecture (SEC EDGAR for company financials, grounded pipeline for everything else), setting it apart from generic ask/research tools.

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

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

Provides explicit guidance on when to use: "Use whenever the agent needs to check whether something a user said is factually correct." It also details the internal routing logic and mentions that it replaces 4–6 sequential calls, but does not explicitly name alternative tools to use instead, leaving some ambiguity against siblings like ask_pipeworx_grounded.

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