Arcgis Peterborough

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds meaningful behavioral context: the default free model, the need for a BYO Anthropic key with direct payment, and the exact per-model response shape. It also clarifies that it performs live probing, which is not contradictory to the readOnly hint. No contradictions found.

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

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

Two sentences, front-loaded with the primary action, followed by cost/return details and use cases. Every piece of information 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 provides a clear overview of behavior, return shape, model options, and use cases. Since there is no output schema, the per-model return structure is essential and included. It could mention error/rate-limit behavior, but overall it's complete for this tool's purpose.

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

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

Schema coverage is 100% with each parameter described. The description adds a cost implication for _apiKey and names the default model, but doesn't meaningfully expand the structural semantics beyond the schema. This is baseline 3.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs') and defines the visibility score outcome (0-100 per model). This clearly distinguishes it from siblings like scan_competitor_ai_presence by focusing on general brand/topic scoring rather than competitor scanning.

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

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

The description lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default vs BYO key options, giving clear context for when to invoke it. However, it doesn't explicitly exclude alternatives or mention when a sibling like scan_competitor_ai_presence would be more appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description aligns with these, so no contradiction. The description adds valuable context beyond annotations: it discloses that the tool routes to 5,529 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and works on every tier in one fast call. It doesn't disclose rate limits or failure modes, but the annotations cover the safety profile, so a 4 is appropriate.

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

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

