Arcgis Detroit

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

Annotations already cover safety traits (read-only, idempotent, non-destructive). The description adds valuable behavior beyond those annotations: default model (free Workers AI), and that passing _apiKey probes Anthropic with direct billing to the user. It also discloses the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). No contradiction with annotations.

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

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

Four sentences, each earning its place: purpose, default model/cost, return format, and use cases. Front-loaded with the primary action and output, no redundancy or filler.

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

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

For a tool with 4 params, rich schema descriptions, and no output schema, the description provides a complete picture: what it probes, how many models, what the score range is, what the response contains, and which scenarios it serves. Nothing essential is left unexplained.

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

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

Schema description coverage is 100%, with each parameter already well-documented (e.g., models notes 'free default' and that Anthropic requires _apiKey). The description largely repeats schema details rather than adding new semantic meaning, so it stays at the 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 and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic' and immediately defines the output ('score visibility (0-100) per model'). It clearly distinguishes itself from sibling tools by focusing on multi-model visibility scoring rather than Q&A or entity comparison.

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that tell an agent when to invoke this tool. However, it does not explicitly name alternative tools or state when not to use it, so it stops 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 cover read-only/idempotent/open-world behavior, and the description adds useful context: it routes through 5,462 tools, fills arguments, returns stable pipeworx:// citation URIs, and is one fast call. It does not discuss failure modes or latency limits, but the added behavioral detail goes beyond the structured annotations without contradicting them.

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

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

The description is long but front-loaded: it starts with the headline 'PREFER OVER WEB SEARCH', then explains the mechanism, usage triggers, examples, and escalation paths. Some lists (sources, trigger phrases) could be trimmed, but every section adds value for a meta-tool with this complexity.

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

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

For a one-required-parameter tool with no output schema, the description fully covers what the tool does, what it returns (structured answer with citation URIs), when to use it, and which alternatives to escalate to. The examples and explicit coverage of news/breaking-news round out the context sufficiently for correct 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?

The schema covers all six parameters (question plus five aliases) with examples, so schema coverage is 100%. The description does not add parameter-level semantics, but with such complete schema documentation, 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?

Clearly states that the tool routes natural-language questions to the appropriate one of 5,462 verified data tools and returns a structured answer with citation URIs. It explicitly differentiates itself from ask_pipeworx_grounded and deep_research, so an agent can distinguish it from 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?

Provides comprehensive when-to-use guidance with trigger phrases ('what is', 'look up', 'find', 'get the latest') and concrete examples. It explicitly says to use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, covering when-not-to-use and alternatives.

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

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

Annotations already declare this as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: live candidate routing improvements, the current absence of an active candidate, the exact date the last candidate was retired, and that it currently matches ask_pipeworx exactly. This goes beyond the annotations and sets accurate expectations for an experimental tool.

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

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

Three dense, well-structured sentences. The description front-loads the beta identity and equivalence to ask_pipeworx, then explains the current state, usage, and experimental nature. Every sentence earns its place with no filler 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?

For a simple one-required-parameter router with no output schema, the description is complete: it explains what the tool is, its current state, when to use it, how it relates to the stable version, and that the response shape is identical. The schema handles parameter details, so no additional information 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 has 100% coverage, with all six parameters documented as aliases for the required 'question' field. The description adds no additional parameter semantics beyond stating 'same arguments,' which is redundant given the schema. Baseline 3 is appropriate because the schema already carries the full load.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx: a universal router with the same 5,462 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by its experimental routing improvements, and the explicit instruction 'Use it exactly like ask_pipeworx' makes its purpose obvious.

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 tells when to use this tool ('when you want the newest routing') and contrasts it with the stable router. It also clarifies that results are compared against the stable router to decide what merges, and that it is a full working router with no fallback, preventing misuse.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behaviors: it returns an explicit refusal with specific refusal_reason enums, includes evidence as verbatim quotes, and only uses what the tool result contains. This adds significant context 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 every sentence adds value: purpose, behavior, return format, use cases, cost tradeoff, alternative. It's slightly long for a single paragraph, but the information is front-loaded and well-organized. A list format could improve scannability, but current structure is acceptable.

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

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

With no output schema, the description fully specifies the return structure on success and failure, including all refusal_reason enum values. It also covers cost implications and usage context, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question.' The description doesn't add parameter-level detail, but the schema fully covers semantics. Baseline 3 is appropriate; no additional compensation needed.

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 for high-stakes reads' with a specific verb and resource. It explicitly distinguishes itself from sibling tool ask_pipeworx by noting it uses the same routing but adds extraction based only on tool result content.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts... prefer ask_pipeworx for casual lookups.' Also notes the cost tradeoff of one extra LLM call, giving clear alternative selection criteria.

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

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

