Arcgis Allegheny

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds valuable behavioral details: the default model is free, using Anthropic requires a BYO key billed directly to the user, and the return payload includes per-model score/confidence/signals/raw_response plus a combined view. It does not contradict annotations and reveals cost and data flow information beyond what structured metadata provides.

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

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

The description is two sentences long, front-loaded with the core action and output, followed by use cases and cost note. Every clause earns its place 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 4 parameters and no output schema, the description covers input options, default behavior, output structure (score, confidence, signals, raw_response, combined view), and monetization. It lacks explicit error/edge-case handling, but the provided context is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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 all four parameters. The description reinforces the default behavior (omitting models yields workers-ai) and the purpose of context for disambiguation, but it adds minimal new semantics beyond the schema. This matches the baseline for high coverage.

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

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

The description clearly states a specific verb ('probe') and resource ('one or more LLMs'), and defines the output as a visibility score (0-100) per model. It also distinguishes from siblings like ask_pipeworx (which asks questions) and scan_competitor_ai_presence (focused on competitors) by covering any business/brand/product/topic.

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

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

The description provides clear context for when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and when to pass `_apiKey`. However, it does not explicitly call out alternatives or 'when not to use', 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 establish readOnly/openWorld/idempotent/non-destructive, so the description's added context about routing, argument-filling, stable pipeworx:// citation URIs, and 'one fast call' is valuable. It doesn't contradict annotations and discloses the tool's aggregating/citation behavior, though it leaves out failure modes or limits.

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

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

The description is long but front-loaded with the most important guidance and uses each sentence to add scope, examples, or alternatives. Some redundancy exists between the 'use whenever' list and examples, but overall it's structured and purposeful.

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, but description explains the return format (structured answer with pipeworx:// citations) and covers usage contexts, priorities, and when to escalate to alternatives. It's comprehensive for a tool of this complexity, though it could mention potential limitations or error behavior.

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 100% of parameters and documents aliases, but description adds semantic guidance on what types of questions are appropriate (real-world entities, events, numbers) with concrete examples. This goes beyond the schema's property 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 identifies this as a question-routing tool that sends user questions to one of 5,521 tools across 1,452 sources and returns citation-backed answers. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research and positioning itself as the default entry point.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'get the latest'. It also names concrete alternatives ('use ask_pipeworx_grounded for...', 'use deep_research for...'), making the selection criteria clear.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: candidate routing improvements enabled live, no active candidate at present, comparison against the stable router, and the explicit 'Falls back to nothing — this IS a full working router' statement.

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?

Four sentences are dense but well organized, front-loading the beta relationship and most important operational facts. Specifics like the 5,521 tool count and retirement date add context though they could be trimmed without losing core meaning.

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

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

Given no output schema, the description covers the essential context: identity, relationship to stable ask_pipeworx, current candidate status, and intended use. Referencing the same response shape as ask_pipeworx is sufficient because the sibling tool provides additional reference 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?

All six parameters are aliases for question and the input schema describes each at 100% coverage, so the schema carries the semantic burden. The description only mentions 'same arguments' and adds no new parameter-level detail, meeting but not exceeding 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?

Description clearly frames the tool as a beta version of ask_pipeworx, a universal router with the same 5,521 tools, arguments, and response shape, and distinguishes it from the stable sibling. However, it never states an explicit action like 'ask a question', relying on the name and the 'Use it exactly like ask_pipeworx' instruction.

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 it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. It also clarifies that with no active candidate it currently matches ask_pipeworx exactly, giving an agent clear decision context.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial context: exact refusal_reason enum values, evidence quote return, fetched_at timestamp, and the behavior of refusing when data doesn't directly answer. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then compactly covers return format, refusal reasons, use cases, and cost comparison. Each sentence adds necessary information 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?

With no output schema, the description fully specifies success return fields (answer, evidence, confidence, source, fetched_at) and failure refusal reasons. It also covers behavioral guardrails, cost, and sibling alternatives, making it complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, with all six parameters being aliases for 'question' and the schema already explaining the query format. The description does not add parameter-level detail beyond this, but the schema fully carries that responsibility.

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

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

The description states a specific verb and resource: 'Hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing grounded evidence and explicit refusal behavior.

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

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

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 notes the extra LLM call cost, giving a clear trade-off for tool 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already establish a safe read-only operation. The description goes far beyond that by detailing resolution contract (market_match_confidence, alternatives), low-confidence suppression, closed-market status, wide-spread illiquidity warning, news fallback behavior, and cancellation rule risk with 50-cent void settlement. This gives the agent crucial behavioral context for interpreting results and avoiding misuse.

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 long, the description is exceptionally well organized with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and a front-loaded purpose. Every sentence carries critical operational information for a complex tool with no output schema. The structure allows an agent to quickly find relevant details without excess.

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 three parameters and no output schema, this description carries full burden to explain behavior and return shapes. It covers the output object structure (market, analysis, evidence, market_match_confidence, parent_event, news fields), error/blocking statuses (low_confidence_match, market_closed_or_inactive), tradeability warnings, and resolution-rule risk. This is as complete as one could expect for such 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?

The input schema already provides excellent descriptions for all three parameters, including accepted token formats for market, quick vs thorough depth, and include_raw size impact (100% schema coverage). The description adds context about resolution and fan-out, but it does not materially clarify the parameters themselves beyond what the schema states, so a baseline of 3 is appropriate.

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

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

The first sentence clearly states the verb ('Research'), resource ('Polymarket bet'), and mechanism ('by pulling the relevant Pipeworx data for it in one call'). It further distinguishes the tool by listing supported input formats and the broad set of classifiers, making it unmistakable compared to siblings like polymarket_edges or arbitrage tools.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear invocation context. It also includes fan-out examples and safety notes that affect when to trust output. However, it lacks explicit 'when not to use' or references to alternatives among the sibling tools, so it misses the top score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond these by disclosing data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, long-term debt, adverse-event counts), special handling for off-calendar fiscal years, and result sorting 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 dense and front-loaded with examples, but every sentence contributes useful selection or invocation guidance. It is slightly longer than strictly necessary, but the added detail about fiscal year handling and data sources 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?