The description is somewhat long (about 180 words) but every sentence earns its place: it provides a priority directive, lists supported domains, gives trigger phrases, examples, and escalation paths. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured logically from when-to-use to how-to-use to when-not-to-use. Could be tightened slightly, but the density is high.

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 single-parameter tool with a rich description that covers purpose, usage, scope, examples, and alternatives. There is no output schema, but the description explains what the return value looks like (structured answer with stable pipeworx:// citation URIs). Given the tool's simplicity (only one natural-language parameter), the description is thorough enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% and the only real parameter is 'question' with five documented aliases. The description explains what to put in the parameter (natural language questions, factual queries) and provides six concrete examples of valid inputs. Since the schema already covers parameter names and aliases, the description adds meaningful usage context without repeating syntax.

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 ('routes', 'returns') and resource (5,529 tools across 1,455 verified sources) and clearly distinguishes this tool from siblings by naming ask_pipeworx_grounded and deep_research as step-up alternatives. It explicitly states this is the default entry point and lists concrete example queries.

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

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

The description provides extensive when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', 'Step up only when needed' with explicit alternatives listed, and gives concrete trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It also clarifies scope boundaries by naming what deep_research and ask_pipeworx_grounded are for.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds beta status, current equivalence to ask_pipeworx (no active candidate), and the comparison process against the stable router. No contradictions; provides meaningful behavioral context beyond annotations.

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

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

Three sentences, each providing essential information: beta identity, current state, and usage guidance. No filler, but slightly longer than strictly necessary.

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?

Completeness is strong for a router: it specifies it is identical to ask_pipeworx, shares the same response shape, and clarifies it is not a fallback. While output schema is absent, references to 'same response shape' and the sibling tool's existence partially compensate. Could explicitly state return format but overall adequate.

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

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

Schema description coverage is 100% with all parameters documented as aliases for 'question'. The description only says 'same arguments' without adding new semantics, so 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?

Specific verb+resource: it is a beta universal router that routes questions to 5,529 tools, explicitly distinguishing itself from the stable ask_pipeworx. The description clearly states its role as an experimental edge.

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: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that it is a full working router, not a fallback. It also contrasts with the stable router and mentions results are compared for merges, giving clear when-to-use context.

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

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

Annotations already cover readOnly, idempotent, openWorld, non-destructive. The description adds grounding mechanics ('uses ONLY what the tool result contains'), the explicit refusal structure with specific refusal_reason values, and the one-extra-LLM-call tradeoff, going well beyond the annotation flags.

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

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

The description is dense but front-loaded with the key differentiator ('hallucination-resistant') and structured with clear sections for behavior, return, and usage guidance. While the first sentence is long, it contains no filler and every clause earns its place.

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

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

Despite no output schema, the description fully documents the response shape on both success and refusal, enumerates failure reasons, and gives concrete use cases. Combined with the annotations, this gives an agent everything needed to decide invocation and interpret results.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description doesn't add parameter-specific syntax beyond the schema, matching the baseline 3 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 identifies this as a hallucination-resistant answer mode that routes to the appropriate tool and extracts answers strictly from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and 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?

States exactly when to use: high-stakes reads where answers will be quoted, cited, or acted on, with examples. Also gives exclusion: prefer ask_pipeworx for casual lookups, and notes the extra LLM call cost, providing a clear when/not alternative.

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

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

The description goes far beyond the annotations by disclosing detailed behavioral traits: the resolver contract ('market_match_confidence', 'market_match_score', 'suggestions'), safety short-circuits ('status:"low_confidence_match"'), closed-market handling ('status:"market_closed_or_inactive"'), illiquid-wide-spread warnings, GDELT fallback behavior, and cancellation-rule parsing. This is exceptional behavioral disclosure, and it does not contradict the readOnlyHint or other annotations.

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

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

The description is long but densely structured with clear headers ('CLASSIFIERS', 'FAN-OUT EXAMPLES', 'RESPONSE SHAPES', 'RESOLVER CONTRACT', 'SAFETY'). It is front-loaded with the core purpose and usage, and every section earns its place by providing actionable details for a complex tool. The organization makes the length navigable rather than bloated.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It details response shapes (result.market, result.analysis, result.evidence), resolver behavior, status codes, edge cases, and cancellation risks. An agent would have enough information to correctly invoke the tool and interpret its results without additional documentation.

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

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

Despite 100% schema coverage, the description adds substantial parameter-level meaning: it defines the acceptable forms for 'market' (slug, URL, or question text), explains 'depth' via concrete fan-out examples, and specifies the response-size implications of 'include_raw' (~20KB vs 50KB-500KB). This goes well beyond the schema descriptions and helps agents select correct parameter values.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains what the tool does and distinguishes it from generic research tools by focusing on Polymarket bets with market resolution and classification. The classifier list and fan-out examples reinforce the tool's unique identity.

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 scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. However, it does not explicitly mention when not to use it or name alternative sibling tools (e.g., polymarket_edges) that might be better suited for certain edge-detection tasks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: data sources (SEC EDGAR/FAERS), fiscal-year handling, sorting by primary metric, and output format with citation URIs. This exceeds what annotations alone provide.

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

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

The description is detailed but well-structured, front-loaded with the core purpose and followed by type-specific details. The opening quote examples add some length but serve as useful triggers for the LLM. Every sentence contributes information, though it could be slightly tightened.

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 format ('paired data + citation URIs') and sorting behavior. It covers data sources, fiscal-year nuances, and scope. It could specify the exact structure of paired data or edge cases, but generally provides enough context for a powerful comparison tool.

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

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

Schema covers both parameters with descriptions, so baseline is 3. The description adds color about what each type returns (10-K metrics, FAERS counts) but doesn't significantly alter or deepen parameter meaning beyond the schema. It's adequate but not exceptional.

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 one parallel call, with specific data sources per type (SEC EDGAR for companies, FAERS for drugs). This distinguishes it from siblings like entity_profile, which likely handle single entities.

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

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

It explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities and highlights efficiency ('Replaces 8–15 sequential lookups'). However, it does not name specific alternative tools or state when not to use it, 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 (readOnlyHint, openWorldHint, idempotentHint) are supplemented with substantial operational detail: account/pricing gate, parallel tool routing, findings packet structure, gaps[] never-invented policy, contradictions[] for standard/thorough, semantic excerpting, and latency. No contradictions with annotations; the description adds far more than the structured fields.

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 account gate and the core differentiator ('NOT open-web search'). Every sentence carries non-redundant operational or selection information, though it could be tightened with bullet points; still 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?

With no output schema, the description takes on the burden of explaining return values—it specifies the findings packet fields, gaps[], contradictions[], hop, and citation_uri resolvability. It also covers latency, prerequisites, and alternatives, making the tool fully usable from the description alone.

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

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

The schema already covers both parameters at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by tying depth values to hop behavior and gap recovery, and by illustrating the question parameter with broad/multi-part examples, thus 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?

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition into facets routed to 5,529 tools. It explicitly distinguishes from siblings like ask_pipeworx ('For a single lookup use ask_pipeworx') and defines the niche as broad/multi-part structured-data questions.

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' with concrete examples. It names exclusions, directing single lookups and breaking current-news to ask_pipeworx, and even adds an account-tier conditional ('If you are not signed in, use ask_pipeworx instead'). Alternatives are explicitly named, meeting the highest bar.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is already known. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states that results are 'ready to call directly, no second schema lookup needed.' This discloses the return format and a key convenience behavior, going beyond the annotations.

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

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

The description is well-structured but slightly verbose due to the long list of domains. However, each element earns its place: the purpose, use cases, covered domains, return details, and the 'Call this FIRST' directive are all useful. It is front-loaded with the main verb and purpose in the first sentence, so the structure is effective, though it could be tightened without losing value.

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

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

Given that this is a simple discovery tool with no output schema, the description covers the essential aspects: what it does, when to use it, what it returns (top-N tools with schemas), and the fact that results are directly callable. It does not mention error cases or pagination, but for a tool with this low complexity and rich annotations, the description is sufficiently complete for an agent to use it effectively.

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

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

Schema description coverage is 100% and the schema thoroughly documents each parameter, including aliases and examples for the query field. The description itself does not add parameter-level details beyond restating that the query is a description of the data or task. With full schema coverage, the baseline of 3 is appropriate; the description contributes little additional 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 purpose: 'Find tools by describing the data or task' with a specific verb and resource. It also explicitly lists the domains it covers (SEC filings, financials, FDA drugs, etc.), distinguishing it from all siblings which are domain-specific tools. The phrase 'Call this FIRST' further differentiates it 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?

The description provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives both affirmative use cases and an explicit exclusion ('not just one answer'), effectively guiding the agent on when to select this tool over direct tools.

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

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

Beyond the readOnly/idempotent annotations, the description discloses data sources, return fields, filing count limit ('up to 5'), sort order, fallback behavior ('GDELT→GNews'), and a soft-fail condition for patents. These operational details add real value.

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

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

The description is long but densely informative and logically organized: trigger examples, core purpose, preference rule, fanout details, return fields, and input requirements. It could be trimmed slightly, but every sentence serves a purpose given 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 sufficiently explains the return composition (cik, filings, fundamentals, patents, news, LEI) and handling of unsupported name inputs. It also notes source fallbacks and deprecations, making it 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 coverage is 100%, and the description largely restates what the schema already provides (ticker/CIK, names not supported). It adds concrete examples ('AAPL', '0000320193') but no material new meaning, so baseline 3 is appropriate.

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

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

The description states it produces a 'full cross-source profile of a US public company in ONE parallel call' and lists concrete example queries and response components. It clearly distinguishes itself from chaining single-source lookups with 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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 gives trigger phrases, states when to prefer this tool ('when the user asks for a holistic view'), and provides an excludion: 'names not supported (use resolve_entity first if you only have a name).' This is strong when-to-use/alternative 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?

The description aligns with but does not add substantial behavior beyond annotations. Annotations already declare destructiveHint=true and idempotentHint=true, and the description simply restates the deletion action. The added nuance about 'clear sensitive data' is a use-case note rather than a behavioral disclosure, so it earns a baseline 3.

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-loads the core action, and then adds concise usage guidance and related tool context. Every sentence contributes meaning 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 simple one-parameter tool with no output schema and strong annotations (destructive, idempotent), the description covers purpose, usage scenarios, and relationships to sibling tools. It is appropriately 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%, and the property description 'Memory key to delete' fully explains the 'key' parameter. The tool description only mentions 'by key' without adding new semantic detail, so it does not elevate beyond the schema's baseline value.

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 the sibling tools 'remember' and 'recall' by indicating it is the deletion counterpart, and the mention of 'key' specifies the scope of operation.

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 use cases are provided: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear context for when to invoke the tool, though it does not explicitly contrast with alternatives or state when-not-to-use, making it 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?

The description discloses that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds behavioral context beyond the readOnlyHint and idempotentHint annotations, though it does not discuss edge cases like handling large pages or failures.

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 are tightly packed: the first states the primary purpose, the second explains the process and output, and the third lists practical use cases. No filler or repetition, and key information is front-loaded.

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

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

For a simple 2-param tool with strong annotations, the description fully covers what it does, how it works, and what output to expect (a single text blob in standard llms.txt format). The use-case list adds practical context, making this complete.

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

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

Schema coverage is 100%, with both url and max_links having descriptive text. The description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts, emits) and distinct use cases (client indexing, personal project, competitor audit). This differentiates it from sibling tools that audit AI presence rather than generate files.

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 three concrete usage scenarios ('getting a client's site indexed', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), giving clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral value by specifying what information is retrieved (fields, geometry type, count, capabilities), going beyond the annotations and adding context about the tool's output.

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

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

The description is a single, front-loaded sentence that immediately states the action and enumerates the returned items. Every word contributes information; 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 the tool's simplicity (one parameter, no output schema), the description is sufficiently complete. It lists the key returned elements and the required input, making the tool's behavior clear. Annotations cover safety and idempotency, so no additional context is needed.

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 'url' parameter with 100% coverage, including an example. The description only says 'by url', which adds no new semantic detail beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description uses a specific verb ('Get') and identifies the resource (ArcGIS Feature/Map Service layer's schema) along with concrete outputs (fields, geometry type, record count, capabilities). It clearly distinguishes from siblings like query_layer by focusing on schema rather than data.

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

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

The description clearly implies when to use the tool: when you need schema information for a layer. It does not explicitly mention when not to use it or name alternatives, but the context is specific enough that an agent can select it appropriately.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is clear. The description adds context beyond annotations by specifying the return fields (id, type, params, created_at, etc.) and the scope ('caller's active subscriptions'), which is useful behavioral information. 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 two sentences, front-loaded with the action and return fields, then provides usage guidance. Each sentence earns its place with no fluff or redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete: it states what is returned, the scope, and the intended use cases. Annotations cover safety, and the schema covers parameters, so the description fully rounds out the context.

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

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

Schema has 100% description coverage for the single parameter include_inactive, with a clear description. The tool description adds minimal parameter-specific meaning beyond reinforcing that only active subscriptions are listed by default, but this is implied by the schema and description. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List the caller's active subscriptions.' It also distinguishes from siblings by noting the purpose of reviewing subscriptions before adding more or finding an id to cancel, which relates to subscribe/unsubscribe tools.

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

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

Explicit usage guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool relative to adding or canceling subscriptions, effectively differentiating it from subscribe/unsubscribe.

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

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

Discloses rate limiting (5 per identifier per day), free status (doesn't count against quota), the claim_token workflow for checking resolution, and that the team reads digests daily. Annotations only set four false hints, so the description carries the full behavioral burden and does so thoroughly.

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?

Nine sentences, each earning its place. The description is information-dense with no redundancy: purpose, usage exclusions, claim_token mechanics, rate limits, and quota impact are all covered efficiently.

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 fully specifies when to use, when not to use, the claim_token workflow, rate limits, and what content to include in the message. Despite no output schema, it clearly explains what a report returns (claim_token) and what passing it back later provides.

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

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

Schema description coverage is 100%, with each parameter fully documented (e.g., claim_token explains the pwfb_… token and what it returns). The description adds no new parameter-level semantics; it only reinforces usage patterns already present in the schema.

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

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

The description uses a specific verb ('Tell the Pipeworx team...') and enumerates the feedback types: broken, missing, or needs to exist. It clearly distinguishes from sibling tools by being the dedicated feedback channel for this Pipeworx connection.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and provides a clear exclusion: do not use for tools from other MCP servers, with direction to file elsewhere. The guidance is unambiguous and actionable.

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

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

The description discloses that the data is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and notes 'Cached 5min-1h depending on window.' This adds meaningful context beyond the annotations, which already indicate read-only and non-destructive behavior. It also clarifies the data's origin and freshness.

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: a clear one-sentence summary, a results line, a numbered use-case list, and a concise data-source/caching note. Every sentence adds distinct value without redundancy or padding, 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?

The tool has one optional parameter (fully covered by schema), clear annotations, and a description that explains the return content (top tools, top packs, total call volume), use cases, data source, privacy, and caching. It is fully complete for an agent to decide when and how to invoke it, even without an output schema.

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

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

The only parameter, 'window', is fully described in the schema with 100% coverage, including the enum values and their semantic difference (hot vs steady-state). The tool description merely mentions the window options without adding extra interpretation, so it meets the baseline for schema-sufficient parameters.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' The opening phrase 'What other AI agents are calling on Pipeworx right now' provides a specific, distinctive purpose that separates it from sibling tools like discover_tools or ask_pipeworx.

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

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

The 'Useful for:' list gives explicit scenarios (discovering hot data sources, confirming canonical tool choice, aligning use case with agent needs), but does not mention when not to use it or name alternative tools. This is clear guidance but lacks exclusion/alternative comparisons.

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

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

The description goes far beyond the readOnly/openWorld annotations by disclosing internal logic (monotonicity checks, partition-sum, Jaccard semantic anchor), response structure, placeholder filtering, and live CLOB depth pricing. It warns about non-tradable edge with realizable_edge_pp <= 0, adding significant operational context without contradicting annotations.

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

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

The description is long but tightly organized: each segment covers a distinct aspect (modes, semantic anchor, partition filter, response, fill check) with no filler. It is front-loaded with the purpose and uses clear typographic cues (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for navigation.

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 comprehensively covers response fields, edge cases (null arb when placeholder fraction >20% returns null), and the critical fill-check caveat. It even cross-references a sibling tool for custom sizing, making the tool self-contained and well-integrated.

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 provides only basic descriptions for event and topic, the tool description expands each with concrete examples (e.g., 'fed-decision-may-2026'), explains the no-arg mode, and details mode-specific behavior and response fields. This fully compensates for any schema brevity.

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 immediately states the core purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (no-arg trending_scan, event, topic) and differentiates itself from sibling tools like polymarket_fill_risk by pointing users to that tool for custom sizing.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It recommends event for a specific market and explains cross-event vs single-event scenarios. It also advises against trading when realizable_edge_pp <= 0, a critical when-not-to-use instruction.

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 extensive context beyond the readOnly/idempotent annotations: detailed model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure, edge_pp_net after slippage, Kelly caps, 24h-move warning, diagnostics, and 1h KV caching. It also discloses the Fed bets exclusion and why, which annotations would never convey. 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 long but densely structured with clear section labels (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It front-loads the core purpose and every sentence contributes unique technical or behavioral detail, though the sheer length skirts conciseness limits.

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 thoroughly covers return structure (by_segment, fed_candidates, diagnostics), key fields (edge_pp_net, kelly_fraction, market.liquidity), and failure modes (funnel counters, filter_skips). It also explains caching and edge-case behavior (placeholder slug filter partition skip), making it complete for a complex tool.

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

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

Schema already describes all 9 parameters (100% coverage), giving a baseline of 3. The description enriches this by explaining how knobs interact: min_liquidity/max_spread_pp enforce tradeable edges, min_partition_leg_kelly targets per-leg Kelly, min_kelly only applies to single-leg opportunities, and slippage context (zero fees but bid/ask). This cross-parameter context adds value beyond the schema.

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

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

States it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear user need ('what should I bet on today'). This distinguishes it from sibling tools by specifying the unique Pipeworx disagreement signal and the discovery-oriented 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?

Provides a clear use case for discovering betting opportunities without paging hundreds of markets, and explains knob effects (min_liquidity/max_spread_pp drop unrealizable edges). However, it doesn't explicitly name alternatives or state when not to use this tool vs polymarket_arbitrage or edge_tracker, 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 already signal read-only/idempotent; description adds rich behavioral context: daily snapshot cadence, gaps mean no scan on cache-miss, 60-day TTL limit, daily-close decay basis (not intraday), and detailed explanation of response fields like expired[]. 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 earns its place. It uses clear sections (Args, RESPONSE, LIMITS) and front-loads the core purpose. The density is justified by the complexity of the response format and limitations.

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, yet the description fully specifies return fields (tracked[], expired[], snapshot_dates[]) with their semantics and limitations. It also covers parameter defaults, history depth, and data gaps, making it complete for an agent to invoke and interpret results.

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

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

Schema covers 100% of parameters with descriptions; the description reiterates defaults and adds 'max 30' but does not significantly extend the semantics. Baseline 3 is appropriate since the schema already carries the 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 a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the question 'how long has this edge existed and is it shrinking?'. It differentiates from siblings like polymarket_edges by focusing on historical persistence and decay, not current edge values.

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

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

Provides clear usage context by framing the tool's value ('a fresh wide edge and a 3-week-old wide edge are different trades') and explaining the response structure. However, it does not explicitly name alternatives or state when not to use this tool, stopping short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds substantial behavioral context beyond that: it walks the order-book ladder, reports partial-fill risk converting an arb into an unhedged directional position, returns per-leg fill details, and names forced-directional-risk legs. There is no contradiction with the annotations; the term 'check' aligns with readOnlyHint.

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

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

The description is front-loaded with a clear purpose sentence and every segment adds useful information, but it is delivered as a single dense paragraph with heavy capitalization and long lists. It is appropriately sized for the tool's complexity, yet slightly less structured than optimal, so it earns a 4 rather than a 5.

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

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

With no output schema, the description fully compensates by enumerating single-market return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), basket return fields (theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk), and failure conditions such as unhedged directional exposure. It is contextually complete for a complex tool.

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

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

Schema coverage is 100% for all four parameters, giving a baseline of 3, but the description adds mode-dependent semantics not captured in the schema: size_usd means max spend on buys vs target proceeds on sells, and in basket mode it represents settlement notional S (shares per leg, each paying $1). It also clarifies the default side derivation from the partition sum, enriching meaning beyond the schema.

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

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

The description opens with a specific verb-resource pairing: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as the actions it should precede, and it enumerates both single-market and basket modes with their respective outputs.

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 contains explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also defines mode selection with 'REQUIRES one of market (single-market mode) or event (basket/partition mode),' giving clear conditions and avoiding ambiguity about 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?

Discloses rich behavioral details beyond annotations: the two modes, compatibility_warning firing conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the limitation that many pre-mapped topics are non-tradeable. This far exceeds what annotations convey.

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

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

Long but structured with TWO MODES and SAFETY FIELDS labels. Every sentence adds behavioral value, though it borders on dense. Front-loaded with purpose and then expands into edge cases, appropriate for a complex cross-venue comparison 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?

Despite no output schema, the description enumerates response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and covers edge cases and failure modes. This makes the tool fully understandable for invocation and result interpretation.

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

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

Even though schema covers all three params, the description adds substantial semantic context: topic values list, how overrides work, and example values. It explains the interaction between topic and explicit params, which is not apparent from the schema alone.

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: computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes this from sibling tools like polymarket_arbitrage by explicitly naming both venues and the concept of equivalent bet shapes.

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 usage modes: `topic` shortcuts and explicit ticker/slug pairings, with clear examples. It also gives when-not-to-trust results via compatibility_warning cases and the caveat 'pre-mapped ≠ tradeable', effectively guiding the agent on when to use custom pairings.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by specifying that it returns attribute rows and optionally geometry, and gives a sampling convention (where='1=1' + out_fields='*'). This exceeds the annotation baseline.

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

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

Two sentences: the first explains the core capability and key parameters, the second offers a practical sampling tip. No fluff, front-loaded with the most important information.

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

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

The description covers the tool's main behavior (query, return rows/geometry), the source of the URL, and common parameter patterns. Given the rich schema and annotations, no critical context is missing for a query operation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic clarity by framing `where` as SQL-like, `out_fields` as comma-separated, and demonstrating typical usage with examples. This enhances understanding beyond raw property names.

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 queries an ArcGIS Feature/Map Service layer by URL, explicitly identifying the resource and action. It also references search_datasets as the source for the URL, distinguishing it from sibling tools.

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

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

The description provides clear context: the URL comes from search_datasets, and it hints at when to use the tool (to query a layer). It does not explicitly mention alternatives or exclusions, but the guidance is strong enough for an agent to know when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context about scoping to the identifier and the two modes (retrieve vs list). It does not mention edge cases like missing keys or return formats, but for a simple read tool this is adequate.

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

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

The description is three sentences long, front-loaded with the main action, and every sentence adds value: core function, usage examples, and scoping/pairing. 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?

The tool is simple with one optional parameter and no output schema. The description covers purpose, usage context, scoping, and related tools. It implicitly conveys what the tool returns (a value or list of keys), which is sufficient 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?

Schema coverage is 100% for the single parameter 'key', and the schema description already states 'Memory key to retrieve (omit to list all keys)'. The description adds no new parameter-level information beyond repeating the same behavior, so it meets the baseline of 3 without exceeding it.

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: retrieve a saved value or list all saved keys. It uses a specific verb ('retrieve') and resource ('value previously saved via remember'), and distinguishes itself from sibling tools like 'remember' and 'forget' by naming them directly.

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 explains when to use the tool: to look up context the agent stored earlier without re-deriving it. It also mentions scoping to the user's identifier and pairs with 'remember' to save and 'forget' to delete, providing clear usage 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?

Descriptions adds substantial behavioral detail beyond the annotations: each alert carries source, citation_uri, and raw payload; mark_read semantics; polling works fine; alternative HTTP endpoint. The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description supplements this with concrete behaviors.

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

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

Two sentences, perfectly front-loaded with the core purpose. Each clause adds necessary information (return fields, filters, mark_read, alternative endpoint) without any filler. Highly efficient.

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

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

Despite having no output schema, the description explains what each alert carries (source, citation_uri, raw payload) and the behavior of mark_read and polling. For a read-only tool with good annotations and full schema coverage, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: e.g., 'type' exemplified with 'sec_8k', since requires ISO timestamp, and mark_read:true causes next call to show only newer events. This enhances the schema's brief 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 states the tool's function: 'Pull fired events from your subscription feed.' It uses a specific verb ('pull') and identifies the resource ('subscription feed'), and distinguishes itself from sibling tools like subscribe/unsubscribe/list_subscriptions by focusing on reading alerts rather than managing subscriptions.

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

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

The description gives clear usage context: it mentions filtering by type and since, polling, and the alternative endpoint for scripts/dashboards. It doesn't explicitly state when not to use it, but the guidance is strong enough for an agent to choose it appropriately.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses the multi-source fan-out, GDELT preference with GNews fallback on rate-limit/5xx, USPTO's soft-fail behavior due to API sunset, and the exact return structure (changes[] grouped by source, total_changes, citation URIs). This is rich behavioral 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 but every sentence carries essential information: query examples, source details, date formats, return shape, and alternative tool. It is front-loaded with the purpose and efficiently packs details without fluff.

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

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

Despite having no output schema, the description clearly explains the return format (changes[] grouped by source, total_changes count, pipeworx:// citation URIs) and covers edge cases like the USPTO API sunset. This makes the tool self-contained for invocation.

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

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

Schema coverage is 100%, so the description doesn't need to compensate. It adds value by providing concrete examples for `since` (ISO and relative shorthand) and recommending '30d' or '1m' for typical monitoring, which enhances the schema's baseline 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, using verbs like 'fans out to' and 'returns'. It provides multiple query paraphrases and distinguishes itself from the sibling tool entity_profile by contrasting the dynamic change feed with a 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?

Explicitly names entity_profile as an alternative for static profiles, and describes the fallback chain (GDELT→GNews) and source conditions (e.g., USPTO soft-fails after API sunset). This gives clear when-to-use and when-to-avoid 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?

Discloses behavioral traits beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and integration with recall/forget. This adds meaningful context not captured by annotations like idempotentHint or readOnlyHint, 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?

Three concise sentences with a clear flow: what it does, when to use it, and lifecycle details. No wasted words; every sentence contributes actionable information.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, usage, persistence rules, and related tools. It is self-contained and leaves no significant gaps for the agent.

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

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

The input schema has 100% description coverage for both parameters (key and value). The description adds no extra parameter details beyond confirming key-value pair storage, so the schema does the heavy lifting; 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 uses a specific verb 'Save data' and identifies the resource as key-value pairs scoped by identifier, with concrete examples of what to save. It distinguishes from siblings by referencing recall and forget, making the tool's role unambiguous.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward...' and names alternatives with 'Pair with recall to retrieve later, forget to delete.' This clearly tells the agent when to use this tool versus siblings.

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

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

Beyond annotations, the description discloses graceful degradation (GLEIF/OpenFIGI unavailability), explicit `unresolved` behavior, source labeling, and internal cascading through lookup endpoints. These details give an accurate operational picture without contradicting annotations.

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

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

The description is long but info-dense; every sentence contributes value. It could be better structured with bullet points for supported types, but the front-loaded examples and clear directives make it easy to scan.

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

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

With no output schema, the description covers return fields, input variations, failure modes, and citation formats. It also addresses both supported entity types fully and explains how the tool handles partial resolution, making it complete for a complex multi-source lookup 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%, but the description enriches meanings meaningfully: for 'company' it lists accepted input forms and resolved identifiers; for 'drug' it specifies RxCUI, ingredient, brand, and citation format. This goes far beyond the schema's one-line descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with explicit examples of intended queries. It distinguishes from siblings by emphasizing it provides the IDs other tools require, and the 'Use FIRST' directive uniquely positions it.

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 usage context: 'Use FIRST whenever you have a name but need an ID.' It enumerates supported types and input forms, and notes it replaces 2-3 manual lookups, making the when-to-use highly actionable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds meaningful behavioral context: it probes each entity by calling ai_visibility_check, ranks results, and returns score/confidence/signal density. This goes beyond what annotations reveal.

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

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

Three concise sentences: the first states the core function, the second explains the mechanism and use case, and the third describes the return format. No redundant or vague language; every sentence carries useful information.

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

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

The description covers the return shape (ranked list with score/confidence/signal density) and the primary use case. It doesn't mention potential multi-probe latency or partial failure behavior, but given the schema covers parameter constraints and annotations cover safety, this is adequately complete for an AI agent to decide on usage.

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

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

Schema coverage is 100% with each parameter well-described (e.g., entities includes 'First entry treated as the subject' and models lists supported values). The description adds the notion of "your brand + N competitors" which aligns with the entity schema but doesn't add significant new parameter-level meaning beyond that. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: "Compare AI visibility across multiple entities side-by-side." It specifies the action (compare), the resource (AI visibility), and the outcome (ranks by score, surfaces most/least recognized). This distinguishes it from the sibling tool ai_visibility_check, which is for single-entity checks.

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

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

Provides a clear use case ("competitive AI-marketing audits") and an example query ("does Claude know about us as well as our competitors?"). However, it doesn't explicitly say when to use this over alternatives like ai_visibility_check or compare_entities, though mentioning ai_visibility_check as the underlying probe gives some implicit contrast.

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, idempotent, and openWorld traits, but the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This goes 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 dense but well-structured: lead sentence defining the tool, usage guidance, return value list, ecosystem scope limitation, and failure behavior. Every sentence adds distinct value, and the length is justified by the composite nature of the 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?

Despite lacking an output schema, the description enumerates all summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, etc.) and mentions per-advisory detail, links, and alternative versions. It also covers limitations and graceful degradation, making it fully sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, with both package and version parameters already described clearly. The description does not add new syntax or format details beyond what the schema provides, so it sits at the baseline score of 3.

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

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

The description opens with a specific composite check definition, naming both deps.dev and bundlephobia and their specific data contributions. It clearly specializes in npm package evaluation, which distinguishes it from sibling tools like scan_competitor_ai_presence or validate_claim.

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

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

It explicitly states when to use the tool with examples ('is X safe / popular / small' or 'what does adding lodash cost me'). It also provides an exclusion for non-npm ecosystems, directing users to deps.dev:version for PyPI/Maven/Cargo/Go, giving clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds useful context about the returned fields (name, summary, record_count, owner/org, Feature Service url) and how to use the url, which goes 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?

Two sentences, no redundancy. The first sentence defines scope, the second specifies return values and workflow.

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 discovery tool with no output schema, the description covers what is returned and how to proceed (pass url to query_layer / layer_info). The sibling context reinforces this, and annotations cover safety.

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% description coverage for all three parameters (limit, query, org_id), including ranges and defaults. The description reinforces query examples but doesn't add new parameter syntax details, so it meets the baseline for well-documented schemas.

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

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

The description uses a specific verb ('Search'), identifies the resource ('City of Peterborough GIS open geospatial datasets'), and lists example content ('parcels, zoning...'). It also clarifies the output and downstream tools, distinguishing it from siblings like query_layer and layer_info.

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

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

It tells the agent that the returned URL should be passed to query_layer / layer_info, implying search_datasets is for discovery. It also gives example keywords and the default org, but doesn't explicitly state when not to use it (e.g., if you already have a dataset URL).

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, the 200K character cap with truncation flagged, and that returned passages carry character offsets for verification. This gives deep insight into the tool's behavior without contradicting annotations.

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

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

The description is concise yet information-dense, front-loading the core purpose, then usage context, technical details, and limitations. Every sentence adds value; there is no filler or repeated schema info.

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, so the description's mention of return values (passages, character offsets, similarity scores) is essential and well-covered. It also addresses edge cases (200K cap, truncation) and integration with sibling tools, making the description complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches the parameter meaning: it specifies what 'text' should be (fetched record like SEC 10-K), provides query examples ('supply-chain risk', 'drug interactions with warfarin'), and implies 'limit' via 'top-N'. While not necessary, this adds practical context that helps the agent formulate correct inputs.

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: 'Semantic search INSIDE a fetched record' with the ability to pass text and a natural-language query and receive top-N passages with offsets and scores. It distinguishes itself from siblings like ask_pipeworx_grounded by positioning itself as the retrieval step after fetching a record, 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?

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and it explicitly pairs with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells the agent when to use this tool and how it relates to alternatives.

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

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

The description discloses several behavioral traits beyond the annotations: the need for an OAuth account, persistence limitations, supported subscription types with examples, and delivery-specific requirements (phone verification, 10/day SMS cap). It also mentions the feed is always on and how to pull alerts. This adds significant context beyond readOnlyHint=false and idempotentHint=true.

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

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

The description is dense but well-structured, starting with the core purpose, then requirements, supported types, and delivery options. Every sentence contributes necessary information for a complex tool. While it is long, the complexity justifies the length, and it remains readable with clear separations between types and delivery channels.

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

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

The description covers the essential aspects: purpose, return value, account requirement, supported types (with examples), and delivery channels (including conditions like phone verification and daily caps). The schema provides complete parameter details, but since there is no output schema, the description could have elaborated slightly more on the response format beyond just the subscription id. Overall, it is fairly 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?

The parameter schema description covers 100% of the parameters with extensive type-specific examples. The main description repeats some of these examples (sec_8k items, polymarket_edge topic, fred_series series_id) but does not add substantial new meaning beyond what the schema already provides. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (create), the resource (subscription), and the nature (proactive monitoring, live-data event stream). It also mentions the return value (subscription id), and the presence of sibling tools like list_subscriptions and unsubscribe makes 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 provides clear context for use, including a required precondition (Pipeworx OAuth account), limitations (anonymous/BYO cannot persist), and how to consume the feed via 'recent_alerts or GET registry.pipeworx.io/alerts.json'. It does not explicitly name alternatives or state when not to use the tool, but the sibling tool names (list_subscriptions, unsubscribe) make the distinctions 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 readOnly/openWorld/idempotent/non-destructive, so the description doesn't need to restate those. Instead, it adds rich behavioral context: the output structure (category-bucketed questions with exact tool+argument shapes), the source (live catalog), and the differing behavior with and without `topic`. 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?

Despite its length, every sentence earns its place: it front-loads example queries, defines the tool's role, explains the return value, describes parameter behavior, and gives usage guidance. The structure flows logically from user intent to invocation details 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 explains what the agent will receive (category-bucketed example questions with tool call shapes) and how to use the optional parameter. It also places the tool within the broader tool ecosystem, making it complete for correct invocation in the onboarding context.

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

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

Schema coverage is 100% with a descriptive `topic` parameter. The description adds concrete examples ('finance', 'pharma', 'betting') and clarifies the effect of omitting the parameter (cross-category spread), providing a slight edge over the schema alone.

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 example queries and explicitly identifies the tool as 'the onboarding entry point' for a newly connected agent. It clearly states the resource (Pipeworx's capabilities) and the action (returning example questions with tool+argument shapes), and distinguishes it from siblings by positioning it as the first tool to use.

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 this FIRST when you do not yet know what Pipeworx can do for you'. It also names alternatives to learn about (ask_pipeworx, entity_profile, compare_entities) and explains how to focus via the `topic` parameter, making the guidance both clear and actionable.

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

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

The description goes beyond annotations by disclosing the ownership enforcement rule and the non-destructive behavior ('deactivated, not deleted'). It also explains the impact on historical events, adding valuable behavioral context that annotations alone do not provide. This is consistent with annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is two sentences, front-loaded with the primary action, and every sentence provides meaningful detail. 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 single-parameter, no-output-schema tool, the description covers the core purpose, key constraints (ownership), and side effects (deactivation vs. deletion). It could mention the return value or error conditions, but given the simplicity and annotations, the description is sufficiently complete.

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

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

The input schema already fully describes the id parameter with 100% coverage, including its source (returned by subscribe). The description adds minimal extra meaning beyond restating 'by id'. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly states the specific action: 'Cancel a subscription by id.' It identifies the resource (subscription) and the method (by id), distinguishing it from sibling tools like subscribe and list_subscriptions. The ownership constraint adds further precision about the tool's 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 implies usage context: use when you want to cancel your own subscription. It also provides an alternative for historical events via recent_alerts, and warns about ownership enforcement. However, it doesn't explicitly compare against alternative tools like unsubscribe vs. deactivating in another way, but the context is sufficient for typical selection.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, but the description adds crucial behavioral nuance: the distinction between could_not_verify (check did not happen, carries verification_error) and unsupported (no source covered), plus the tolerance_pct override semantics. This is the kind of detail agents need to interpret results correctly and is fully consistent with the annotations.

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

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

The description is dense but well-organized: trigger phrases, usage, pipeline routing, return format, and caller warnings each get a sentence or two. It is longer than ideal but every sentence earns its place given the tool's complexity. The structure is front-loaded and scannable, only missing a bulleted list to break up the return-value enumeration.

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 return values, and it does so thoroughly: verdicts, actual value with citation, reasoning, and both failure modes. It also explains the two execution paths and the tolerance override. For a 2-parameter tool with these edge cases, this is as complete as one could expect.

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

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

Schema coverage is 100% (both parameters have descriptions), so baseline is 3. The description adds value beyond the schema by explaining that tolerance_pct 'overrides the tolerance implied by the claim wording' and suggesting use for hallucination detection. It also gives example claim phrasings that make parameter intent concrete, justifying a score above baseline.

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

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

The description opens with natural-language trigger phrases and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It explicitly distinguishes itself from generic Q&A tools by describing the dual pipeline (SEC EDGAR fast path vs. grounded fallback) and notes it replaces 4–6 sequential calls, making its unique purpose unmistakable even among many siblings.

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

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

It clearly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the two internal paths and provides an important caller warning about could_not_verify vs unsupported. However, it does not explicitly name sibling tools to avoid or give a 'when-not' scenario, so it stops short of the highest tier.

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