The description significantly expands on annotations by detailing the resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits for low-confidence matches, closed-market status codes, fan-out behavior, parent-event extraction, and cancellation-rule parsing. These behavioral traits are not conveyed by the readOnlyHint or idempotentHint annotations.

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

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

The description is long but well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the main purpose. While every sentence contributes useful detail, the sheer length and exhaustive examples prevent it from being maximally concise.

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

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

Despite lacking an output schema, the description thoroughly documents result fields (market, analysis, evidence), status codes, edge cases (closed/dead markets, wide spreads), fallback mechanisms, and safety behavior. It is highly complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage with descriptive definitions for all three parameters (market, depth, include_raw). The description does not add substantial parameter-specific meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research), and distinct use cases ('should I bet on X', 'is there edge in Z'), differentiating it from sibling tools like polymarket_arbitrage 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?

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context. However, it does not explicitly mention alternative tools for exclusions, 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?

Even with annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral details: it performs a parallel call, pulls specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This goes far beyond the annotations to explain what actually happens.

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

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

The description is dense but every sentence earns its place. It front-loads the most common query phrasings, follows with a preference directive, and then details per-type behavior and output. No fluff or repetition; the long format is justified by the tool's complexity.

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

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

For a tool with two modes, multiple data sources, sorting behavior, and output details, the description fully covers selection criteria, invocation format, data semantics, and return value (paired data + citation URIs). Even without an output schema, an agent can understand what to expect from the call.

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 enhances both parameters: it explains that 'type' determines the data source and metrics (company pulls 10-K financials; drug pulls FAERS counts), and clarifies 'values' format (tickers/CIKs for company, drug names for drug) with concrete examples. This provides meaning beyond the schema's basic enum and array definitions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses a specific verb ('compare'), identifies the resource (companies/drugs), and distinguishes itself from sequential lookups and sibling tools by emphasizing a parallel call and specific use cases.

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 provides when-to-use guidance with trigger examples ('Compare X and Y', 'which is bigger/better/larger/more profitable', 'rank these companies') and a strong preference rule: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This clearly tells the agent when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: account requirements (free vs. paid 'thorough'), parallel decomposition into facets, the exact contents of the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[] on standard/thorough, semantic excerpting, and expected latency. This far exceeds what annotations alone convey and does not contradict them.

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

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

The description is lengthy (roughly 200 words) but every sentence carries substantive information: eligibility, purpose, use cases, exclusions, behavior details, performance expectations. It is front-loaded with the most critical caveat (account requirement) and then the main value proposition. While dense, the complexity of the tool justifies the length; it avoids fluff and is well-organized with parallel structures.

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

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

Despite lacking an output schema, the description fully explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions, hop field, citation_uri). It covers usage contexts, limitations, alternatives, authentication prerequisites, latency, and even the behavior for large records. For a tool with this many behavioral nuances, the description is remarkably 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 schema already provides 100% coverage of both parameters, including detailed enum descriptions for depth. The description adds value by explaining the real-world implications of each depth value ('depth:"standard" re-angles unanswered gaps... depth:"thorough" additionally chases the best leads'), which is not redundant with the schema. It also reinforces that question can be broad/multi-part, but that mostly repeats 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 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' and clearly distinguishes itself from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx'. It names the specific resource (structured data sources, 5,462 tools) and the verb 'researches/decomposes/routes', making the tool's scope unmistakable.

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

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

The description explicitly states when to use the tool: 'Best for broad/multi-part questions over structured data' and gives concrete examples. It also tells the agent when to use alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', with a rationale that deep_research returns mostly empty gaps for non-catalog topics.

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 meaningful behavioral detail: returns top-N tools with names, descriptions, and full input schemas (with curated examples), ready to call directly without a second schema lookup. This goes beyond annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the core function, followed by use cases and return behavior. The domain list is a bit long but each element adds value. No wasted words, though it could be tightened without losing meaning.

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

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

With no output schema, the description explicitly states the return format (top-N tools with schemas and examples) and the tool's role as the first call in a multi-tool environment. This gives the agent enough context to invoke it correctly without ambiguity.

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 (including aliases) documented with examples. The description reiterates natural-language input but adds no new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate when the schema handles the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools as a meta-search/discovery tool. The verb 'find' plus resource 'tools' makes it specific and unambiguous.

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

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

The description provides explicit when-to-use 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.' It does not explicitly mention when-not-to-use or name alternative tools, but the directive to call it first establishes a 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?

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: parallel fan-out across multiple sources, detailed return fields, fallback chains (GDELT→GNews), and a known API sunset with soft-fail behavior for patents. This is rich, non-obvious context.

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

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

The description is dense but every clause earns its place: example queries, priority directive, output summary, and fallback behavior. It front-loads the most important purpose and preference, then packs necessary details into a structured list of return fields.

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

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