With no output schema, the description must explain return behavior, and it does: it notes paired data plus pipeworx:// citation URIs, explains sorting by primary metric, and covers both entity types thoroughly. This gives an agent enough context to use the tool correctly and interpret results.

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

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

While schema coverage is 100%, the description adds significant semantic detail: it explains what each type='company' and type='drug' returns, specifies the values array as 2–5 items, and provides concrete examples. It also clarifies output ordering by primary metric, which is not in the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, using concrete trigger phrases like "X vs Y" and "head to head." It also distinguishes itself from likely single-entity siblings like entity_profile by emphasizing parallel comparison.

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

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

Explicit guidance is provided: "ALWAYS PREFER over sequential single-pack lookups when comparing entities," and it quantifies the benefit ("Replaces 8–15 sequential lookups"). This clearly tells an 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses account requirements, depth-specific hop behavior (gap recovery, contradiction scans), citation resolvability, semantic excerpting, and timing (15-60s). It also clearly notes limitations ('returns mostly empty gaps[] when the topic isn't in the structured catalog'). No contradiction with annotations.

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

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

The description is long but every sentence adds distinct value: account requirements, alternative tools, core mechanism, output format, depth semantics, limitations, and timing. For a tool of this complexity, the density is justified, though a more structured layout (e.g., bullet points) could improve scannability. No redundancy found.

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 detailing return values: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]' and 'contradictions[]'. It also covers timing, process, and edge cases, making the description self-sufficient for an agent to choose 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% (both parameters documented). The description adds narrative context about depth levels beyond the schema, such as how 'standard' re-angles unanswered gaps and 'thorough' chases leads, plus default depth behavior. While the schema already explains the enum values, the description enriches understanding of their practical effect, earning value above the baseline.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' and explains the mechanism ('Decomposes your question into focused facets, routes each to the right one of 5,521 tools IN PARALLEL'). It distinguishes from siblings by explicitly contrasting with ask_pipeworx ('For a single lookup use ask_pipeworx').

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and exclusionary guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS / "what's the world saying about X" topics, prefer ask_pipeworx.' Also states prerequisites (account required, free tier limitations).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' which is valuable behavioral context 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 front-loaded with the purpose and then covers when to use, the return format, and strategic advice in just two sentences. The domain list is long but densely packed as a comma-separated enumeration, earning its place for a discovery tool.

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

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

No output schema exists, but the description explicitly explains the return value ('top-N most relevant tools with names, descriptions, and full input schemas'), so agents know what to expect. Combined with strong annotations and clear usage guidance, the tool is well covered without needing more.

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

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

Schema description coverage is 100%, so baseline is 3. The description's domain list gives context for forming queries but doesn't add parameter-specific semantics beyond what the schema already documents for 'query', 'limit', and aliases.

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 tools by describing the data or task.' It specifies the resource (tools) and provides a list of domains, distinguishing it from sibling tools as a discovery/meta-tool.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available,' which is clear when-to-use guidance. It also implies when not to use it (if you already know the specific tool) with 'not just one answer.'

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 substantial behavioral detail: parallel fan-out across sources, patent API sunset with soft-fail, GDELT-to-GNews fallback, and sorting/limits for fundamentals and filings. This adds real transparency beyond the structured 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 information-dense, front-loading with query examples and using semicolon-separated lists to pack details. Every sentence earns its place; it is not concise, but the complexity justifies the 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 complex multi-source tool with no output schema, the description covers all expected outputs, fallbacks, and a key limitation. It doesn't define exact units or time windows for news, but the core profile behavior is well specified.

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

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

Schema descriptions cover 100% of parameters, already including ticker/CIK examples and the name restriction. The description repeats this information without adding new syntax or format details, so the baseline 3 applies.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It distinguishes from siblings like resolve_entity and single-pack lookups by explicitly advising preference for holistic views, showing a specific verb+resource+scope.

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

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

The description gives 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 states a clear exclusion (names not supported) and recommends resolve_entity as an alternative, making alternatives and 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 declare destructiveHint=true and idempotentHint=true, so the destructive nature is known. The description adds context by specifying the target is 'previously stored memory' and the use case of 'clearing sensitive data,' which goes beyond the structured annotations. It doesn't contradict them.

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

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

