Arcgis Houston

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

Annotations already declare read-only and idempotent behavior, and the description adds valuable context: default free model, external API key pass-through with direct billing, and the return structure of per-model results. It clarifies that Anthropic calls are user-billed, which is critical side-effect information beyond the schema.

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 efficient: core purpose first, then model options/cost, output shape, and use cases. Every sentence carries distinct information with no redundancy or fluff.

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

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

Given 100% schema parameter coverage, full annotations, and no output schema, the description covers the essential contract: what it returns, which models are supported, the default behavior, and the external cost implication. No critical gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that omitting 'models' defaults to workers-ai and that supplying an _apiKey incurs direct Anthropic charges — details not fully captured in the schema and valuable for correct invocation.

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

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

The opening sentence uses a specific verb ('Probe') and clear resource (LLMs), defines the output (visibility score 0-100 per model), and distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on cross-model visibility scoring rather than Q&A or targeted competitor scans.

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

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

The description provides concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and practical instructions on model selection and API key handling. 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?

The annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds behavioral context about routing, filling arguments, returning stable citation URIs, and being a fast default that works on all tiers, enriching the usage profile without contradicting the annotations.

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

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

Though fairly long, the description is front-loaded with the most critical usage directive and each sentence adds strategic guidance—tool capabilities, triggers, examples, and escalation paths. No redundancy or 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?