For a complex tool with no output schema, the description fully accounts for all returned data (cik, filings with URIs, fundamentals, patents, news, LEI) and edge cases. It gives enough detail for an agent to invoke it correctly and know what to expect.

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

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

The input schema already fully describes both parameters with examples and constraints (100% coverage). The description repeats these details but adds little beyond the schema—mainly confirming the input format with concrete examples like 'AAPL' and '0000320193.'

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-resource pair ('full cross-source profile') and provides multiple example user queries to frame its purpose. It clearly distinguishes itself from chained single-source lookups and sibling tools like resolve_entity by specifying exactly what it does.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear alternative: 'use resolve_entity first if you only have a name,' and notes the unsupported input form.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds minimal context beyond 'Delete' and 'previously stored memory', but doesn't describe permanence or error handling. Since annotations cover the key behavioral traits, a mid-range score 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 two sentences: the first states the core action, the second provides usage guidance. No wasted words, and the most important information is front-loaded.

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

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

For a simple single-parameter delete operation, the description plus annotations (destructive, idempotent) and full schema coverage are sufficient. It includes usage scenarios and companion tool references, making it complete for an agent to select and invoke correctly.

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

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

The schema has 100% coverage for the single 'key' parameter with description 'Memory key to delete'. The description simply says 'by key' without adding new semantic details. With high schema coverage, baseline is 3, and no extra elaboration is provided.

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: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like 'remember' and 'recall' by focusing on the deletion action and the memory-store resource.

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 the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools 'remember and recall', providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it explains the process ('Fetches the page, extracts title/description/key links') and the output ('single text blob ready to drop at site-root/llms.txt'), which is especially important since no output schema is provided. No contradictions with annotations.

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

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

The description is compact and front-loaded with the primary action. Each sentence adds value: purpose, process/output, and use cases. 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?

Despite lacking an output schema, the description fully specifies the return format ('single text blob ready to drop at site-root/llms.txt'). Given the simple parameter set (2, fully documented) and clear annotations, the description covers all necessary context 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 description coverage is 100%, with both 'url' and 'max_links' already described in the schema. The description does not add extra parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on generating a file rather than checking visibility. The mention of AI crawlers further clarifies the unique purpose.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it does not mention when not to use it or name alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds specific output details (fields, geometry type, record count, capabilities) that go beyond annotations and explain what the tool effectively returns.

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?

Single, front-loaded sentence that uses the verb 'Get' and lists the output categories succinctly. Every word adds value; 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 read-only metadata tool, the description fully covers the purpose, input, and output. The explicit list of returned items makes up for the lack of an output schema, and annotations handle safety context.

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

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