The description is two sentences, front-loaded with the operation and resource, and every sentence adds value. No filler or repetition of structured fields.

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 one-parameter tool with complete schema coverage and informative annotations, the description covers the purpose, usage context, and relationship to sibling tools. No output schema means return values don't need explanation. The description is sufficient for accurate 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 description coverage is 100%, with the 'key' parameter already described as 'Memory key to delete.' The description's phrase 'by key' adds no new format or syntax details beyond what the schema provides, 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 opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (store) and recall (retrieve), making the purpose unambiguous.

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

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

The description explicitly states when to use the tool ('Use when context is stale, the task is done, or you want to clear sensitive data...') and even pairs it with 'remember and recall,' but it does not provide explicit exclusions or alternative tool suggestions beyond the pairings. This is clear context without comprehensive when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail: it fetches the page, extracts title/description/key links, and returns markdown output. It also clarifies that the output is a text blob, which is not in the annotations. 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 three sentences: purpose, process, and use cases. It is front-loaded with the primary action and contains no redundant 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 2 parameters and no output schema, the description explains the output (single text blob) and workflow clearly. Combined with strong annotations, it is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with both `url` and `max_links` already having descriptive comments in the input schema. The description doesn't add parameter-specific semantics beyond what's in the schema, so a 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 states a clear purpose with a specific verb ('Generate') and resource ('llms.txt file'), and elaborates on the process (fetching, extracting, emitting). It distinguishes itself from sibling tools like `scan_competitor_ai_presence` by focusing on producing the file rather than just analyzing visibility.

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: client indexing, drafting for projects, auditing competitor AI visibility. It lacks explicit 'when not to use' comparisons with alternatives, but the use-case list effectively conveys when to pick this tool.

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

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

The description adds behavioral context beyond the annotations by specifying the exact contents of the returned schema (fields, geometry type, record count, capabilities). Since annotations already declare it read-only and idempotent, this extra detail helps the agent understand the result 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?

One sentence, front-loaded with the verb 'Get', and no filler. Every word contributes to defining the tool's output.

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

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

For a single-parameter read-only tool, the description is comprehensive: it names the input and all outputs. The lack of an output schema is mitigated by listing the return contents explicitly.

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

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

The input schema fully documents the single 'url' parameter with a clear description and example. The tool description does not add parameter semantics beyond restating 'by url', so baseline of 3 applies.

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

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

The description clearly states the tool retrieves an ArcGIS layer's schema, listing specific outputs (fields, geometry type, record count, capabilities). This strongly distinguishes it from sibling tools like query_layer, which presumably queries data rather than metadata.

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

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

The description implies this tool is for schema inspection but does not explicitly state when to use it versus alternatives like query_layer. No exclusions or alternative tool references are provided, leaving usage guidance to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the active-only default behavior. No contradictions with annotations.

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

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

The description is two concise sentences. The first states the primary function, the second lists return fields and usage guidance. No redundant or filler content.

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

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

For a simple list tool with no required parameters and no output schema, the description covers the essential behavioral context: what is listed, what fields are returned, and how to use it. The sibling context (subscribe/unsubscribe) further clarifies its role.

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 has one parameter with a complete description: 'Include cancelled subscriptions in the response (default false).' Since schema coverage is 100%, the description does not need to add parameter details. Baseline of 3 applies.

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

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

The description clearly states the verb and resource: 'List the caller's active subscriptions.' It also specifies the return fields, which adds precision. This is distinct from sibling tools like subscribe/unsubscribe, which perform different actions.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use the tool, though it does not explicitly name alternatives like subscribe/unsubscribe. This is strong guidance for a simple list operation.

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

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

The annotations provide no meaningful safety/behavior hints (all false), so the description carries the full burden. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, the claim_token flow for anonymous tracking and later retrieval, and that the team reads digests daily. This goes well beyond the structured 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?

Though the description is a lengthy single paragraph, it is front-loaded with purpose and then systematically covers usage, exclusions, workflow, and limits without redundancy. Every sentence delivers actionable information; the length is justified by the rich operational context needed for a feedback tool with a token-recovery mechanism.

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

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

The tool has no output schema, but the description explains the returned claim_token and how to use it. It also covers required context (which connection/tool), exclusions, rate limits, and the team's response process. This is fully sufficient for an agent to select and invoke the tool correctly in all described scenarios.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the claim_token workflow (filing without an account returns a token, pass it back later to read status), and by advising users to describe issues in terms of Pipeworx tools and avoid pasting user prompts. It does not re-explain every parameter, but the schema already does that thoroughly.

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 ('Tell the Pipeworx team') and resource ('something is broken, missing, or needs to exist'), immediately defining the tool's purpose. It further distinguishes this tool from all siblings by scoping it to Pipeworx connection tools and naming concrete feedback categories (bug, feature/data_gap, praise).

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

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