The description covers purpose, usage, alternatives, parameter semantics, and output characteristics (structured answer with citation URIs), all necessary for an agent to decide and invoke correctly. Since there is no output schema, the description sufficiently fills that gap. It also addresses edge cases like breaking news and free account limitations.

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 explains the 'question' parameter and its aliases at 100% coverage. The description adds practical examples of accepted inputs ('current US unemployment rate', 'Apple's latest 10-K') and clarifies the natural-language format, which helps the agent formulate effective queries 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?

The description clearly states the tool routes questions to 5,462 tools across 1,419 verified sources and returns structured answers with citation URIs, with explicit examples. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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

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

The description gives an explicit preference directive ('PREFER OVER WEB SEARCH') and enumerates when to use it, including trigger phrases and example queries. It also names exact alternatives for specific scenarios (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions), setting clear boundaries.

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 annotations, the description discloses that this is an experimental edge with candidate routing improvements, that no candidate is active right now, and that it falls back to nothing (i.e., it is fully functional). This provides meaningful context about the tool's behavior and current state.

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 long and each sentence contributes critical information (relationship to ask_pipeworx, current active state, usage guidance, and fallback behavior). It is slightly longer than necessary but remains well-structured and front-loaded with the key 'Beta version' identifier.

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

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

The description covers the tool's purpose, relationship to the stable sibling, current experimental state, and response shape via reference to ask_pipeworx. No output schema is provided, but the 'same response shape' reference compensates. It does not elaborate on what 'routing' entails, but the sibling context and alias details make it sufficiently complete for an experienced agent.

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

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

The input schema provides 100% coverage with detailed descriptions for the `question` parameter and all aliases (q, text, input, query, prompt). The description adds no additional parameter meaning, so the baseline score of 3 for high schema coverage 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 'Beta version of ask_pipeworx' and an 'identical universal router' with the same 5,462 tools, arguments, and response shape. It clearly distinguishes it from the stable ask_pipeworx sibling by naming the beta status and the router role, making its purpose 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 usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that no candidate is currently active, implying it matches the stable version exactly. It also contrasts with the stable router by noting results are compared to decide merges, and states it is not a fallback but a full working router.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description goes further by disclosing refusal reasons, the evidence verbatim quote, confidence, source, fetched_at, and the fact that it makes an extra LLM call. This is far beyond what annotations provide and fully sets expectations.

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

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

The description is dense with information but well-structured: the core value proposition is front-loaded, then the return contract, then usage guidance. Every sentence contributes essential operational detail 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?

Despite having no output schema, the description explicitly lists the success and refusal response shapes, including all possible refusal_reason values. Combined with clear usage context, cost implications, and behavioral expectations, the tool is fully specified.

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

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

Schema coverage is 100% as all parameters are aliases for 'question' and are described in the schema. The description only references 'question' generically and does not add parameter-level detail, so the schema already carries the semantics. A 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' which is a specific verb (answer) plus a resource (grounded tool output). It explicitly differentiates from ask_pipeworx by describing the extraction-only behavior and the evidence return, so the purpose is 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?

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts with ask_pipeworx for casual lookups. It also mentions the cost tradeoff (one extra LLM call), which helps agents decide between 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 readOnlyHint/idempotentHint annotations, the description discloses behavioral details like parallel fan-out, low-confidence short-circuiting, blocked statuses for closed markets, illiquid spread warnings, and the resolution-rule risk with flat-50¢ settlements. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Each section provides necessary operational detail absent an output schema, and the description is front-loaded with the core purpose and usage.

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

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

There is no output schema, so the description must carry the full burden of return-value semantics. It defines result.market fields, result.analysis fields, evidence keys, resolver contract fields, parent_event object, news fallback flags, status strings, and cancellation-rule parsing—covering all essential contexts for safe and effective 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?

With 100% schema coverage, the schema already defines all parameters. The description adds meaningful context for 'market' (slug/URL/question variants) and include_raw (summary vs 50KB-500KB payloads), but does not elaborate on the 'depth' parameter beyond the schema, so it is above baseline but not maximal.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on research and evidence gathering rather than arbitrage or edge scanning.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers blocking paths and when to inspect resolver fields, but it does not explicitly name alternative sibling tools or state when not to use this tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, non-destructive operation, and the description adds rich behavioral context: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, metric-based sorting, and citation URI returns. No contradiction with annotations exists.

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 clause serves a purpose: trigger examples, use-case priority, type-specific data details, sorting behavior, and return format. It is front-loaded with the most critical usage cues, though slightly dense; trimming repetitive examples could improve efficiency without losing value.

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

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

With no output schema present, the description sufficiently explains what the tool returns (paired data + citation URIs) and covers all key behavioral aspects: scope, data sources, sorting, and efficiency gains. Given the 2-parameter simplicity and robust annotation support, the description is 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?

Schema coverage is 100% for the two parameters, and the description enriches both: it explains 'company' pulls financial data and 'drug' pulls adverse-event/trial data, and specifies value formats (tickers/CIKs for company, names for drug). This goes beyond the schema's basic descriptions and ensures correct invocation.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, using clear verbs like 'compare' and providing trigger phrases. It distinguishes itself from single-entity lookups by emphasizing it replaces 8–15 sequential queries, making its purpose and 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 provides explicit when-to-use guidance with concrete user phrasings (e.g., 'X vs Y', 'which is bigger', 'rank these companies') and instructs to always prefer this tool over sequential single-pack lookups when comparing entities. It also clarifies the two type-specific data sources, aiding correct selection.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description adds critical operational context: account/paid-plan requirements, NOT open-web search, decomposition into facets, parallel execution, 'explicit gaps[] for facets the data couldn't answer (never invented)', contradiction scanning for standard/thorough, citation_uri fetchability, semantic excerpting behavior, and latency expectations. This substantially exceeds what annotations provide and contains no contradictions.

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

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

The description is front-loaded with the most critical information (account requirement and core purpose) and each sentence adds value. However, it is long and has some redundancy (gaps[], contradictions[], citation details appear multiple times), preventing a perfect score for conciseness.

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

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

Given the tool's complexity and the absence of an output schema, the description fully explains the return packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), depth behavior, latency, and boundary conditions (structured catalog vs. open-web news). It also accounts for edge cases like fetchable citations and semantic excerpting, making the description complete for reliable 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 already covers 100% of parameters, including a detailed explanation of the depth enum values and the natural-language nature of the question parameter. The description adds only marginal context (e.g., thorough requires a paid plan, broad/multi-part questions are acceptable), which does not materially enhance schema-based understanding. The baseline of 3 for full schema coverage 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 function: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in ONE call, with specific verbs and scope. It also explicitly distinguishes itself from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx, so the agent can immediately differentiate it from alternative 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 explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For a single lookup use ask_pipeworx' and for current-news topics 'prefer ask_pipeworx.' It also covers account-tier constraints and suggests an alternative if not signed in.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that by disclosing the return format ('top-N most relevant tools with names, descriptions, and full input schemas') and the promise that results are 'ready to call directly, no second schema lookup needed.' This is credible and goes beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and is wrapped in two sentences. The long list of domains is somewhat verbose but earns its place by indicating the tool's breadth. No redundancy with the schema; all sentences contribute 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?

For a tool-discovery tool with no output schema, the description fully covers the return contract (tools with names, descriptions, full schemas, curated examples) and instructs the agent to use it as a first step in multi-tool environments. It explains the key guarantee ('ready to call directly') which is essential for agent decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the primary input is a natural-language query ('describing the data or task') and mentions 'top-N' but does not elaborate on the 'limit' parameter beyond what the schema already specifies. The description adds marginal semantic value over the schema.

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

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

The description uses a specific verb+resource construction ('Find tools by describing the data or task') immediately clarifying this is a tool-discovery utility. It also enumerates a broad domain list (SEC filings, FDA drugs, FRED, etc.), distinguishing it from sibling tools like search_datasets which operate on data rather than the tools themselves.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and implies contrast with tools that return direct answers, covering both usage and exclusion guidance.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, but the description adds substantial behavioral context: it fans out across multiple named sources, returns specific fields, soft-fails for patents after API sunset, and uses a GDELT→GNews fallback. This far exceeds the structured annotations and prepares the agent for failure modes.

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

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

Despite being long, every sentence earns its place: it first lists user intents, then the core action, then the preferential use case, then the detailed output components, and finally the parameter constraint. There is no filler or redundancy beyond the slight repetition of the parameter rule, which itself is concise and useful.

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

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

This is a complex multi-source tool with no output schema, but the description compensates by enumerating exactly what is returned (cik, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers edge cases like patent API sunset and name-based requests, making the tool fully usable without additional investigation.

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

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

The input schema already provides 100% description coverage for both parameters, including the exact instruction that value accepts a ticker or zero-padded CIK and that names are unsupported. The description repeats this same information in its final sentence, adding no new meaning beyond what the schema already documents.

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

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

The description opens with concrete user intents and explicitly states 'full cross-source profile of a US public company in ONE parallel call', making the tool's purpose unmistakable. It distinguishes itself from siblings like compare_entities and resolve_entity by focusing on a holistic single-entity view.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the alternative for name-only inputs: 'use resolve_entity first if you only have a name', which effectively excludes inappropriate uses.

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 and idempotentHint; description adds context about clearing sensitive data but doesn't disclose behavior for missing keys or side effects beyond what annotations imply.

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

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

Two sentences with no waste; the first states the core action, the second provides usage guidance.

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

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

Simple tool with one param, clear annotations, and description covers purpose and use cases; no output schema 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?

Schema coverage is 100% with clear description ('Memory key to delete'); tool description adds no additional parameter meaning beyond that baseline.

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

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

Description uses a specific verb 'Delete' and resource 'previously stored memory by key,' clearly distinguishing from sibling tools like remember and recall.

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 ('context is stale, task is done, or clear sensitive data') and pairs with remember and recall, though it doesn't explicitly exclude 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, so the description adds value by disclosing the internal process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also clarifies the output form ('single text blob'), though it omits failure modes or edge cases.

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

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

The description is tightly written: a single opening sentence, a brief process sentence, and a succinct 'Useful for' list. Every sentence contributes meaning, and the structure front-loads the core action.

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 two-parameter, no-output-schema tool, the description covers purpose, process, output format, and typical use cases. It lacks details on error behavior or site accessibility, but given the simplicity and strong annotations, this is adequate and close to complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema, only indirectly referencing 'key links' and output format. It does not elaborate on 'max_links' beyond what the schema already says.

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 ('Generate') and resource ('llms.txt file for any URL'), clearly stating what the tool does. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than analysis, and its 'Useful for' list reinforces its distinct purpose.

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

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

The description provides clear usage context with a 'Useful for' list (client indexing, own project drafting, competitor auditing), which covers when to use it. It does not explicitly mention exclusions or alternatives, but the tool's unique niche among siblings makes the guidance largely sufficient.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is retrieved (fields, geometry, record count, capabilities) and that it operates 'by url', but it does not go beyond that. 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 a single sentence that front-loads the verb and resource, and each word adds value. No filler or redundant information.

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

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

For a simple tool with one parameter and no output schema, the description adequately lists all return components (fields, geometry type, record count, capabilities). It is missing potential caveats like URL format validation or error behavior, but these are not critical for the core use case.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the url parameter is for the layer endpoint and clarifies the output that depends on it, but does not add extra syntax or format details beyond the existing parameter description.

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

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

The description uses a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and lists exact outputs: fields (name + type), geometry type, total record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer or search_within.

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

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

The description implies usage for schema inspection ('Get an ArcGIS layer's schema'), but it does not explicitly mention when to use this tool versus alternatives (e.g., query_layer). No exclusions or when-not-to-use guidance are given, so it remains at an implied level.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context that it scopes to the caller's subscriptions and returns specific fields, which are not conveyed by annotations.

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

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

Two concise sentences: the first states what the tool does and returns, the second provides practical usage guidance. Every word earns its place with no redundancy.

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

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

For a simple read-only list tool with a single optional parameter, the description covers purpose, return fields, and usage scenarios. Annotations and schema fill in the remaining details, making the tool fully understood.

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

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

Schema coverage is 100% for the single parameter 'include_inactive', so the description does not need to explain it further. The description adds no additional parameter meaning, but the schema already provides sufficient detail.

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

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

The description clearly states the action ('List') and specific resource ('the caller's active subscriptions'), and enumerates the returned fields. It is unambiguous and distinct from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit use cases ('review what you're monitoring before adding more' and 'find an id to cancel'), giving clear context for when to use the tool. However, it does not explicitly name alternatives or exclusionary conditions.

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 behaviors beyond annotations: rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and the claim_token flow for status checks. It also notes that the team reads digests daily and signal affects roadmap. No contradiction with the provided annotations.

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

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

The description is long but every sentence earns its place, covering purpose, usage boundaries, content guidance, token mechanics, and rate limits. It is logically organized and front-loaded with the core purpose. No fluff or repetition.

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

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

For a feedback tool with no output schema, the description covers all necessary context: what to report, what not to report, how to follow up, rate limits, and roadmap impact. The claim_token workflow is fully explained, making the tool self-contained for an agent.

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

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

Schema coverage is 100%, but the description adds significant meaning to parameters: it explains how to use claim_token (pass it back with no other arguments), what message should contain (specific, 1-2 sentences, max 2000 chars), and that context should reference Pipeworx tools/packs. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about broken, missing, or desired functionality. It distinguishes itself from siblings by specifying it is only for tools served by this Pipeworx connection, not other MCP servers. The use cases (bug, feature, data_gap, praise) are explicitly listed.

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 (bug, feature, praise) and when-not-to-use (tools from other MCP servers), including an alternative action (file with that server). It also explains how to frame feedback (in terms of Pipeworx tools/packs, not end-user prompts) and how to follow up with a claim_token.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h depending on window'), which are not evident from annotations.

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

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

The description is well-structured with a one-sentence summary followed by a concise use-case list and a technical note. It is front-loaded with the core purpose and every sentence adds value without redundancy.

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

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

For a simple one-parameter tool with no output schema, the description provides enough detail: what is returned, the data shape ((pack, tool, count)), the caching behavior, and the intended use cases. It fully covers the tool's operation and limitations.

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 covers the 'window' parameter with an enum and description. The description further explains that shorter windows surface 'what's hot right now' while longer windows show 'steady-state demand', adding semantic nuance beyond the basic 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 returns top tools, top packs, and total call volume over a recent window, using specific verbs and resources. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on aggregated trending usage signals.

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 three explicit use cases (discovering hot data sources, confirming canonical choices, checking alignment with agent needs), giving clear context for when to use it. It stops short of naming alternatives or stating when not to use it, so it doesn't quite reach 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 the tool read-only, idempotent, and non-destructive, and the description adds substantial context: partition filters, semantic similarity thresholds, placeholder filtering, and the fill check warning not to trade when realizable edge ≤ 0. 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 dense but well-structured, with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded core purpose and mode selection. Every sentence contributes value, and the length 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?

With no output schema, the description compensates by thoroughly explaining the response structure (opportunities[] and partition_check fields), covering request modes, filters, thresholds, and the fill check. It even points to a related tool for custom sizing, making it 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 input schema already has 100% description coverage for event and topic, but the tool description goes further by providing concrete slug examples and explaining how each parameter changes the scan behavior. This adds significant meaning beyond the schema.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with a clear verb and resource. It further distinguishes three modes (no-arg trending_scan, event, topic), setting it apart from sibling tools like polymarket_edges.

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

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

It provides explicit when-to-use guidance for each mode, including no-args for a trending scan, event for a specific market, and topic for cross-event scanning. It also gives a clear alternative by directing users to polymarket_fill_risk for custom sizing, making both when and when-not-to-use explicit.

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

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

The description goes far beyond the annotations, detailing response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, etc.), the 24h-move warning, gate thresholds, and even caching behavior ('Cached 1h at the KV level keyed on all knobs'). This gives an agent a thorough understanding of what the tool does and what to expect.

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 one long, dense block of text with extensive details (per-sport α values, gate thresholds, funnel counters). While the information is valuable, it is not concise and is difficult to parse quickly. The lack of paragraphs or bullet points makes it overwhelming; a more structured layout would be far more 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?

Since there is no output schema, the description carries the full burden of explaining return values. It thoroughly covers the response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields, and explains how parameters affect the output. The detail is sufficient for an agent to understand what the tool returns and how to use it.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaningful parameter semantics by explaining how knobs interact (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and clarifying exceptions (e.g., 'min_kelly never filters partition arbs; min_partition_leg_kelly applies per-leg instead'). This extra context raises the score.

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 pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('Built for "what should I bet on today"'), making the tool's purpose unmistakable and distinguishing it from generic market data tools. The scope is clear without needing to reference 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 provides clear use context: 'agents discover opportunities without paging hundreds of markets' and explains what the tool is for. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already mark it as read-only and idempotent, and the description adds substantial detail: snapshot source, TTL limits, data gaps when snapshots aren't written, computation basis (daily closes, not intraday), and the signed/directional meaning of edge_pp_net. 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 well-organized into purpose, arguments, response format, and limitations. Despite its length, every sentence provides unique value, especially the detailed breakdown of the response fields. It is front-loaded with the core question it answers, making it efficient.

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

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

For a tool with no output schema, this description fully documents the response structure (tracked[], expired[], snapshot_dates[]), including the meaning of fields and edge cases like snapshot gaps and TTL limits. No significant gaps remain, making it complete for an agent to invoke 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 schema covers both parameters 100%, so the baseline is 3. The description adds defaults and clarifies days is lookback and window is snapshot family, but these details already exist in the schema. No additional semantics or interaction details are provided beyond the schema's own descriptions.

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

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

The description clearly states the tool's role: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

It provides clear context for when to use the tool (when you need edge persistence/decay history) and explains why fresh vs old edges matter in decision-making. However, it does not explicitly name alternative tools for other cases, such as 'use polymarket_edges for current edges,' 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/idempotent/non-destructive, and the description adds materially by explaining that it 'walks the ladder', returns a clean/degraded/cannot_fill verdict, and is a pre-trade simulation rather than an execution. No contradiction exists between annotations and description, and the description gives meaningful context about live order-book depth and basket-fill pitfalls.

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

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

The description is long and dense, but it is front-loaded with purpose and every clause adds mode-specific behavior, output fields, or usage caveats. It loses one point for being a single run-on paragraph that could benefit from short bullet-style separation, but it is not wasteful.

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, yet the description enumerates all returned values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, plus basket-specific fields like capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers defaults, constraints, and risk rationale, so an agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, and the description goes beyond it by explaining the mutually exclusive market/event modes, the meaning of side in each mode, and the different interpretation of size_usd (spend/proceeds for single-market vs settlement notional for basket). It also clarifies defaults and clamps, so parameter semantics are fully enriched.

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 statement ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and then distinguishes two modes (single-market vs basket), clearly separating this fill-risk checker from sibling polymarket tools. It states exactly what it returns (top_of_book, vwap_fill_price, slippage_pp, verdict) and even names the intended usage before acting on arbitrage/edge signals.

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 the agent when to use it: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It also gives mode-selection guidance (market vs event) and explains why (theoretical overround on thin books is not capturable; partial basket fills create unhedged directional risk).

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, which only state readOnly, openWorld, idempotent, non-destructive. It discloses behavior in detail: response format, compatibility_warning triggers, temporal alignment, skipped_cross_type/subtype counters, and the note that pre-mapped topics often return warnings. This gives the agent a full picture of what the tool does under various conditions without contradicting annotations.

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

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

The description is long but well-structured into sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds essential information about a complex matching tool. It is front-loaded with the core purpose and uses formatting to improve scannability. No filler or redundancy.

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

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

Given the tool's complexity (cross-venue matching, compatibility checks, temporal alignment) and the lack of an output schema, the description covers all necessary aspects: input modes, response structure, safety fields, and caveats. It fully explains return values and edge cases, making the tool's behavior predictable for an agent.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds semantic context beyond the schema: it explains the two modes, that explicit parameters override topic-mapped sides, and lists example values. This interaction logic is not evident from the schema alone, so the description adds meaningful value.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools by focusing on cross-venue spread and explicitly explains two modes (topic shortcuts and explicit pairings), making the tool's purpose unmistakable.

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

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

The description provides clear usage context: when to use topic shortcuts vs explicit tickers, and it warns about when the tool's output is not meaningful (compatibility_warning, temporal alignment). It does not explicitly name alternative tools, but the safety-field explanations serve as exclusions for when not to trust the spread. This is more than implied usage, but lacks direct 'use this instead of X' 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. The description adds useful behavioral context by stating that it returns attribute rows and geometry, and the sampling hint clarifies how to make safe exploratory queries. 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?

Two sentences, front-loaded with the core purpose and parameter list, followed by a practical usage tip. Every clause adds value; no filler or redundancy.

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

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

Given no output schema, the description still communicates the return shape (attribute rows and geometry), covers pagination via offset/limit, filtering via where, and field selection via out_fields. Combined with the rich schema examples, it provides enough context to invoke correctly.

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

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

The input schema covers all six parameters with descriptions and examples (100% coverage). The description reinforces the SQL-like semantics and the out_fields concept but adds little beyond the schema's own parameter explanations, so a baseline of 3 is appropriate.

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

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

The description clearly states it queries an ArcGIS Feature/Map Service layer by URL, with a specific list of SQL-like query parameters. This distinguishes it from sibling tools like layer_info (likely metadata) and search_within (searching data) by naming the exact resource and 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?

It explicitly references that the URL comes from search_datasets and gives a concrete sampling pattern ('where=1=1 + out_fields="*"'). This provides clear usage context, though it does not explicitly contrast with sibling tools like layer_info.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds the scoping detail ('Scoped to your identifier') and the dual-mode behavior based on optional key, which are useful beyond annotations. It doesn't mention return format or missing-key behavior, but that's minor given the simple read-only nature.

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

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

Two sentences, front-loaded with the action, no redundant words. Each sentence adds value: the first explains the operation, the second provides context and related tools.

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 optional-key read tool with strong annotations, the description covers purpose, scoping, and related tools. No output schema is needed because the return value is implied. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (the only param `key` is described as 'Memory key to retrieve (omit to list all keys)'). The description repeats this same info and adds no new parameter-level detail, so baseline 3 applies.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys' — a specific verb with a clear resource, and explicitly distinguishes the listing mode. It also names sibling tools remember and forget, making scope clear and distinguishing from alternatives.

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

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

Explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch', and pairs with remember to save and forget to delete, which guides when to use this vs alternatives. This is clear usage guidance with explicit sibling references.

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

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

The description discloses that setting mark_read:true will flag events as read, which is a state mutation, contradicting the readOnlyHint annotation. The annotation suggests the tool is read-only, but the description reveals an optional write side effect. This is a direct contradiction, so the score is 1 with annotation_contradiction flagged.

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 purpose. It includes useful details like polling and the HTTP endpoint without excessive verbosity. The structure flows logically from main function to return format to filtering to side-effect behavior.

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

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

With no output schema, the description adequately covers return values. It mentions the source of alerts (evaluator), the persisted feed, filtering options, mark_read side effects, and an alternative access point. Combined with annotations indicating read-only/idempotent behavior, it is reasonably complete, though it could clarify unread_only semantics more.

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

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

Although schema coverage is 100%, the description adds semantic value by explaining return fields (source, citation_uri, raw event payload), illustrating the type filter with an example ('sec_8k'), and clarifying mark_read behavior ('next call only shows newer ones'). This goes beyond the schema's bare descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with a specific verb ('Pull') and resource ('fired events from your subscription feed'). It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alert events with source, citation_uri, and payload details.

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

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

The description provides clear usage context: it mentions filtering by type and since, polling behavior, and an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It doesn't explicitly state when NOT to use this tool versus alternatives, but the context is sufficient for a basic understanding.

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

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

The description goes beyond the readOnly/openWorld/idempotent annotations by revealing the internal fan-out behavior: the GDELT→GNews fallback when rate-limited or 5xx, and the USPTO/PatentsView API sunset causing a soft-fail. It also describes the return structure (changes[], total_changes, pipeworx:// citation URIs), adding significant behavioral context.

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

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

The description is a dense single paragraph that packs in query triggers, source fallbacks, parameter syntax, return format, and an alternative tool. Every sentence earns its place, though it would benefit from line breaks or bullets for easier scanning. Still, the length is appropriate for the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining return values, which it does ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers failure modes (PatentsView sunset), fallback behavior, and the alternative tool, making it highly 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 provides 100% coverage of the three parameters, so the baseline is 3. The description adds meaning by explaining the `since` format (ISO date or relative shorthand) and recommending a typical window ('30d' or '1m'). It also clarifies that `value` accepts a ticker or CIK, reinforcing the schema. This extra usage guidance nudges the score to 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 defines the tool as a 'change feed for a company in the last N days/weeks/months' and enumerates specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling tool entity_profile, which retrieves static profiles, making the purpose unmistakable.

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

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

The description opens with natural-language query examples ('What's new with X', 'latest on Y', 'what happened to Z this week / month / quarter') and explicitly states when to use entity_profile instead. It also gives parameter usage guidance (e.g., 'Use "30d" or "1m" for typical monitoring'), providing clear contextual instructions.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and idempotent behavior. The description adds valuable context about memory scoping (by identifier) and persistence (persistent for authenticated users, 24 hours for anonymous), which goes beyond the structured fields.

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

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

Four sentences, front-loaded with purpose, and every sentence provides useful information. No fluff or repetition of schema details.

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

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

For a simple two-parameter save tool, the description covers purpose, usage, persistence, and pairing with sibling tools. No output schema is needed for a write operation, and the context is complete.

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

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

Schema coverage is 100% with clear descriptions and examples for both key and value. The description adds general examples of what to store but doesn't substantially extend the schema's parameter meanings, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, using specific verbs and resources. It distinguishes itself from siblings like recall and forget by explicitly naming them.

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

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

Provides explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference) and names alternatives (recall, forget). This helps the agent select the correct tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds significant behavioral context: it reveals that calls cascade through multiple endpoints, that company names are auto-disambiguated, and that it returns specific citation URIs. This gives the agent insight into internal complexity and output structure that is not available from annotations alone.

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

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

The description is longer than average but every sentence earns its place. It is front-loaded with example queries, followed by the core purpose, then structured details for each entity type. The formatting with SUPPORTED TYPES makes it scannable and 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?

Despite lacking an output schema, the description thoroughly covers return values (ticker, CIK, company name for companies; RxCUI, ingredient, brand for drugs) and includes citation URIs. It also covers internal behavior (cascading endpoints), input flexibility, and usage context, making it fully self-contained for an agent.

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

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

The schema already covers both parameters comprehensively (100% coverage). The description adds value by clarifying accepted input formats for companies (ticker, CIK, or name) and drugs (brand or generic), along with auto-disambiguation behavior. This goes beyond the schema's examples, though it doesn't provide exhaustive formatting rules.

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: resolving user-spoken names to canonical identifiers. It provides specific examples ('What's the ticker for…') and distinguishes it from sibling tools by emphasizing that other tools require these IDs as input. The verb 'resolve' and the explicit 'other tools require as input' make the purpose unmistakable.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. However, it does not mention when not to use it or name alternative tools, so it falls short of the full 5 because there is no explicit 'when-not' or alternative differentiation.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds beyond this by explaining the probe mechanism ('Probes each entity... with ai_visibility_check') and the return format ('ranked list with score, confidence, signal density per entity'). This provides useful context beyond the structured flags.

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

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

Three sentences, front-loaded with the core action, followed by method and use case. No redundant phrases; 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?

No output schema exists, but the description compensates by detailing the return structure (score, confidence, signal density). It also covers the use case and algorithm. Minor gaps like configurable models are addressed in the schema, so the description is sufficiently complete.

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

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

Schema description coverage is 100% for all parameters, so baseline is 3. The description reinforces the first-entity-as-subject concept but adds little beyond the schema's parameter descriptions. It does not introduce new parameter-specific meaning.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and 'ranks by score, surfaces which is most/least recognized.' It differentiates from sibling ai_visibility_check by emphasizing multiple entities and side-by-side 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 clear context: 'Useful for competitive AI-marketing audits' with an example. It names the underlying tool (ai_visibility_check) and implies when to use this wrapper, but does not explicitly state when not to use alternatives or name exclusion scenarios.

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 readOnly/idempotent, and the description adds substantial behavior: it fans out to two external services, explains partial failures with a 5-30s window for bundlephobia's first measurement, and notes sources_failed reporting. 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 dense but well-structured, starting with the composite purpose, then usage, return fields, ecosystem constraint, and failure behavior. The list of return field names is necessary since there's no output schema, but the length is slightly above the ideal minimal; still, every sentence earns its place.

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

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

For a complex composite tool with no output schema, the description fully covers return values, failure modes, latency expectations, and ecosystem limitations. It even names the alternative tool for non-NPM cases, making the description self-contained.

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

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

The schema has 100% coverage with clear descriptions for both 'package' and 'version', so the description doesn't need to add parameter details. The main description adds context about the return behavior but not new parameter semantics, fitting the baseline of 3 for high schema coverage.

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

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

The description clearly defines the tool as a composite check for 'should I add this npm package to my project' that fans out across deps.dev and bundlephobia. It distinguishes from siblings by specifying NPM-only scope and naming deps.dev:version as the alternative for other ecosystems.

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

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

It explicitly states when to use: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion: non-NPM ecosystems fall under deps.dev:version directly, guiding the agent to an 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, idempotentHint, and destructiveHint=false, covering safety. The description adds value by detailing the return contents (name, summary, record_count, owner/org, url) and how to use the url with other tools. This goes beyond what annotations provide 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?

Two sentences: the first sets scope and action, the second lists return fields and downstream usage. Every sentence earns its place with no wasted words.

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

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

With no output schema, the description compensates by explicitly listing return fields and pointing to query_layer/layer_info for next steps. Annotations cover safety and schema covers parameters, so this description is complete enough for an agent to decide when to use it and what to do with the 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?

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond the schema, but it does contextualize 'query' as a keyword search and the overall purpose. Since the schema already documents query, limit, and org_id fully, the description's contribution here is minimal.

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

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

The description clearly states a specific action ('Search') and resource ('City of Houston GIS open geospatial datasets'), with examples of dataset types. It also distinguishes itself from siblings by explaining that the output includes a Feature Service url to be passed to 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 implies when to use this tool: to discover datasets by keyword before querying them. It explicitly mentions downstream tools query_layer and layer_info, giving context on how to use the result. However, it doesn't explicitly state when not to use it or alternative search methods, so it's not 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?

The description adds rich behavioral details beyond annotations: BGE-base-en embeddings, 500-character overlapping windows, 200K character cap with truncation flag, and that every passage includes character offsets and similarity scores. No contradictions with readOnly/openWorld/idempotent 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 information-dense but every sentence adds value: core functionality, use case, pairing with sibling, implementation details, and limitations. It is well-structured, front-loaded with the action, and not overly verbose.

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 explains return values (passages with offsets and similarity scores), limitations (truncation), and pairing with sibling tools. It gives enough context for an agent to decide when and how to invoke the tool.

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

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

Input schema already provides 100% coverage with descriptions for text (incl. max length), limit (1-20, default 5), and query (with examples). The description mostly reinforces schema semantics and adds minimal extra meaning, so baseline 3 is appropriate.

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

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

Description clearly states the tool performs semantic search inside a fetched record, distinguishing it from siblings by emphasizing it works on text already pulled, with passages and offsets. It also differentiates from ask_pipeworx_grounded by its focus on local search within a single document.

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

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

Explicitly states when to use: when the record is too big for the prompt. It also explains how it pairs with ask_pipeworx_grounded and why this is better than grounding over the whole document, giving clear context and an 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 state readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description adds substantial context without contradiction. It discloses side effects (returns subscription id, auto-disables webhook after 10 failures), prerequisites (verified phone, OAuth account), and delivery behavior (feed always on).

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

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

The description is long but densely packed with necessary details, examples, and constraints. It is front-loaded with the core purpose and returns value, though it could be broken into clearer sections for scannability.

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

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

Despite no output schema, the description covers the return value (new subscription id, webhook secret), prerequisites, all parameter variants, delivery options, and fallback behavior. It is complete for a moderately complex subscription tool with nested parameters.

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

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

Schema coverage is 100%, and the description adds rich meaning beyond the schema: concrete examples for each type (e.g., sec_8k with items:['5.02']), delivery constraints (E.164, verified phone, 10/day cap), and webhook signing details. This far exceeds the baseline.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and including explicit subscription types.

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

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

The description gives clear context for use, including supported subscription types, required OAuth account, and delivery channels. It names an alternative for consuming alerts ('pull via recent_alerts') but does not explicitly state when *not* to use subscribe; still, the guidance is strong.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description goes beyond by detailing the return structure (category-bucketed example questions with exact tool + argument shape), the 'live catalog' aspect, and the effect of optional topic filtering, giving a clear mental model of tool behavior.

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

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

The description is dense but organized: it opens with illustrative queries, then explains the output, parameter behavior, and usage priority. While lengthy, each sentence contributes unique information; only the long category list could be trimmed without losing much.

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

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

With no output schema, the description adequately explains what is returned (category-bucketed example questions with tool/argument shapes). It covers invocation modes, parameter semantics, and the intended use case, making the tool self-sufficient for an agent.

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

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

Schema coverage is 100% with a thorough description of the optional `topic` parameter. The tool description adds example values ('finance', 'pharma', 'betting') and clarifies the omit behavior ('full spread'), reinforcing the schema without duplicating it entirely.

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 the onboarding entry point for discovering what Pipeworx can do, distinguishing it from siblings like discover_tools and ask_pipeworx. It specifies the verb (suggest questions), the target resource (Pipeworx capabilities), and the output (category-bucketed example questions with tool/argument shapes).

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

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

Provides explicit instructions: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also gives concrete example queries and explains when to omit or pass the `topic` parameter, offering clear context for selection.

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

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

Beyond the annotations, the description discloses that ownership is enforced, the row is deactivated (soft delete) rather than deleted, and historical events remain available via recent_alerts. These details are not present in the annotations and give important behavioral context for a mutation 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 sentences, each contributing unique value: core action, ownership rule, and post-cancellation behavior. No superfluous wording, 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 single-parameter mutation tool with rich annotations and full schema coverage, this description is complete. It states what happens to the data and where historical events can be accessed, leaving no essential ambiguity for an agent invoking 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 fully describes id as a subscription uuid returned by subscribe. The description adds behavioral context—ownership enforcement and soft-delete—which enriches the meaning of the parameter beyond a simple identifier.

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, clearly distinguishing it from siblings like subscribe and list_subscriptions. It also specifies the ownership constraint, which clarifies the exact scope of the 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: you can cancel only your own subscriptions, implying you shouldn't use it for others' subscriptions. It indirectly signals using recent_alerts for historical events, but it does not explicitly name alternatives or provide a when-not-to-use clause beyond the ownership rule.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds significant behavioral context: returns specific verdict types, provides pipeworx:// citations, explains routing to live sources, and mentions the fast path for company-financial claims. This goes well beyond the annotations and gives the agent a clear mental model of what happens inside the tool.

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

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

The description is dense but every sentence serves a purpose: trigger phrases, usage scope, claim-type routing, return value summary, and efficiency claim. It is front-loaded with examples and has no fluff, making it appropriately sized for a tool with nuanced behavior.

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 the return values (verdict, actual value with citation, reasoning), covering the tool's complexity. It handles both claim categories and parameter behaviors, so the agent has enough information to invoke the tool correctly in a variety of scenarios.

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

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

Schema coverage is 100% for both parameters, but the description adds meaning beyond the schema: it gives concrete examples for claim, explains the tolerance_pct override behavior for hallucination detection (1–2%), and clarifies the default (implied by wording, capped at 5). This enriches the parameter understanding substantially.

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 natural-language claim verification system with explicit trigger phrases ('Is it true that…', 'fact check', etc.). It distinguishes the tool by explaining its internal routing (SEC EDGAR vs grounded pipeline) and states it replaces 4–6 sequential calls, differentiating it from sibling research/fact tools.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and provides nuanced guidance for company-financial vs other claims. However, it does not explicitly name alternative sibling tools or state when NOT to use it, so it lacks the clear exclusionary guidance seen in top-tier examples.

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