The schema provides 100% coverage of the single 'url' parameter with a clear description and example. The description reinforces that the tool operates 'by url' but adds no new parameter-level details, so the 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 action ('Get') and the resource ('an ArcGIS Feature/Map Service layer's schema by url'). It enumerates the specific return items (fields, geometry type, record count, capabilities), distinguishing it from sibling data-query tools like query_layer.

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

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

The context is clear: this tool is for retrieving schema metadata, not for querying data. It does not explicitly mention alternatives or when-not-to-use, but the purpose is unambiguous enough for an agent to select it appropriately.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds context by specifying the scope ('caller's active subscriptions'), listing the returned fields, and noting the default behavior of excluding cancelled unless a parameter is set. It doesn't mention pagination or errors, but those are less critical for a simple read-only list.

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 purpose, followed by return fields and usage guidance. Every word earns its place; no redundancy or fluff.

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

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

For a simple read-only list tool with one optional parameter, the description is complete: it states purpose, scope, return fields, and when to use it. Annotations cover safety, and the schema covers the parameter, leaving no significant gaps.

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

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

The schema fully documents the only parameter (include_inactive) with a clear description. The tool description adds no additional meaning about this parameter, but since schema coverage is 100%, 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by focusing on read-only listing. It also lists the return fields, making the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the user when to use this tool versus alternatives (subscribe/unsubscribe), though it doesn't name them explicitly.

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

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

Despite annotations being all false hints, the description discloses valuable behavioral traits: rate-limiting ('Rate-limited to 5 per identifier per day'), quota independence ('doesn't count against your tool-call quota'), account implications, and the claim_token workflow for later lookup. It also sets expectations about response time ('reads digests daily') and feedback impact (roadmap).

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

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

The description is dense but every sentence carries operational value. It front-loads the core purpose, then flows logically through use cases, exclusions, message content guidance, claim_token mechanism, and operational notes. No filler or redundancy; appropriate size for the tool's complexity.

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

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

Even without an output schema, the description explains the return token and how to use it, covers constraints (rate limit, account requirements), and details the expected message format. It fully equips the agent to submit feedback correctly and follow up, leaving no critical gaps.

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

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

The schema already covers all parameters at 100%, so baseline is 3. The description adds semantic guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and illustrates the claim_token round-trip with a concrete invocation example, enhancing the agent's understanding of how to use 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this as a feedback channel versus sibling tools like ask_pipeworx or research utilities, and enumerates concrete use cases (bug, feature, data_gap, praise).

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug)...' and it names alternatives to avoid, stating 'if the tool came from a different MCP server... file it with that server instead.' It also clarifies how to identify Pipeworx tools, giving the agent unambiguous selection criteria.

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

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

Beyond the read-only and idempotent annotations, the description discloses caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). This adds significant context for the agent.

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

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

The description is well-structured: a clear opening statement, a bulleted list of use cases, and a succinct technical note. Every sentence adds value, and it is front-loaded with the core purpose.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers return contents, use cases, caching, and data sensitivity. It is complete for an agent to select and invoke confidently.

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 (100% coverage), and the description repeats the enum values without adding new meaning. Baseline of 3 is appropriate since the schema carries the semantics.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It uses a specific verb ('returns') and resource, and distinguishes itself from siblings by focusing on aggregate trending data rather than individual 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?

The description provides explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tools, and aligning use cases. This gives clear guidance on when to use the tool, even without naming alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond these: semantic anchor (Jaccard similarity threshold), partition filter (placeholder slug handling), and the fill check explaining when a signal is not tradable (realizable_edge_pp <= 0). It even cautions 'do not trade it,' which is critical behavioral disclosure.

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 is dense with information. It is structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. There is zero fluff or repetition; each sentence contributes to operational understanding, making the length justified for a complex tool.

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

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

Given there is no output schema, the description explains the response structure (opportunities[], partition_check, fill_check fields) in detail. It covers prerequisites, edge cases, filtering logic, and provides a pointer to a related tool for custom sizing. For a tool of this complexity, the description is remarkably complete, leaving no significant operational gaps.

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

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

The input schema already has descriptions for both params (100% coverage), but the description enhances them further. It gives concrete examples of event slugs ('fed-decision-may-2026'), explains what 'topic' does, and clarifies the difference between modes. This goes well beyond the schema's basic definitions, adding real value for parameter understanding.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states what the tool does and distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk, which serve different purposes. The modes (trending_scan, event, topic) further clarify its scope.

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

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

The description explicitly states when to use each mode: no args for trending_scan, 'event' for a specific market, 'topic' for cross-event scanning. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This is exemplary usage guidance with clear when-to-use and 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?

Even though annotations already mark the tool as read-only/idempotent, the description adds rich behavioral detail beyond those hints: model families, response segments, diagnostics, the 24h-move warning, Fed candidates caveat, placeholder-slug filters, and KV-level caching. This far exceeds what annotations alone convey.

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

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

The description is a dense, run-on block of text with ALL-CAPS pseudo-sections and minimal whitespace. It is not concise or well-structured, making it difficult for an agent to parse. It front-loads the purpose but then dumps excessive detail in one paragraph.

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 complexity and the lack of an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates/fed_note, _diagnostics), the meaning of returned metrics (edge_pp_net, kelly_fraction), and caching behavior. It leaves little ambiguity about what the tool returns and how it behaves.

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 all nine parameters already have detailed descriptions. The tool description mentions a few knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) but does not add meaning beyond the schema. It is a baseline 3 because the schema carries the burden.

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

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

The description opens with a specific action and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states its intent ('what should I bet on today'). However, it does not explicitly contrast itself with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it stops short of a 5.

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

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

It provides a clear context for use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives tuning guidance via 'TRADEABLE-EDGE KNOBS.' Yet there are no explicit when-not-to-use or alternative-tool recommendations, so it misses the top tier.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds significant behavioral context: snapshots are written on cache-miss, gaps mean no scan, TTL is 60 days, decay is computed from daily closes of edge_pp_net (not intraday), and the trade direction sign convention. This goes well beyond what annotations provide.

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

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

The description is long but highly structured with explicit 'Args', 'RESPONSE', and 'LIMITS' sections. Every sentence contributes useful information—return format, data nuances, and limitations—so it is efficient despite its length.

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

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

Given there is no output schema, the description thoroughly documents the response structure (tracked[], expired[], snapshot_dates[]), explains edge cases (snapshot gaps, TTL limits, day-closes vs intraday), and mentions the competition clock (median lifespan). This is complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters (days and window) with detailed descriptions including defaults and clamps. The tool description repeats some of this (defaults) but adds negligible new semantic meaning beyond what the schema already provides, so the 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 uses specific verbs and resources: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series persistence rather than just current edges.

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

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

The description provides clear context for when to use this tool: it answers a specific question about edge persistence and decay, and contrasts fresh vs. stale edges to illustrate relevance. However, it does not explicitly name alternatives or state when NOT to use it, which prevents a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower. The description adds substantial behavioral context: it 'walks the ladder', returns verdicts (clean|degraded|cannot_fill), interprets size_usd differently in single-market vs basket modes, and warns that partial basket fills convert an arb into an unhedged directional position. This goes well beyond the annotation hints.

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

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