The description gives explicit when-to-use guidance for each feedback type (bug, feature, data_gap, praise) and explicitly says when NOT to use it: for tools from a different MCP server, directing the user to file with that server instead. It also clarifies ambiguous cases by saying Pipeworx tool names are those this connection lists, and instructs users not to paste the end-user prompt.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds meaningful behavior beyond that: it self-aggregates from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on the window. This extra context justifies a 4.

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

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

The description is well-structured, starting with a clear headline, followed by return details, use cases, and data source/caching notes. It is slightly longer than necessary (e.g., repeating the window options), but every sentence contributes value, so it earns a 4.

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

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

For a simple tool with one optional parameter and no output schema, the description is remarkably complete. It explains what is returned, the data source, caching behavior, privacy characteristics, and multiple use cases. No critical information is missing, so this is a 5.

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

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

The input schema fully documents the only parameter ('window') with an enum and a clear description of how short vs. long windows behave. Since schema_description_coverage is 100%, the baseline is 3, and the description does not add significant new parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool's function: showing what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume over a recent window. It is specific and resource-focused, but it does not explicitly distinguish itself from siblings like discover_tools, so it stops short of a 5.

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 concrete use cases: discovering hot data sources, confirming canonical tools, and aligning with agent behavior. This is clear context for when to use the tool, but it does not mention when not to use it or name alternatives, so it earns a 4 rather than 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 mark read-only/idempotent; description adds substantial behavior: partition_filter drops placeholder slugs and returns null for >20% placeholder fraction; fill_check prices against live CLOB depth and warns that realizable_edge_pp ≤ 0 should not be traded. It also describes the emitted BUY/SELL EVERY LEG signal on >3pp deviation.

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

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

The description is long but densely packed; every sentence contributes technical behavior or usage nuance. It front-loads the core purpose in the first sentence but packs boundary conditions, filters, and output contracts into a single paragraph, making it somewhat harder to scan.

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

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

For a tool with no output schema, it describes response fields (opportunities[], gap_pp, partition_check, placeholders_filtered, thin_legs[]), explains failure/null cases, and gives usage recommendations. It also contextualizes the tool versus polymarket_fill_risk, covering both input and output semantics thoroughly.

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

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

Schema coverage is 100%, but the description enriches both params: it provides concrete event slug examples, defines topic as a seed question, and explains the distinct algorithmic behavior for each mode (walking child markets vs. flattening related events). It also makes clear that omitting both args runs a trending scan.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by detailing exclusive mechanisms (monotonicity, partition sums) and enumerating modes (trending_scan, event, topic).

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

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

Explicitly instructs when to call with no args for `trending_scan`, when to pass `event` (recommended for a specific market), and when to use `topic`. It names an alternative tool for custom sizing: 'use polymarket_fill_risk', and explains cross-event mode catches patterns single-event misses.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context beyond that: 'Cached 1h at the KV level keyed on all knobs', the 24h-move warning when the recent move exceeds the edge, and the _diagnostics block with funnel counters explaining why segments are empty. These details are not redundant with annotations and help the agent anticipate response 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 front-loaded with the main purpose, but it is a single monolithic paragraph with long run-on sentences and no bullet points or section breaks. While every sentence carries useful information, the lack of structure makes it harder to parse; it would benefit from separating the model families, response structure, and knobs into clearly labeled sections.

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 must explain return values, and it does thoroughly: it lists the fields carried by every opportunity (edge_pp_net, kelly_fraction, liquidity, etc.), the top-level response structure (by_segment, fed_candidates, _diagnostics), and even the reasons for empty segments. Combined with the parameter explanations and caching behavior, the description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds significant value beyond the schema. For example, min_liquidity is described as 'drop thin-book opportunities where executing the edge would walk the book past breakeven', and min_partition_leg_kelly is explained in relation to min_kelly, clarifying that basket trades always return kelly_fraction_half=0 at the parent level. This rationale and usage guidance go far beyond the schema's descriptions.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which clearly states the verb (scan/return), resource (Polymarket markets), and purpose (opportunity discovery). It further differentiates from siblings by identifying the use case 'what should I bet on today' and noting it avoids paging hundreds of 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?

The description provides clear context for when to use the tool ('what should I bet on today') and explains the three response segments and tradeable-edge knobs, including when to apply filters like min_liquidity and max_spread_pp. However, it does not explicitly name alternatives or state when not to use this tool compared to sibling tools like polymarket_arbitrage, so it lacks explicit exclusions.

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

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

Annotations provide read-only/idempotent/open-world hints, and the description substantially extends this by detailing snapshot cadence (cache-miss writes), history bound from TTL, decay calculation method (daily closes, not intraday), and data gaps. This rich context goes well beyond the annotations with no contradictions.

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

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

The description is dense but well-organized with sections for purpose, args, response format, and limits. Every sentence provides necessary detail for a tool without an output schema, though it is longer than minimal and could be tightened slightly.

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

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

With no output schema, the description compensates thoroughly by specifying the full response structure (tracked[], expired[], snapshot_dates[]), including field meanings, edge-case behavior (expired opportunities), and data quality caveats (snapshot gaps, TTL, daily closes). This makes the tool's behavior fully understandable.

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

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