The description is long but well-structured with clear sections: definition, REQUIRES, SINGLE-MARKET, BASKET, and USE THIS. Each section earns its place given the tool's two-mode complexity and lack of output schema, though the dense list of return fields prevents it from being truly concise.

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

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

This tool is complex (two modes, no output schema, 4 parameters), and the description covers inputs, return fields, verdicts, failure modes, a usage threshold, and risk rationale. The agent gets enough information to know when to invoke, what to pass, and what to expect in return, including edge-case warnings.

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%: each of the four parameters already has a detailed description, including side enum values, market/event distinction, and size_usd default/clamp. The tool description largely restates these same semantics rather than adding new syntax, formatting, or edge-case details, 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 first sentence defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', which is a specific verb+resource. It clearly differentiates from siblings by explicitly positioning it as the pre-trade check for polymarket_arbitrage and polymarket_edges, and by describing two distinct operating modes.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming sibling tools and giving a concrete threshold. It also explains the REQUIRES condition (market or event) and the behavioral rationale for why partial basket fills are dangerous.

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 detailing response contents (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and specific edge cases. This provides comprehensive behavioral context, especially since there is no output schema. Annotations already indicate read-only/idempotent, and the description adds significant value without contradiction.

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

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

While the description is long, every sentence serves a purpose. It is front-loaded with the core purpose, then systematically covers modes, response fields, safety warnings, and caveats. The structure uses labels and transitions (e.g., 'TWO MODES:', 'RESPONSE:', 'SAFETY FIELDS:') to make dense information scannable. No fluff is present.

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

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

Given the tool has no output schema and only a single optional parameter set, the description thoroughly covers all necessary context: modes, return fields, compatibility checks, temporal alignment, and skipped comparison counters. It even warns about the reliability of pre-mapped topics. This is complete for an agent to select and interpret results correctly.

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

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

The input schema already covers all three parameters with 100% description coverage, so the baseline is 3. The tool description adds meaningful context by explaining the two modes (topic vs explicit overrides), clarifying that explicit tickers 'Override the topic-mapped side,' and elaborating on what parameters like topic enable. This adds semantic value beyond the schema.

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

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

The description clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from siblings by specifying the exact cross-venue scope (Kalshi vs Polymarket) and explains its two modes (topic shortcuts and explicit tickers), making it unique among the 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 on when to use the tool ('for the same resolving question') and describes both modes. It also includes important usage cautions, such as when spreads are meaningless (compatibility_warning, temporal_alignment:false) and that 'pre-mapped ≠ tradeable.' However, it does not explicitly mention alternatives or when to prefer another tool (e.g., polymarket_arbitrage), so it lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, and idempotent, so the description adds only that results include rows and geometry and that SQL-like filters are supported. It does not discuss authentication, rate limits, or error behavior, which would be useful 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 four short, purposeful sentences. It front-loads the core purpose, efficiently summarizes the parameter set, states the return type, and offers a practical usage tip without any fluff.

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

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

With 6 parameters and no output schema, the description provides purpose, source context, and a return-type hint ('rows (and geometry)'). It lacks a more precise statement of the result format, but the annotations cover safety, making the description adequate for selection and invocation.

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

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

The schema provides 100% coverage with detailed parameter descriptions, so the baseline is 3. The description's listing of parameters is redundant, and the only added value is the sampling tip for where/out_fields; it does not provide deeper semantics beyond the schema.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, identifying a specific verb and resource. It distinguishes from sibling tools like layer_info (metadata) and search_datasets (discovery) by focusing on fetching attribute rows.

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 advises that the URL comes from search_datasets, implying a preceding discovery step, and gives a concrete sampling pattern (where='1=1' + out_fields='*'). However, it does not explicitly mention when to avoid this tool (e.g., for spatial queries) or name alternatives, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, informing the agent this is a safe read operation. The description adds valuable context beyond annotations: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID), and the dual retrieve/list behavior. No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the primary action ('Retrieve a value previously saved via remember, or list all saved keys'). Each sentence delivers distinct information: behavior, use cases, and scoping/companion tools. 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 two-mode tool with full annotations and 100% schema coverage, the description covers the necessary context: use cases, scoping, and relationships to remember/forget. The only minor gap is not explicitly describing the return format, but that is acceptable given the absence of an output schema and the simplicity of the tool.

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

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

The schema already covers 100% of the single 'key' parameter with the description 'Memory key to retrieve (omit to list all keys)'. The tool description re-states this and provides examples of typical values, but adds no additional parameter-specific semantics beyond what the schema provides. 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 'Retrieve a value previously saved via remember, or list all saved keys' with concrete examples of stored context like 'the user's target ticker, an address, prior research notes'. It names companion tools remember and forget, distinguishing this tool from 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?

The description explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch', giving clear when-to-use guidance. It mentions pairing with remember and forget but does not explicitly exclude alternatives or compare with sibling tools, so a 4 is appropriate.

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

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

Annotations already indicate read-only/idempotent hints, and the description adds valuable context about persisted feed, mark_read behavior, and the raw event payload. The mark_read option is a potential side effect, but it is clearly disclosed, so 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 compact but information-dense. It front-loads the purpose and uses the remaining sentences to cover return fields, filtering, mark_read, polling semantics, and an alternative access method without waste.

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

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

No output schema exists, so the description carries the burden of explaining return values—which it does (source, citation_uri, raw payload). It also covers polling behavior and the alternative endpoint. Minor omission: unread_only is not mentioned, but the schema covers it. Overall, sufficiently complete for a read tool.

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

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

Input schema has 100% coverage with descriptions for all 5 parameters. The description enriches semantics by providing examples (e.g., 'sec_8k'), explaining mark_read behavior, and clarifying the return payload, going beyond 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?

Description clearly states the tool pulls fired events from the subscription feed, with a specific verb and resource. It distinguishes itself from siblings like list_subscriptions or recent_changes by explicitly mentioning the feed, evaluator-written alerts, and return fields.

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

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

Provides context on when to use the tool (polling, checking recent alerts) and offers an alternative for scripts/dashboards via a direct HTTP endpoint. It does not explicitly exclude sibling tools, but the intended use case is clear.

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

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

Annotations already mark this as readOnly and idempotent, but the description goes beyond by disclosing the parallel fan-out to three external APIs, the fallback mechanism (GDELT preferred, GNews when rate-limited/5xx), the soft-fail for USPTO, and the exact return shape (changes[], total_changes, citation URIs). This level of detail is highly useful for an agent predicting side effects and 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 dense but not bloated; it uses compact phrasing and parentheticals to pack detail into one paragraph. The opening example-phrase list is a bit unusual, but it quickly conveys intent. The final sentence provides an explicit alternative, which is valuable. Slight structural improvement could be to lead with the core action, but it remains effective.

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

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

With no output schema, the description fully specifies the return format and groups, including citation URIs. It covers all input constraints, edge cases (fallbacks, API sunset), and provides a clear distinction from a sibling tool. This is a complete and self-sufficient description for a complex tool.

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

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

Although the schema covers 100% of parameters, the description adds valuable semantic nuances: it shows accepted formats for `since` (ISO date or relative shorthand), gives examples like '7d' and '3m', recommends '30d' or '1m' for typical monitoring, and clarifies that `value` can be a ticker or CIK. This enriches the schema's basic descriptions.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with examples like "What's new with X" and "latest on Y". It distinguishes itself from the sibling entity_profile by noting that this tool returns changes rather than 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?

The description explicitly states when to use this tool (for recent changes in a window) and when to use an alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also details the internal data-source fallbacks (GDELT→GNews) and the USPTO sunset caveat, giving the agent concrete decision-making 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?

The description discloses key behavioral traits beyond annotations: key-value scope by identifier, persistence differences for authenticated vs. anonymous users, and integration with recall/forget. These details are not present in the annotations and meaningfully inform usage.

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

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

The description is three sentences, front-loaded with action, and every sentence earns its place. It avoids fluff and is appropriately sized for the tool's simplicity.

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

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

Given the tool's simplicity and the absence of an output schema, the description covers all essential aspects: what it stores, when to use it, persistence behavior, and related tools. No critical information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds examples of key types and value usage ('a resolved ticker, a target address'), enriching the schema's generic descriptions. This marginal extra value justifies a 4.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It specifies the resource (key-value data) and distinguishes from siblings by referencing 'recall' and 'forget.' This makes the purpose unambiguous and distinct.

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 clear usage context ('Use when you discover something worth carrying forward') and mentions alternatives/companions ('Pair with recall to retrieve later, forget to delete'). However, it does not explicitly state when NOT to use the tool, holding it back from a 5.

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

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

Annotations already establish read-only/idempotent/destructive safety. The description adds valuable behavioral context: it names the exact output fields (ticker, CIK, RxCUI, ingredient, brand), explains that it cascades through multiple endpoints internally, and notes auto-disambiguation. This goes beyond what annotations provide.

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

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

The description is dense but well-organized, using clear labels (SUPPORTED TYPES, company, drug) and concrete examples. No wasted words; it delivers high information in a structured format.

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

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

Despite having no output schema, the description fully explains what the tool returns, including citation URIs, and frames its role in the tool ecosystem. For a two-parameter read-only tool, this is effectively 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 already covers both parameters with 100% coverage, explaining accepted formats per type. The description reinforces this with the supported types section and adds the auto-disambiguation nuance, justifying a slight boost 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 concrete example queries and states the core function: resolving a user-spoken name to the canonical identifier other tools require. It distinguishes itself from sibling tools (entity_profile, compare_entities) by focusing on converting names to IDs, not analysis or comparison.

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

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