The input schema already describes both parameters with 100% coverage. The description repeats defaults and window families but adds no new semantic details, so it meets the baseline without enhancing understanding.

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 edge persistence and decay telemetry from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from related siblings like polymarket_edges by focusing on temporal behavior rather than current edges.

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 gives clear context by framing the tool's purpose around a specific question and contrasts fresh vs. old edges, implying when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full usage guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context beyond these: it walks the order book ladder, returns specific metrics, and warns about partial fills converting arb into unhedged directional positions. No contradiction with annotations; the description enriches them with operational detail.

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 every sentence carries meaningful information. It is structured by mode (single-market vs basket) and includes return fields and risk warnings. It could be slightly more concise, but the complexity of the tool justifies the length; no filler or redundancy is present.

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?

This is a complex tool with two modes, 4 parameters, no output schema. The description fully enumerates return fields for both modes, explains parameter interpretation per mode, and discusses edge cases (thin legs, forced directional risk, partial fills). It is complete enough for an agent to understand 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 coverage is 100%, but the description adds substantial meaning beyond the schema. It explains mode-dependent semantics: for market mode, side options and size_usd interpretation (max spend vs target proceeds); for basket mode, side meaning (sell_yes captures overround, buy_yes captures underround) and size_usd as settlement notional per leg. This far exceeds the baseline for schema-covered params.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by explicitly stating it is for checking fill risk before acting on signals from polymarket_arbitrage or polymarket_edges, making its purpose unmistakable.

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

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

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 is not capturable on thin books, partial fills create directional risk), giving clear when-to-use context and alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses detailed behavioral traits: response structure, safety fields (compatibility_warning with two distinct cases), temporal_alignment meaning, and skipped_cross_type/subtype counters. This is rich context well beyond what annotations provide, and it does not contradict them.

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

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

The description is notably long and dense, with extensive details on edge cases and safety fields. Although it is structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS), it could be trimmed significantly without losing essential meaning. It is not 'appropriately sized' for a tool with only 3 parameters, and the length reduces skimmability.

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 full burden of explaining the response format, which it does thoroughly (leg-by-leg prices, matched spread, safety fields, temporal alignment). It also covers the tool's place in the landscape and caveats, making it complete for a complex analytic 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?

While the schema already describes all three parameters (100% coverage), the description adds crucial interaction semantics: the two modes (topic vs explicit ticker/slug) and how explicit parameters override the topic-mapped side. This explains relationships and usage patterns beyond the individual parameter descriptions, fully compensating for any lack of detail.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' using a specific verb+resource and clearly differentiating from siblings like polymarket_arbitrage by naming both venues and the spread concept. It further explains two distinct operation modes, leaving no ambiguity about what the tool does.

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

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

The description provides clear context on when to use it ('when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so') and warns that 'pre-mapped ≠ tradeable,' implying caution. However, it does not explicitly name alternatives or state 'use this instead of X,' so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds that it 'Returns attribute rows (and geometry)' and gives a sampling tip, but does not disclose pagination behavior, response limits, or any potential external side effects. This is acceptable but not rich 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 two sentences, front-loaded with the core purpose, and includes a practical quick-start tip. Every sentence earns its place with no redundancy or fluff.

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

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

With no output schema, the description appropriately explains the return type ('attribute rows (and geometry)'). It also provides enough context for typical usage, including the source of the URL, key parameters, and a sampling strategy. The tool's complexity is well-covered by the combination of description and schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description briefly restates parameter names and adds 'SQL-like' and 'comma-separated' semantics, but these are already implied in the schema descriptions. The sampling tip is a useful addition but does not significantly deepen parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It uses a specific verb (query) and resource (Feature/Map Service layer), and distinguishes itself from sibling tools like search_datasets and layer_info by focusing on data retrieval from a known layer URL.

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

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

The description provides clear usage context by indicating the URL comes 'from search_datasets', establishing a workflow prerequisite. It also offers a sampling tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly mention alternatives or when not to use this tool, though the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavior beyond annotations: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the list-all behavior when the key is omitted. It does not describe return format, but this is a minor gap.

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

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

Three sentences, each earning its place: the core action, the use case, and the scoping/pairing detail. Front-loaded and free of fluff.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers both operational modes, the intended use case, scoping, and related tool integration. Nothing essential is missing.

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

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

Schema description coverage is 100% for the single 'key' parameter, which already explains 'omit to list all keys'. The description adds context that the key is 'previously saved via remember', but this is marginal added value over the schema baseline of 3.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys, with a specific verb and resource. It also distinguishes itself from the sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names related tools (remember, forget) and implies the conditions for listing vs retrieving, making the usage context unambiguous.

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

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