Provides an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' This clearly defines when to use it. However, it does not mention any exclusions or alternative tools, so it falls short of a full 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context: it probes each entity using ai_visibility_check, ranks results, and surfaces strongest/weakest recognition. It also clarifies the return structure (score, confidence, signal density), which goes beyond the annotations.

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

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

The description is front-loaded with the core action ('Compare AI visibility'), followed by method, use case, and return format. Each sentence earns its place, but the final sentence is slightly redundant with the first. Overall, it is concise and well-structured.

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

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

Given the tool's complexity (multiple entities, optional models/API key) and the absence of an output schema, the description adequately explains what the tool returns (ranked list with score, confidence, signal density). It does not dive into models or _apiKey behavior, but those are covered by the schema. The description is sufficient for an agent to understand the tool's scope and result.

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

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

The input schema covers all four parameters with full descriptions (100% coverage), including the note that the first entity is the subject. The description adds no additional parameter-level detail beyond what the schema already provides. Thus, the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the method (probes each entity with ai_visibility_check), the output (ranked list), and the use case (competitive AI-marketing audits). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description explicitly frames when to use the tool: 'Useful for competitive AI-marketing audits' with an example query. It also names the underlying tool (ai_visibility_check), implying this is the multi-entity alternative. However, it does not explicitly state when NOT to use it or offer alternative tools for non-competitor 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 discloses behavioral traits beyond annotations, such as potential 5-30s delay for bundlephobia's first measurement and graceful degradation with sources_failed. While annotations already declare readOnly/idempotent, the description adds valuable context about timeout and partial failure behavior, contradicting nothing.

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, well-structured paragraph that front-loads the core purpose, then covers usage, return data, and limitations. Each sentence adds information, though it is somewhat long; however, the detail is necessary for a composite tool with multiple data sources and failure modes.

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 explains what the tool returns (summary block with specific fields, per-advisory detail, links, alternative versions), how failures are handled, and the ecosystem constraint. With no output schema, the description carries the burden of return-value explanation, and it does so thoroughly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add additional parameter-specific semantics beyond what the schema already provides, but it does contextualize the parameters within the tool's purpose. 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 explicitly states this is a composite 'should I add this npm package to my project' check, aggregating data from deps.dev and bundlephobia. It clearly distinguishes the tool's scope (npm packages) and its multi-source fan-out behavior, making it distinct 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?

Direct guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also explicitly notes the NPM-only limitation and points to deps.dev:version directly for other ecosystems, providing a clear alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description adds value by specifying the exact return fields (name, summary, record_count, owner/org, url) and the 'open geospatial datasets' scope. 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 main purpose, and includes a concise workflow hint. Every sentence earns its place with no redundancy.

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

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

With no output schema, the description helpfully lists the returned fields and gives examples of content areas. It covers the essential aspects for a simple optional-parameter search tool, though it does not mention what happens with an empty query or result pagination.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces that query is a keyword search and ties the returned url to a workflow, but adds no substantial parameter-specific details beyond the schema.

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

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

The description clearly states the verb 'Search' with a specific resource ('City of Detroit GIS open geospatial datasets') and scope (by keyword, with examples). It also distinguishes from sibling tools by noting the returned Feature Service url is used with query_layer / layer_info.

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

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

The description provides clear context for when to use the tool (searching for datasets by keyword) and explicitly names the downstream tools (query_layer / layer_info) for the returned URLs. It does not explicitly exclude alternatives like search_within, so it misses a full when-not clause.

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 substantial behavioral context beyond the readOnlyHint/idempotentHint annotations: it discloses the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and the 200K character cap with truncation flagging. This gives the agent important expectations about behavior and limitations.

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

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

The description is information-dense and well-structured: first sentence defines the core action and outputs, second provides the primary use case, third gives complementary tooling and technical details. Every sentence serves a purpose, with no filler or redundancy.

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

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

Despite having no output schema, the description explains the return format (passages with offsets and similarity scores), the input expectations, and the limitations (truncation). This makes the tool's behavior clear for an agent, especially given the large sibling list, and confidently distinguishes search_within from related tools.

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

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

Schema description coverage is 100%, so the description does not add much beyond what the schema already provides. It gives context like 'the text you already pulled' and query examples, but these are similar to the schema's own descriptions. The description does not introduce new parameter meanings or relationships.

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 'Semantic search INSIDE a fetched record' with specific outputs (top-N passages, character offsets, similarity scores). It distinguishes from sibling tools by emphasizing search within an already-fetched text, rather than global search or grounded Q&A.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, providing clear guidance on when to use and an alternative. However, it does not explicitly state when NOT to use (e.g., when the record fits in context), so not a perfect 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?