The description discloses a significant side effect by stating 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies a state change. This directly contradicts the annotation readOnlyHint: true, which asserts the tool is read-only. Although the description is otherwise rich in behavioral details, the contradiction forces a score of 1 per the rules.

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 comprehensive, using three sentences to convey purpose, return payload, filtering, mark_read semantics, and an alternative access method. It is front-loaded with the core action ('Pull fired events') and every sentence earns its place 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 key aspects: what the tool does, what the returned alerts contain, optional filters, the mark_read side effect, and polling suitability. There is no output schema, but the return payload is described sufficiently. Some minor details like error handling or rate limits are omitted, but overall the description is complete enough for a read-oriented tool with well-documented parameters.

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 parameters with descriptions, but the description adds meaningful context for mark_read ('flag returned events read so the next call only shows newer ones') and provides a concrete example for type filtering ("sec_8k"). This goes beyond the schema's terse descriptions, enhancing the agent's understanding of parameter behavior.

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: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts the evaluator has written to your persisted feed.' This specific verb+resource pair distinguishes it from sibling tools like list_subscriptions or recent_changes, making its purpose unmistakable.

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

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

The description provides clear context for when to use the tool: for retrieving alerts from the subscription feed, and even mentions an alternative for scripts/dashboards ('the same feed is also at GET registry.pipeworx.io/alerts.json'). It lacks an explicit when-not-to-use statement or comparison to specific sibling tools, but the guidance is sufficient for most use cases.

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

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

Beyond the annotations (read-only, idempotent), the description discloses rich behavioral details: parallel fan-out to multiple sources, fallback logic (GDELT preferred, GNews on rate limiting/5xx), the PatentsView API sunset causing soft-fail, and the exact return format (changes[] grouped by source, total_changes, citation URIs). This is substantial added context beyond the safe-read signals.

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

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

The description is dense but every sentence earns its place. The opening list of natural-language paraphrases is slightly verbose but useful for intent matching. The overall structure flows from purpose to sources to parameters to return shape to alternatives, making it easy to scan.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail, no output schema), the description is exceptionally complete. It explains the return shape (changes[] grouped by source, total_changes, citation URIs), the window parameter, and the operational caveats (USPTO sunset, rate-limiting fallback), leaving no significant gaps for an agent to invoke it correctly.

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

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

While the schema already documents all three parameters (100% coverage), the description adds practical nuance: `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, and clarifies that `value` can be a ticker or zero-padded CIK. This goes slightly beyond the schema's own 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 defines the tool as a change feed for a company over a time window, listing the specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and the return structure. It also distinguishes itself from sibling tools like entity_profile by explicitly contrasting the dynamic feed with the static profile.

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

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

The description provides explicit usage context with natural language query examples and directs users to an alternative tool ('Use entity_profile instead... when you want the static profile'). It also discloses fallback behavior and limitations (GDELT to GNews fallback, USPTO soft-fail), giving clear guidance on when and how to use the tool.

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

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

The description adds valuable behavioral context beyond the annotations: persistence semantics ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping by identifier. It does not contradict any annotation; idempotentHint and readOnlyHint align with the write-and-overwrite nature of saving key-value pairs.

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

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

The description is three concise sentences, front-loaded with the core purpose ('Save data the agent will need to reuse later'). Every sentence adds distinct value: what to save, when to use it, persistence behavior, and companion tools. 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?

For a simple two-parameter tool with no output schema, the description fully covers the essential context: purpose, usage triggers, persistence behavior, and related tools. The annotations cover idempotency and non-destructiveness, so the description does not need to repeat those. It is sufficiently complete for an agent to invoke it correctly.

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

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

The input schema already provides 100% description coverage for both parameters ('key' and 'value') with examples. The description adds minimal new parameter-specific detail, only noting the key-value pair structure and identifier scoping, which is more of a behavioral note than parameter semantics. The description does not compensate enough to exceed the baseline.

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

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

The description uses a specific verb ('Save data') and a clear resource ('data the agent will need to reuse later'), and it differentiates itself from sibling tools by explicitly mentioning 'recall' and 'forget' for retrieval and deletion. The phrase 'across this conversation or across sessions' clarifies the scope of what is stored.

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

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

It provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and explains the benefit ('so you don't have to look it up again'). It also names companion tools ('Pair with recall to retrieve later, forget to delete'), giving clear alternatives for the same workflow.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses internal cascading behavior ('cascades through several lookup endpoints internally'), auto-disambiguation, and the exact return fields (ticker, CIK, company_name, citation URI) for each type. This adds substantial behavioral context beyond the structured metadata.

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

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

The description is dense but well-organized: opening examples immediately orient the agent, followed by a clear directive, then structured per-type details. Every sentence adds necessary information with no fluff or repetition.

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

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

Given there is no output schema, the description fully covers return values and input formats for both supported types. It also addresses the tool's internal complexity (cascading lookups) and how it fits into the broader workflow. Complete for the tool's complexity and metadata richness.

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 already 100%, but the description enriches both parameters with concrete examples and expected outputs. For type it lists 'company' and 'drug' with their return shapes; for value it provides formats like 'AAPL', '0000320193', 'ozempic'. This goes far beyond the schema's minimal descriptions.

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

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

The description opens with concrete user queries ('What's the ticker for…', 'find the CIK for…') and then states the core purpose: resolve a user-spoken name to the canonical/official identifier. It clearly identifies the resource (entity names) and the action (resolve to ID), and differentiates from siblings by emphasizing this tool is the entry point for all ID lookups.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It also explains that one call replaces 2-3 manual lookups, reinforcing the 'use this first' guidance. While it doesn't name alternative tools, the directive is clear and contextually 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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond that: it probes with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score/confidence/signal density per entity. It also discloses the first-entry-as-subject narrative nuance. This is rich additional context that goes well beyond the annotations, with no contradiction.

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

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

The description is four sentences, front-loaded with the main purpose, then method, use case, and return format. Every sentence earns its place with specific information: what it does, how it works, when to use it, and what you get back. There is no fluff or repetition of schema/annotations. Ideal size and structure.

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

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

Despite having no output schema, the description covers the key aspects: purpose, internal mechanics (uses ai_visibility_check), return format (ranked list with score/confidence/signal density), use case context, and an important parameter nuance. Annotations cover the safety profile. For a read-only comparison tool with 4 well-documented parameters, this is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic nuance for the 'entities' parameter: 'First entry treated as the "subject" for narrative; rest are competitors.' This explains the order-dependent behavior not captured in the schema. Other parameter details (models, _apiKey, context) are already fully described in the schema, so this modest addition justifies a 4.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive AI-presence audit focus and the ranking behavior. The example use case ('does Claude know about us as well as our competitors?') reinforces the 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 provides clear context: it is for competitive AI-marketing audits when you want to compare multiple entities. It explains that it probes each entity with ai_visibility_check, implying that for a single entity you'd use the sibling tool, though it doesn't explicitly say 'use ai_visibility_check for single entity.' This is clear context without explicit exclusions, so a 4 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?

The description adds significant behavioral context beyond the annotations: explains composite fan-out, partial failure degradation, potential 5-30s delay on first bundlephobia measurement, and the sources_failed field. No contradictions with the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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 dense, with no wasted sentences. It front-loads the core purpose, then covers usage, return fields, and failure modes in a structured flow. Every clause adds value, making the length appropriate for the tool's complexity.

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

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

With no output schema, the description compensates by explicitly listing return fields and summary block contents. It covers prerequisites, ecosystem scope, latency caveats, and fallback behavior. This is a complete picture for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces that 'package' is an npm package name and 'version' defaults to latest, but these details are already in the schema. It adds no substantially new parameter-level semantics beyond what the schema provides.

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

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

The description clearly states the composite purpose: a one-call check for whether to add an npm package, with specific sources (deps.dev, bundlephobia) and output fields. It distinguishes itself from any sibling tool by focusing on npm dependency vetting.

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

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

Explicit guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly delineates non-NPM ecosystem handling, directing users to deps.dev:version directly for PyPI/Maven/Cargo/Go, which serves as an alternative pathway.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by listing the exact return fields (name, summary, record_count, owner/org, url) and the pointer to query_layer/layer_info. However, it does not disclose any potential side effects, pagination behavior, or error conditions beyond what the schema already provides. This is adequate but not deeply transparent.

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 concise sentences. The first states the action and scope, the second lists the return values and provides a workflow hint. No redundancy or filler; every word earns its place. This is a model of concise, well-structured documentation.

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 search tool with optional parameters and rich annotations, the description is quite complete. It enumerates all return fields and advises the next step (using the returned URL with query_layer/layer_info). It does not discuss empty-result behavior or sorting, but those are minor given the tool's simplicity. The presence of a robust schema and annotations means the description does not need to over-explain.

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 describes all three parameters (limit, query, org_id) with clear descriptions, covering 100% of them. The description only re-emphasizes the 'keyword' search behavior and does not add new parameter-level detail. Per the rubric, baseline 3 applies when schema coverage is high, and the description does not significantly augment the parameter semantics.

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

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

The description clearly states the tool's function: searching Allegheny County GIS datasets by keyword. It specifies the resource (geospatial datasets), the action (search), and the scope (parcels, addresses, zoning, public works). It also differentiates from sibling tools like query_layer and layer_info by framing this as the discovery step that returns URLs for those tools.

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

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

The description provides a clear workflow: after searching, pass the returned Feature Service URL to query_layer or layer_info. This implies when to use this tool (for finding datasets) versus the alternatives (for inspecting/querying a specific layer). However, it does not explicitly state 'use this when you need to discover datasets' or mention any exclusion scenarios, 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 mark read-only, idempotent, non-destructive; description adds substantial context: BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation flagging, and return format (character offsets, similarity scores). No contradiction.

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

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

Five sentences, front-loaded with the core action, and every sentence adds unique value: purpose, usage scenario, integration, algorithm details, and limits. Dense but well structured with em-dashes and semicolons.

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, so the description compensates by explaining the output passages, character offsets, similarity scores, truncation behavior, and pairing with ask_pipeworx_grounded. It is fully self-sufficient 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 coverage is 100%, so baseline is 3. Description adds concrete query examples and clarifies the text param with real-world use cases (SEC 10-K, article, long tool result), plus limit default context. This adds meaningful 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 states a specific verb+resource: 'Semantic search INSIDE a fetched record' returning top-N passages. It distinguishes from siblings by contrasting with ask_pipeworx_grounded and emphasizing the in-record scope.

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

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

Explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and how it saves context. Names ask_pipeworx_grounded as the paired alternative, providing clear integration instructions.

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

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

The description adds valuable behavioral details beyond the annotations: OAuth account requirement, return of subscription id, feed always on, optional email/SMS, phone verification, and SMS cap. However, it omits the webhook delivery channel from the main description (only in the schema), which is a minor transparency gap.

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

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

The description is concise yet information-dense, with each sentence earning its place. It is well-structured: purpose and return value first, then auth requirement, then supported types, then delivery channels. No redundant text, and it is appropriately sized for the tool's complexity.

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

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

For a tool with 3 parameters and no output schema, the description covers the key aspects: purpose, return value, auth, supported types, and most delivery options. It omits webhook from the main text, but the schema fully documents webhook behavior, so the description is mostly complete though slightly incomplete in that regard.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description enhances parameter understanding with concrete examples (e.g., sec_8k items:['5.02'] = officer change, polymarket_edge topic:'fed', fred_series series_id:'UNRATE') and delivery caveats (phone verification, 10/day cap), adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and lists supported types and delivery channels, which further clarifies its scope.

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

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

The description provides clear context for when to use the tool (to create a subscription) and includes specific examples for supported types and delivery options. It does not explicitly name alternatives or state when not to use it, but the purpose is distinct enough that an agent can infer appropriate usage.

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

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

Annotations already cover readOnly, openWorld, idempotent, and destructive hints. The description adds meaningful context beyond annotations: results are drawn from the live catalog, return structure is category-bucketed with exact tool+argument shapes, and behavior varies by whether `topic` is supplied. This goes beyond the annotated safety profile, though it doesn't discuss pagination or error cases.

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

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

The description is a dense, single paragraph that front-loads the core purpose and usage. The opening list of user-style questions ('what can I ask Pipeworx?') is a useful quick-identifier, and every subsequent clause adds necessary information about output, invocation, and positioning. No wasted sentences.

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

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

No output schema exists, so the description must explain return values – it does: 'Returns category-bucketed example questions ... each with the exact tool + argument shape.' It also covers the simple input (optional topic), both invocation modes, and the tool's place in the onboarding flow, making it complete for a tool with these annotations and one optional param.

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

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

The schema already describes the `topic` parameter with a full list of allowed values at 100% coverage, so baseline is 3. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a cross-category spread, enriching the schema without redundancy.

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 is 'the onboarding entry point' that returns 'category-bucketed example questions' with 'the exact tool + argument shape' – a specific verb+resource with clear scope. It differentiates from siblings like discover_tools and ask_pipeworx by positioning itself as the first step for deciding what to ask.

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 gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools, implying when to move on. It also explains the two invocation modes – no args for full spread or pass `topic` for focus – making the when-to-use and how-to-use clear.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement (auth model) and deactivation instead of deletion (data retention semantics). These details give the agent a clear picture of side effects and constraints, complementing the official hints.

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

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

The description is two concise sentences. The first sentence front-loads the action; the second adds critical behavioral nuance. No redundant or verbose phrasing.

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

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

For a tool with one parameter and no output schema, the description covers the essential aspects: what it does, who can use it, and the side effect on historical data. It references recent_alerts, providing a complete picture 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?

The input schema already documents the single parameter 'id' with 100% coverage, so the description adds little beyond repeating 'by id.' The baseline of 3 applies because schema does the heavy lifting, and the description does not introduce new parameter meaning.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and adds distinguishing details: ownership enforcement and deactivation rather than deletion. This differentiates it from siblings like subscribe and 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 clear context on when to use the tool (canceling your own subscription) and the effect on historical data, suggesting a relationship to recent_alerts. It does not explicitly name alternatives like list_subscriptions, but the context is sufficient for an agent to infer appropriate usage.

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

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

The annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant context: the SEC EDGAR + XBRL fast path for financial claims, automatic fallback to a grounded pipeline for other claims, the return of verdicts with evidence and citations, and consolidation of multiple sequential calls. This goes well beyond the annotations and provides a clear behavioral model.

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

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

The description is dense but every sentence earns its place: examples of user phrasing, a clear usage directive, the financial-vs-other routing distinction, and the output structure. It is front-loaded with the purpose and avoids fluff, making it concise for the complexity it covers.

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

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

Without an output schema, the description explains return values (verdict, actual value with citation, reasoning). It also covers routing logic, edge cases (inconclusive/unsupported verdicts), and the efficiency benefit. It is comprehensive and leaves no major gaps for an agent to misuse the tool.

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

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

The input schema provides 100% coverage with detailed descriptions for both parameters (claim and tolerance_pct). The tool description does not add significant meaning beyond the schema; it references the judgment logic but does not elaborate on parameter formats or constraints. Per rubric, a high-coverage schema sets a baseline of 3, which is appropriate here.

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

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

The description explicitly states the tool's core function: natural-language claim verification against authoritative sources, with specific verb ('verify') and resource ('claims'). It distinguishes itself from sibling tools by focusing on factual correctness with verdicts, and even delineates sub-cases (company-financial vs. other claims). This is a highly specific and unambiguous 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 provides a clear directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for different claim types. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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