Adds rich behavioral context beyond annotations: requires OAuth account, phone verification, 10/day SMS cap, webhook signing secret returned once, auto-disable after 10 failures. 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?

Dense but well-organized: front-loaded purpose, then types with examples, then delivery channels. Every sentence adds value, no fluff. Appropriate length for the complexity.

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

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

Comprehensive for a subscription-creation tool: covers prerequisites, supported types with param examples, delivery options with limitations, return value (subscription id), and consumption path. No output schema exists, but description fills the gap.

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

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

Despite 100% schema coverage, the description adds significant meaning: detailed examples for each subscription type, clarification of delivery channel constraints (e.g., phone must match verified, webhook HTTPS-only), and explanation of the webhook signing secret and failure policy.

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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and lists supported types. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides clear context on prerequisites (OAuth account) and references recent_alerts for consuming the feed, but does not explicitly exclude alternatives like list_subscriptions or unsubscribe. Strong guidance but lacks direct when-not-to-use statements.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond this: the tool returns category-bucketed example questions drawn from the live catalog, and that it can be called with or without a topic to adjust the scope. No contradictions with annotations.

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

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

The description is longer than typical but is structured and front-loaded with example queries to quickly orient the agent. Each sentence adds value: purpose, output format, categories, invocation modes, and usage timing. While it could be trimmed slightly, it remains efficient for a complex onboarding 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?

There is no output schema, so the description carries the burden of explaining return values—it does, saying it returns category-bucketed example questions with 'the exact tool + argument shape'. It also covers how to invoke it (with/without topic) and when to use it first. For a read-only, non-destructive tool, this is complete enough for an agent to decide and call it correctly.

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

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

The schema already has 100% coverage with a description for the single `topic` parameter, listing allowed values. The description adds meaning by providing example values ('finance', 'pharma', 'betting') and clarifying that omitting the parameter returns a cross-category spread, which enriches the schema's basic documentation.

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 as 'the onboarding entry point' that 'Returns category-bucketed example questions' with specific categories. It distinguishes itself from siblings by positioning itself as the first stop for learning about the meta-tools like ask_pipeworx, entity_profile, and compare_entities, and even specifies 'Use this FIRST'.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also describes the two invocation modes: call with no arguments for the full spread, or pass a `topic` to focus. This directly helps the agent choose when to use this tool vs alternatives.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds critical behavioral context: ownership is enforced, and the row is soft-deleted (deactivated) so history remains accessible. This meaningfully extends what annotations alone 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?

Two concise sentences front-load the core action, then add ownership and behavioral details. Every clause provides value with no repetition or fluff.

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

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

For a one-parameter, no-output-schema tool with strong annotations, the description fully explains purpose, constraints, and post-conditions. The only minor gap is no explicit mention of failure behavior, but this is not necessary for such a simple 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%: the single parameter 'id' is clearly described as the 'Subscription id (uuid) returned by subscribe'. The description does not add further parameter detail, but also does not need to given the schema's clarity.

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 'Cancel a subscription by id', a specific verb and resource that immediately distinguishes it from sibling tools like subscribe and list_subscriptions. The additional context about ownership and deactivation further clarifies the exact 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?

The description provides clear context on when to use this tool: to cancel a subscription that the user owns. It also explains the result (deactivation rather than deletion) and points to recent_alerts for historical events, giving the user a sense of what happens next.

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/openWorld/idempotent hints, the description reveals the two-step execution logic, the exact percent-delta math for financial claims, and the concrete verdict set (confirmed / approximately_correct / refuted / inconclusive / unsupported). It also explains citations via pipeworx:// and the 'replaces 4–6 sequential calls' benefit. This is rich behavioral context far 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?

Although the description is long, it is information-dense with zero filler. It front-loads trigger phrases and purpose, then explains routing, return values, and efficiency gains in a logical flow. Every sentence earns its place.

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

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

The tool has two parameters, no output schema, and nontrivial routing logic. The description covers inputs, processing paths, outputs, and edge-case behavior (tolerance cap at 5). It is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Both parameters are fully documented in the schema, and the description adds semantic depth: it explains how tolerance_pct interacts with verdict classification ('Max percent deviation still graded approximately_correct') and how it overrides the claim's implied tolerance. This adds meaning beyond the schema's field descriptions.

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

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

The description opens with concrete trigger phrases ('Is it true that…', 'fact check') and a clear verb-phrase: 'natural-language claim verification against authoritative sources'. It explicitly differentiates from sibling tools like deep_research or ask_pipeworx by focusing on verifying a user's claim rather than general research or Q&A.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It further provides detailed routing rules: company-financial claims go through the SEC EDGAR/XBRL fast path, while any other factual claim falls through to a grounded pipeline. This is explicit when-to-use guidance with no ambiguity.

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