Arcgis Marioncountyor

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context beyond annotations, including the free default model ('Workers AI Llama-3.3-70b'), the BYO-key auth/cost behavior ('you pay Anthropic directly'), and the returned structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It does not contradict the annotations.

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

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

The description is three sentences, front-loaded with the core action, and every sentence contributes unique value: operation, parameters/billing, output format, and use cases. 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?

The tool has no output schema, so the description compensates by listing the per-model return object and combined view. It covers the main operation, parameters, use cases, and cost/auth context. However, it does not detail what 'signals' or the 'combined view' contain, which is a minor gap for a tool with this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by naming the exact default model ('Llama-3.3-70b') and clarifying the purpose of the `_apiKey` parameter (BYO key, direct billing to Anthropic). This is useful information not present in the parameter 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 uses a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business / brand / product / topic') and adds a concrete outcome ('score visibility (0-100) per model'). This clearly distinguishes it from sibling tools like scan_competitor_ai_presence, which appear narrower in scope, by covering general brand/product/entity visibility across multiple models.

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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative sibling tools.

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

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

Beyond the annotations (readOnly, idempotent), the description reveals that the tool routes to 5,501 tools across 1,441 sources, fills arguments automatically, returns structured answers with citation URIs, works on every tier, and makes a single fast call. This adds substantial behavioral context about internal routing and output format that the annotations do not cover.

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

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

The description is concise despite its length: every sentence contributes actionable information. It front-loads the 'PREFER OVER WEB SEARCH' instruction, then covers routing behavior, trigger phrases, examples, default status, and escalation paths without fluff. The structure is clear and logically organized.

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 specifies the return format ('structured answer with stable pipeworx:// citation URIs') and covers the tool's capabilities and limitations. It addresses alternative tools and when to use them, making it complete for a complex agentic router tool with only a single conceptual parameter.

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% (question plus aliases are documented). The description adds value by explaining that the parameter is a natural-language request and providing concrete examples (e.g., 'current US unemployment rate'), which helps the agent formulate optimal questions. It doesn't detail each alias, but that's already covered by the schema, so the extra examples justify a slight boost over 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 explicitly states the tool routes factual questions to the appropriate specialized tool among 5,501 options and returns structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unmistakable.

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

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

The description provides strong usage guidance: it declares itself the default entry point, tells users to prefer it over web search for a comprehensive list of data types, gives example query phrasings, and explicitly says when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds valuable context: it is a full working router (not a stub), may have live routing improvements under test, and currently matches ask_pipeworx exactly. This goes beyond the safety profile to describe experimental variability.

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

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

The description is three sentences and front-loaded with the key point that it's a beta version. It includes necessary details (same 5,501 tools, current state, no active candidate) without excessive fluff. Slightly verbose in the middle sentence but each part 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 simple question-router tool, the description covers its identity, current behavior, relationship to stable, and experimental nature. It doesn't describe return format, but explicitly states 'same response shape' as ask_pipeworx, which is sufficient given the complexity. No output schema exists, but the description compensates adequately.

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

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

Schema description coverage is 100%, with all six parameters clearly documented as aliases for 'question'. The description adds no parameter-specific detail, but the schema already handles it. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, while explicitly distinguishing it from the stable ask_pipeworx and other siblings. It states the specific purpose: to test candidate routing improvements.

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.' It also explains the relationship to the stable router and that results are compared for potential merges. It names the alternative (ask_pipeworx) but could be clearer about when to prefer stable over beta.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the refusal mechanism with specific refusal_reason categories, the return shape, and the strict dependence on tool result data. It also highlights the extra LLM call cost and the 'must not invent facts' guarantee, which are critical behavioral traits for an agent.

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

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

Although moderately long, each sentence delivers distinct value: the mode's purpose, the routing behavior, the exact return/refusal contract, use cases, and cost tradeoff. It is front-loaded with the key concept and uses lists effectively, with no filler.

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

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

For a grounded QA tool with no output schema, the description covers what the tool returns, refusal conditions, use cases, relationship to siblings, and performance cost. This is comprehensive enough for an agent to make informed invocation decisions.

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 (all aliases for the question field). The description does not add any parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool result content. It distinguishes itself from sibling ask_pipeworx by emphasizing the grounded/refusal behavior, making its purpose unmistakable.

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

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

Explicitly instructs to use 'whenever an answer will be quoted, cited, or acted on' and to 'prefer ask_pipeworx for casual lookups.' It names the alternative tool and provides a cost consideration (one extra LLM call), giving clear when-to-use vs when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context: resolver contract with confidence levels, blocking statuses (low_confidence_match, market_closed_or_inactive), tradeability warnings, news fallback flags (_fallback_attempted, retry_after_sec), and cancellation-rule risk with EV impact. This goes well beyond the annotations.

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

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

The description is very long (800+ words) but is structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and each section provides dense, actionable content. While not concise, the length is justified by the tool's complexity, and the front-loaded purpose sentence anchors the reader.

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 thoroughly documents return shapes (result.market, result.analysis, result.evidence), the resolver contract (market_match_confidence, market_match_score, suggestions), parent_event details, news fallback fields, safety short-circuits, and resolution-rule risks. It covers all major scenarios an agent could encounter, making it complete for this complex tool.

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

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

The input schema covers all 3 parameters with descriptions and examples (100% coverage), so the baseline is 3. The description adds some context about fan-out behavior and depth, but most parameter semantics are already in the schema. No additional syntax or edge-case parameter guidance is provided.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' specifying the verb, resource, and scope. It differentiates from sibling tools like polymarket_edges by emphasizing aggregated research, evidence packets, and market-vs-model 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?

Explicitly provides usage triggers: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains blocking behavior for low-confidence matches and closed markets. However, it does not explicitly name alternative tools or give 'when not to use' guidance, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description reveals significant behavioral details: company type pulls specific SEC EDGAR/XBRL fields from latest 10-Ks, handles off-calendar fiscal years (AAPL, NVDA examples), drug type pulls FAERS counts, and results are sorted by primary metric with citation URIs. This goes far beyond what annotations provide.

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

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

The description is dense but well-organized: it leads with user-intent phrasing, then explains behavior, sources, sorting, and output format. Every sentence carries useful information, though the length is above the bare minimum and contains some redundancy (e.g., 'ONE parallel call' and 'ALWAYS PREFER over sequential' overlap).

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

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

With no output schema, the description takes on the burden of explaining return behavior, and it does so: sorted results, paired data, and citation URIs per entity. It also covers entity type specifics, cardinality constraints, and examples. It could mention potential errors or rate limits, but for the tool's complexity it is largely 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 describes both parameters with 100% coverage, so the baseline is 3. The description adds semantic depth by explaining how the 'type' enum changes data sources and metrics ('company' pulls financials, 'drug' pulls adverse-event/trial counts), and gives realistic examples for 'values' (tickers, drug names). This adds value beyond the schema.

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

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

The description begins with concrete query patterns ('X vs Y', 'which is bigger') and explicitly states the tool performs side-by-side comparison of 2–5 entities in a single parallel call. It clearly distinguishes from sequential single-pack lookups and lists two supported entity types, making the purpose unambiguous.

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

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

The description gives an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent when to use the tool, and it contrasts with the alternative of multiple sequential lookups, though it does not name a specific sibling tool like entity_profile as the 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: it's not open-web search, it decomposes questions and routes facets in parallel, returns gaps[] for unanswered facets (never invented), performs gap-recovery and contradiction scans based on depth, and semantically excerpts long records. It also states latency expectations and auth requirements, far exceeding what annotations provide.

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

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

Although long, the description is dense and every sentence adds behavioral or usage information. It front-loads the account requirement, then explains what the tool does, when to use it, how depth alters behavior, and what the output contains. The structure is logical and avoids fluff, which is appropriate for a tool with this complexity.

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

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

With no output schema, the description fully covers return values: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also addresses auth, pricing, latency, limitations, and alternatives. This is a complete picture for an agent to decide whether 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?

The schema already documents both parameters well (100% coverage), so the baseline is 3. The description adds meaningful additional semantics: depth:'thorough' requires a paid plan, 'standard' and 'thorough' return contradictions[], and the question parameter is explicitly described as accepting broad/multi-part natural language. This enriches the schema without being redundant.

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

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

The description clearly identifies a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources...' and explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx. It also states what it returns (a findings packet with evidence, confidence, source, citations) and for what kinds of questions it's best, making it unmistakably distinct.

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

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

Usage guidance is exceptionally explicit: 'Best for broad/multi-part questions over structured data' and then provides concrete 'when NOT to use' instructions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also notes account requirements and paid depth tiers, giving clear decision criteria.

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

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

Although annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds useful behavioral context: it returns top-N results with names, descriptions, full schemas, and curated examples, and each result is 'ready to call directly, no second schema lookup needed.' This complements the annotations without contradicting them.

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

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

Four sentences, each earning its place: purpose, usage trigger, return behavior, and a strategic directive ('Call this FIRST'). Front-loaded and dense with specific information, yet not bloated.

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

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

Given no output schema, the description thoroughly explains what the tool returns (top-N tools with names, descriptions, input schemas, examples) and how to use it. It also includes a broad domain list to set expectations, making it complete for a meta-tool of this complexity.

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

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

Schema description coverage is 100%, including aliases and examples, so the baseline is 3. The description adds minor semantic value by linking the query parameter to 'describing the data or task' and hinting at the limit parameter via 'top-N,' but it does not substantially enrich the parameter understanding beyond what the schema already provides.

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

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

The description's first sentence uses a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this meta-tool from sibling domain-specific tools by framing it as a discovery tool for the option set, not a data-querying tool.

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

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

Explicit guidance is given: '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 also implies when not to use it (when a direct answer is needed), satisfying the when/when-not criteria.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses specific behavioral traits: it fans out across multiple sources, soft-fails for the USPTO API sunset, and details the exact return fields. No contradiction with annotations.

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

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

The description is front-loaded with example queries and a clear definition, then systematically covers data sources, output fields, and parameter handling. Every sentence earns its place, making it appropriately sized for a tool of this complexity.

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

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

Despite having no output schema, the description explicitly enumerates all return fields, data sources, failure modes, and parameter constraints. It provides a complete, self-contained reference for the agent to invoke the tool correctly.

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

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

The input schema already fully documents both parameters, including examples and the name limitation. The description repeats this information without adding significant new semantics, so a baseline score of 3 is appropriate given 100% 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 states the tool creates a full cross-source profile of a US public company in one parallel call, with concrete example queries. It distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making the purpose unambiguous.

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

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

Explicitly instructs to prefer this tool over chaining single-pack lookups for holistic views, and provides a direct alternative ('use resolve_entity first') when only a name is available. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds context beyond annotations by stating what happens (deletion of a stored memory) and why it might be used (clearing sensitive data), which helps agents assess the impact. It does not contradict the annotations.

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

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

The description is three short sentences, each earning its place: the operation, the usage context, and the relationship to sibling tools. No redundant or filler content, front-loaded with 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 simple single-parameter destructive tool with no output schema, the description provides the essential information: what it does, when to use it, and how it relates to other tools. The annotations cover destructive and idempotent behavior, so no further elaboration is needed.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete.' The description adds no new meaning beyond restating 'by key,' which is already in the schema. The baseline of 3 is appropriate since the schema fully documents the only parameter.

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

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

The description clearly states the action ('Delete') and the target resource ('previously stored memory') with the method ('by key'). It also distinguishes the tool from siblings by explicitly pairing it with 'remember and recall,' making its role in the memory workflow unambiguous.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names related tools ('Pair with remember and recall'), giving clear guidance on how this tool fits into the broader toolset.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral context by stating it 'fetches the page' and 'extracts' content, which implies network access and processing. It also explains the output format, though it does not detail error handling or rate limits. This adds value beyond the annotations.

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

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

The description is concise, with three sentences. The first sentence front-loads the core purpose, the second describes the underlying process and output, and the third lists practical use cases. Every sentence adds meaningful information without fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers all necessary aspects: purpose, process, output, and use cases. It explicitly states the output is a 'single text blob', which compensates for the lack of an output schema. The annotations cover safety and side-effect context, making this description complete 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 description coverage is 100%, so the baseline is 3. The description does not add additional parameter-specific details beyond what the schema provides for 'url' and 'max_links'. It indirectly references the extraction behavior but does not clarify parameter syntax or defaults beyond the schema.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It specifies the process (fetch, extract title/description/key links, emit markdown) and the output (a text blob). This distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on visibility checking rather than file generation.

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 contexts for use, such as getting a client's site indexed, drafting llms.txt for a project, or auditing a competitor. It does not explicitly mention alternative tools or state when not to use this tool, but the use cases are sufficiently clear to guide an agent.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds value by clarifying exactly what information the tool returns (fields, geometry type, count, capabilities), which is not stated in the annotations. No contradictions or hidden side effects are present.

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?

A single, tightly-packaged sentence that fronts the action and delivers all essential information. No filler or redundant phrasing.

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

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

For a simple one-parameter read tool with strong annotations and a self-contained description, this is fully sufficient. The description specifies the input (URL), the output components, and the nature of the operation. No output schema is needed because the description enumerates the return contents.

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 url parameter is already well-described in the input schema. The description only adds 'by url' and sample output components, but doesn't contribute additional parameter-level meaning beyond what's in the schema. 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?

Description uses specific verb 'Get' and identifies the resource as an ArcGIS Feature/Map Service layer's schema. It enumerates the exact contents (fields, geometry type, record count, capabilities), clearly distinguishing it from sibling tools like query_layer which likely fetch data.

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

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

The description provides clear context: use this tool when you need schema/metadata for a specific ArcGIS layer by URL. It doesn't explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when it's appropriate. Sibling tools like query_layer and search_within serve different functions.

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

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

The description adds behavioral context beyond annotations by specifying it returns active subscriptions, enumerates returned fields, and is scoped to the caller. The annotations already declare readOnlyHint, destructiveHint, etc., so the additional field list and scope info are valuable.

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

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

The description is three concise sentences, each earning its place: purpose, return fields, and usage guidance. No fluff, front-loaded with 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?

The tool is simple, has one optional parameter well-described in the schema, and the annotations cover safety. The description fully covers the return values and usage guidance, so it is complete for this context.

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

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

Schema description coverage is 100% for the single parameter include_inactive, and the schema already describes it thoroughly. The description does not add any extra meaning about the parameter, so the baseline of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions,' which is a specific verb+resource. It distinguishes from siblings like subscribe/unsubscribe by focusing on the read-only list operation and mentions 'caller's' to clarify scope.

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

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

The description gives explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It provides clear context for when to use the tool, though it does not explicitly name alternatives or 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 are all false/neutral, so the description carries the full burden. It reveals key behaviors: filing without an account returns a claim_token, passing the token later lets you read resolution status, rate-limiting exists (5 per identifier per day), and it does not count against tool-call quota. 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 long but entirely purposeful; it is front-loaded with the core action and then systematically covers scope, method, token mechanics, rate limits, and cost. A few phrases like 'signal directly affects roadmap' are motivational rather than essential, so it is not perfectly lean, but every operational sentence contributes.

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

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

Given the tool has no output schema and uses a relatively free-form feedback model, the description is remarkably complete: it explains the categories, expected message specificity, the claim-token mechanism for follow-up, exclusions, rate limits, and quota impact. An agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining the claim_token round-trip flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and by guiding message content ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This extra context earns a 4.

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

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

Purpose is explicit: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb+resource action that is clearly distinct from sibling tools like ask_pipeworx, deep_research, or discover_tools, which are research or catalog-related rather than feedback submission.

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?

Extremely detailed when-to-use guidance: bug, feature/data_gap, or praise. Explicitly states when NOT to use it (for tools from a different MCP server, file there instead) and provides inclusion criteria ('Pipeworx tool names are the ones this connection lists'). Also gives practical instruction about not pasting end-user prompts and notes the daily rate limit.

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

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

Annotations already mark read-only/idempotent, and the description adds valuable context: caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). All consistent with annotations and beyond 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?

One focused paragraph with a clear opening, a structured list of use cases, and a closing note on data sourcing. The content is relevant and well-organized, though the three use cases could be trimmed slightly without losing meaning.

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

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

Covers purpose, return contents, window options, use cases, data provenance, privacy, and caching. Without an output schema, this is sufficient for an agent to correctly select and invoke the tool, and it distinguishes itself from the many sibling tools.

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

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

The sole parameter 'window' is fully documented in the schema (100% coverage) including semantics of shorter vs longer windows. The description merely reiterates the window options and adds cache timing, which does not meaningfully extend parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

Description opens with 'What other AI agents are calling on Pipeworx right now' and specifies 'Returns the top tools, top packs, and total call volume over a recent window', using a specific verb and resource that clearly distinguishes it from sibling discovery tools like discover_tools.

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

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

Provides three explicit use cases ('Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool... (3) seeing whether your use case aligns...'), which give clear context. It does not mention alternatives or when not to use, so it misses the 'exclusions' bar for a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the bar is lower, but the description still adds substantial behavioral context. It discloses internal thresholds (3pp partition deviation, 0.30 Jaccard similarity, 20% placeholder fraction), describes the fill-check distinction between theoretical and realizable edge, and explicitly warns 'do not trade it' when the edge isn't in the book. This is far beyond what annotations provide.

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

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

The description is long but well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every block carries operational detail necessary for correct use, and the density is justified by the tool's two-mode complexity. It is not wasteful, though it is more verbose than the simplest 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 read-only analysis tool with no output schema, the description covers invocation modes, filtering rules, response shape, edge cases (skipped_low_similarity, placeholder filtering), and the fill-check caveat with a clear no-trade condition. It also directs users to polymarket_fill_risk for custom sizing, making the tool's boundaries and limitations clear. This is a complete operational picture.

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 major meaning beyond the schema. It explains when to use event versus topic, provides concrete slug and seed question examples, notes that full Polymarket URLs are accepted, and details what each parameter triggers (child-market partition check vs. cross-event flattening and comparator). This is rich semantic enrichment, not just a restatement of parameter names.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's three modes (trending_scan, event, topic) and differentiates it from siblings by naming polymarket_fill_risk for custom sizing, making the tool's unique role obvious.

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

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

The description gives explicit conditional guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' and recommends event for a specific market and topic for cross-event scanning. It also explains when cross-event mode adds value and points to polymarket_fill_risk for custom sizing. It doesn't enumerate all sibling alternatives, but the main usage paths are clearly laid out.

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

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

Even though annotations already convey read-only and idempotent behavior, the description goes far beyond by detailing model families (crypto_price, news_momentum, partition_overround, etc.), response segments, caching ('Cached 1h at the KV level'), the 24h-move warning, placeholder filtering, and Fed exclusion logic. This is exceptional behavioral disclosure beyond annotations.

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

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

The description is long and dense but well-structured with segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL). It front-loads the core purpose and then systematically details behaviors. While verbose, every sentence provides value for a complex tool with 9 parameters and no output schema; it could be trimmed but remains appropriately detailed.

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 full burden of explaining return values and does so thoroughly: it details by_segment structure, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), _diagnostics, and the Fed exclusion note. It also explains caching and filter behavior, making the tool highly 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% with rich parameter descriptions, so baseline is 3. The description adds extra context such as classifying min_liquidity and max_spread_pp as 'TRADEABLE-EDGE KNOBS' and explaining why min_partition_leg_kelly exists (partition arbs return kelly_fraction_half=0 at parent level). This adds meaning beyond the schema but is somewhat redundant given the schema's own detail.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings by stating it's built for 'what should I bet on today' and avoids paging hundreds of markets, making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool: 'Built for "what should I bet on today"' and explains that it helps agents discover opportunities without manual pagination. It gives usage guidance on knobs (e.g., min_liquidity, max_spread_pp) but does not explicitly name alternatives or exclusions versus sibling tools, so it stops short of a 5.

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

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

The description adds substantial behavioral detail beyond the annotations, including how snapshots are generated ('snapshots are written when polymarket_edges runs on a cache-miss'), the TTL constraint ('60-day snapshot TTL'), and the computation method ('decay numbers come from daily closes of edge_pp_net... not intraday'). It also explains the response structure. This goes well beyond readOnlyHint and other annotations.

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

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

The description is structured with clear labels ('Args:', 'RESPONSE:', 'LIMITS:'), making it scannable despite its length. Each sentence contributes meaningful information about usage, response structure, or limitations, with no filler or redundancy.

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

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

Since there is no output schema, the description fully specifies the return value structure (tracked[], expired[], snapshot_dates[]) and the semantics of each field. It also covers edge cases like snapshot gaps and the TTL limit, making it a complete reference for the tool's behavior.

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

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

The schema already provides full parameter descriptions (coverage 100%), so the baseline is 3. The description's 'Args:' section restates the schema's defaults and adds the term 'snapshot family' for window, but does not provide additional syntactic or format detail not already present in the schema. Therefore, it adds marginal 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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' which clearly identifies the tool's function: tracking edge persistence and decay over time. It goes beyond the title by explaining the specific question it answers ('how long has this edge existed and is it shrinking?') and distinguishes it from both polymarket_edges (current edges) and other sibling tools by focusing on historical persistence and decay.

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

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

The description provides a concrete scenario: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take),' illustrating when the tool is valuable. It also explains the limits of history depth, but does not explicitly state when to use alternatives, so while context is clear, exclusions are absent.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond this by explaining that the tool walks the order-book ladder, returns specific metrics like top_of_book and vwap_fill_price, and details the risk of partial basket fills converting an arb into an unhedged directional position. This is rich behavioral context 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 long (250+ words) but each sentence carries useful information. It is well-structured with 'SINGLE-MARKET:' and 'BASKET:' sections, and the opening sentence front-loads the core purpose. However, it could be slightly more concise by using bullet points or splitting into shorter paragraphs; the density of information makes it a bit heavy to parse.

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

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

There is no output schema, yet the description enumerates all major return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers input preconditions, mode selection, and use-case context, making it fully 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?

Though schema coverage is 100%, the description adds significant meaning: it clarifies that `market` and `event` select mutually exclusive modes, explains `side` defaults for each mode (including auto-detection in basket mode), and gives different interpretations of `size_usd` (max spend on buys vs target proceeds on sells vs settlement notional in basket mode). This goes 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 opening sentence 'Realizable-vs-theoretical edge check against live CLOB order-book depth' clearly states a specific verb ('check') and resource ('live CLOB order-book depth'). It distinguishes itself from sibling tools by focusing on fill risk rather than opportunity discovery, and explicitly references polymarket_arbitrage and polymarket_edges as related but different 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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale (theoretical overround on thin books is not capturable) and describes two distinct modes (single-market vs basket) with clear guidance on when each applies.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral details: compatibility_warning conditions, matched_pairs semantics, temporal_alignment effect on validity, skipped_cross_type/subtype counters, and the fact that many pre-mapped topics return warnings. It openly states that some pairings yield mathematically meaningless spreads. This exceeds what annotations provide and fully aligns with them.

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

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

The description is long but well structured with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes either to usage, interpretation, or caveats. While dense, it avoids redundancy and front-loads the core purpose. A slight trim could improve readability, but it remains appropriately organized for a tool with many edge cases.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It explains the response structure (leg-by-leg prices, top_spreads_pp), the safety fields and their meanings, temporal alignment semantics, and the skip counters. It also provides a realistic expectation that most pre-mapped topics return warnings. No critical aspect of the tool's behavior is left undocumented.

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

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

Although the input schema already documents all three parameters with descriptions and examples (100% coverage), the description adds semantic context by explaining how the parameters interact: the topic is a pre-mapped shortcut that auto-fetches matching events, while explicit tickers override the mapped sides. It also clarifies the 'same resolving question' relationship between the two explicit identifiers. This goes beyond the schema's per-field descriptions, but the schema already does most of the work.

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 clear verb+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes from siblings by naming the two specific venues and the concept of a matched spread. The two modes (topic and explicit tickers) further specify the tool's scope.

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

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

The description gives clear when-to-use context (comparing the same resolving question across venues) and warns when the spread is not meaningful (non-equivalent bet shapes, temporal misalignment, unmatched pairs). It also cautions that 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility_warning today. However, it stops short of explicitly naming alternative sibling tools or contrasting when to use this vs. polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns attribute rows and geometry, and supports SQL-like filtering, pagination, and field selection. This goes beyond annotations without contradicting them.

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

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

The description is two sentences long, front-loaded with the core purpose, and every phrase contributes value. The first sentence defines scope and parameters; the second gives a concrete sampling example. 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?

For a tool with 6 parameters, no output schema, and good annotations, the description covers the essential context: tool purpose, source of url, query capabilities, and return type. It even ties to the search_datasets workflow. It could be more explicit about the exact output format or handling of empty results, but it's sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100%, with every parameter having a description, so the baseline is 3. The description restates the parameter list and offers one combined usage hint (sampling with where='1=1' and out_fields='*'), but it doesn't add deeper semantics to individual parameters beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Query an ArcGIS Feature Service / Map Service layer by its url.' It uses a specific verb ('Query') and identifies the exact resource type, while also referencing its origin from search_datasets, distinguishing it from sibling tools like layer_info or search_datasets.

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

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

The description provides clear usage context by indicating the url comes from search_datasets, implying a workflow: first search, then query. It also gives a practical sampling tip (where='1=1', out_fields='*'). However, it doesn't explicitly mention when to prefer an alternative like layer_info or when not to use this tool, so it falls short of a perfect 5.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds useful scoping context (anonymous IP, BYO key hash, account ID) and the dual retrieve/list behavior, enhancing understanding 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?

Every sentence earns its place: the main function, usage context, scoping detail, and relationship to siblings are packed into a compact, front-loaded description with no filler.

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

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

For a single-parameter tool with strong annotations, the description fully covers purpose, usage, scoping, and sibling relationships. No output schema is needed given the simple nature of the operation.

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

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

The schema fully documents the 'key' parameter including the omit-to-list behavior, so the description's explanation adds no new semantic information. Baseline 3 applies since schema coverage is 100%.

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: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools like remember and forget by specifying the retrieval/list action.

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

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

It gives concrete use cases (target ticker, address, research notes) and advises pairing with remember/forget, but does not explicitly state when not to use this tool or mention alternatives beyond the immediate memory trio.

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 valuable context about the returned payload structure (source, citation_uri, raw event payload) and discloses that mark_read:true flags events as read, which is a mild state-changing behavior. This transparency about the optional side-effect goes beyond the annotations without contradicting them.

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

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

The description is compact (three sentences) and well-structured: it states the core purpose, describes the return payload, covers filtering options, explains the mark_read behavior, and notes a non-MCP alternative. Every sentence adds value 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?

Given the tool has 5 parameters, no output schema, and good annotations, the description is complete. It explains the return format (each alert carries source, citation_uri, and raw event payload), the filtering capabilities, the mark_read semantics, and even provides an HTTP endpoint for scripts. This covers all essential aspects for an agent to use the tool effectively.

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

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

Schema description coverage is 100% with per-parameter descriptions, so baseline is 3. The description enhances this by giving a concrete filter example (type "sec_8k") and explaining the practical effect of mark_read ('flag returned events read so the next call only shows newer ones'). This adds semantic depth 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's function: 'Pull fired events from your subscription feed. Returns the most recent alerts the evaluator has written to your persisted feed.' It specifies the resource (subscription feed alerts) and the action (pull/return), and distinguishes it from siblings like list_subscriptions, which lists subscriptions rather than alert events.

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

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

The description provides clear context on when to use the tool: for polling recent alerts, filtering by type/since, and using mark_read to control visibility. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, but does not explicitly compare against sibling MCP tools or state when not to use them. It gives good context without formal exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by detailing multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), specific failure modes (rate limits, 5xx, PatentsView sunset), and return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). 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?

Dense but efficiently organized; open with user-intent phrases, then logical progression through sources, fallbacks, date formats, and return value summary. Every sentence provides essential information, no filler. Completeness within a compact paragraph.

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

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

Given the tool's complexity (multiple upstream APIs, fallbacks, temporal parsing) and absence of output schema, the description fully covers expected inputs, behavioral nuances (including soft-failure), and output shape. It also names the alternative tool for static profiles, making it self-sufficient 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 coverage is 100% with descriptions for all three parameters. The description adds practical meaning not in schema: examples for `since` ('7d', '30d', '3m', '1y'), recommended value ('Use "30d" or "1m"'), and `value` accepts ticker or CIK. This enriches parameter understanding beyond the schema baseline.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with specific verb 'returns structured changes[]' and differentiates from entity_profile by stating 'Use entity_profile instead when you want the static profile'. This distinguishes it from siblings like recent_alerts.

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

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

Explicitly provides natural language example queries ('What's new with X', 'updates on Acme') and direct comparison to alternative tool entity_profile, stating when to use which. Also describes fallback behavior (GDELT→GNews) and date format guidance ('Use "30d" or "1m" for typical monitoring'), giving clear usage context.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and idempotency, but the description adds key behavioral context: storage as a key-value pair scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24-hour) sessions. This goes beyond what annotations provide.

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

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

The description is three sentences: purpose, usage trigger, and storage/persistence details. It is front-loaded with the most important information and contains no fluff; every sentence adds distinct 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?

For a simple write operation with 2 parameters and no output schema, this description is complete: covers purpose, usage scenario, storage semantics, persistence, and related tools. It fully meets the needs of an agent deciding when and how to invoke it.

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

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

The schema already describes both parameters with 100% coverage, but the description enriches them with domain examples ('resolved ticker', 'target address', 'user preference') and value types ('findings, addresses, preferences, notes'), helping the agent choose meaningful keys and values.

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

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

The description states the tool saves data for later reuse across conversations/sessions, with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes from sibling tools by mentioning 'recall' for retrieval and 'forget' for deletion, and provides concrete examples of what to store.

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 frames when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names sibling tools for complementary operations ('Pair with recall to retrieve later, forget to delete'), giving clear context for tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds transparency about internal cascading through multiple lookup endpoints and reveals it returns auto-disambiguated results with citation URIs (pipeworx://...), which is useful behavioral context beyond annotations. However, it doesn't specify response format or failure modes, but given annotations, a 4 is warranted.

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 clear sections: example queries, usage directive, supported types with specifics. It's a bit longer than average but every sentence carries useful information. The front-loading of examples and 'Use FIRST' directive is effective. Minor redundancy in supported types list could be tightened, but overall 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?

With 2 params, full schema coverage, and rich annotations, the description adds sufficient context: the types, return identifiers, citation URIs, and the fact it replaces multiple lookups. There's no output schema, so the description compensates by explaining what each type returns. It could mention error handling or edge cases, but given the tool's complexity and existing structured data, it's reasonably complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds specific semantics: for type='company' it returns ticker + 10-digit CIK + company_name from SEC EDGAR and a citation URI; for drug it returns RxCUI + ingredient + brand from RxNorm. It also clarifies that value accepts multiple input forms (ticker, CIK, name) and that disambiguation is automatic. This goes beyond the schema's brief parameter descriptions.

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

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

Description uses specific verb 'resolve' with examples of user queries, clearly states it maps names to canonical/official identifiers, and distinguishes from sibling tools like entity_profile or compare_entities. It also lists supported entity types (company, drug) with their respective return values.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', which is a clear usage directive. It also contrasts with alternatives by stating it replaces 2-3 manual lookups, and mentions the supported input forms (ticker, CIK, name) for disambiguation.

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, destructiveHint. The description adds value by disclosing that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It does not contradict annotations and provides behavioral context beyond them.

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

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

The description is two sentences with an embedded example, front-loading the primary purpose. Every sentence earns its place: the first defines functionality, the second explains the use case and return value. No filler or repetition of structured fields.

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

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

The tool has moderate complexity (multiple entities, optional models, API key), but no output schema. The description compensates by stating the return format ('ranked list with score, confidence, signal density per entity'). It also names the underlying probe tool and explains the first-entity rule. Minor gaps: no mention of error handling or rate limits, but these are not critical for a read-only, idempotent tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds important semantics for 'entities': 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies the interpretation of the first array element, which is not evident from the schema alone. It also provides a concrete example for the 'context' parameter.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It specifies the action (compare), resource (competitor AI presence), and behavior (probes with ai_visibility_check, ranks by score). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides explicit use cases: 'Useful for competitive AI-marketing audits' and an example query, 'does Claude know about us as well as our competitors?'. It implicitly differentiates from single-entity checks by emphasizing multiple entities, and clarifies that the first entity is the subject while the rest are competitors. This gives clear when-to-use guidance.

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

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

Adds important behavioral context beyond the readOnly/idempotent annotations: bundlephobia first-measurement latency (5-30s), partial failure degradation with sources_failed listing, and the NPM-only limitation. This helps the agent set expectations and handle 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 moderately long but information-dense, covering purpose, usage, return summary, and caveats in one paragraph. Every sentence earns its place, though it could be tightened slightly for faster scanning.

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 listing the summary block fields, per-advisory details, links, alternative versions, and failure behavior. It is complete for a high-level composite tool, though a few specifics (e.g., what advisory_count means) are left implicit.

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 documents both parameters (package, version) with 100% coverage, including scoped package acceptance and version defaults. The description adds only the ecosystem restriction, which is contextual but does not deepen understanding of the parameters themselves.

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 as a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It specifies what it returns and explicitly distinguishes itself from siblings by naming its data sources and ecosystem scope.

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

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

Provides explicit usage context ('Use whenever an agent asks...') and states a clear exclusion ('NPM ecosystem only in v1... fall under deps.dev:version directly'). This gives the agent unambiguous guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by disclosing the return fields (name, summary, record_count, owner/org, Feature Service url) and the relationship to downstream tools, which is practical behavioral context beyond the annotations.

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

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

The description is two sentences: the first states the core action and scope, the second outlines return values and downstream usage. Every word earns its place; no redundant or repeated schema 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?

Despite having no output schema, the description explicitly lists the returned fields and points to the next step. It covers the essential details needed to invoke and use the tool, including the optional org_id override in the schema and the scope limitation to Marion County GIS, making the description sufficient for a search tool.

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

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

The input schema has 100% coverage with descriptions for all three parameters (limit, query, org_id), so the schema fully explains parameter semantics. The description adds no additional parameter-level details beyond what the schema already provides.

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

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

The description clearly identifies the tool as a keyword search for Marion County GIS open geospatial datasets, listing example dataset types (parcels, addresses, zoning & public works). It distinguishes from siblings by explicitly directing users to pass the returned Feature Service `url` to query_layer/layer_info, which are sibling tools.

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

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

The description implies a workflow: search datasets first, then use query_layer/layer_info on the returned URL. This provides clear usage context and differentiates from downstream query tools, though it does not explicitly state when not to use this tool or compare it to other search tools like search_within.

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 indicate readOnly/openWorld/idempotent/non-destructive. The description adds non-obvious behavior: truncation at 200K chars with a flag, use of BGE-base-en embeddings with cosine over 500-char windows, and output details (offsets, similarity scores). These are not derivable 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 front-loaded with a precise one-line purpose, then appends usage and technical details in five dense sentences. No fluff; each sentence adds a distinct 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?

Despite having no output schema, the description fully characterizes the return payload (passages, offsets, similarity scores) and handles edge cases (input too large, truncation flag). It also connects to ask_pipeworx_grounded for broader workflow context.

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

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

The input schema already describes all three params with 100% coverage. The description enhances this with concrete examples (SEC 10-K, article), query examples ('supply-chain risk'), and clarifies that limit controls 'top-N' passages, adding context beyond the schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' giving a specific verb and resource. It further differentiates from siblings like ask_pipeworx_grounded by emphasizing that the text is already pulled, not fetched by the tool.

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

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

It explicitly states a clear use case: 'Use when the record is too big to cram into the prompt.' It also names the companion tool ask_pipeworx_grounded and explains how to combine them, giving both when-to-use 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description reveals the OAuth requirement, return of a subscription id, feed always-on behavior, and SMS verification with a 10/day cap. It does not elaborate on idempotency deduplication or failure scenarios implied by idempotentHint, but adds substantial 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 dense but efficiently written, with the core purpose and return value in the first sentence, followed by type details and delivery channels. It consists of two long sentences rather than bullets, slightly hurting scannability, but every clause provides needed 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?

Given a complex tool with nested objects and five subscription types, the description covers return value, auth prerequisites, three of five types with examples (the remaining two are in the schema), and delivery channels with verification caps. The lack of an output schema is partly compensated by the return statement, but error conditions and idempotency semantics are absent, preventing a perfect score.

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, but the description adds semantic richness with concrete examples like 'items:["5.02"] = officer change' and 'topic:"fed"' that teach the meaning behind params.type values. It also explains delivery channels with formatting examples, exceeding 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 opens with 'Create a proactive monitoring subscription to a live-data event stream,' a specific verb and resource that clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe. It also lists supported subscription types and the return value, removing ambiguity.

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

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

The description states that anonymous + BYO cannot persist subscriptions, which guides usage by requiring an OAuth account. It references complementary tools (recent_alerts, registry.alerts.json) for consuming the feed, but does not explicitly contrast with list_subscriptions or unsubscribe, leaving a small gap.

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 it read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it returns category-bucketed example questions, each with tool/argument shape, drawn from a live catalog, and supports optional topic filtering. This goes beyond annotation basics.

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 part serves a purpose: aliases, categories, two calling modes, and usage-first directive. It is front-loaded with the intent examples, though the wall-of-text format could be slightly streamlined with bullets.

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

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

For a simple tool with one optional parameter and no output schema, the description is highly complete. It explains what is returned, the categories, the tool/argument shape, the topic filtering, and the best time to use it, leaving no major gaps.

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

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

Schema covers the topic parameter fully (100% coverage) including the value list and omission behavior. The description adds examples like "finance", "pharma", "betting" but these are already in the schema description; no substantial new meaning is added.

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

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

Clearly states it is the onboarding entry point that returns category-bucketed example questions with the exact tool + argument shape. Distinguishes from siblings like ask_pipeworx and discover_tools by positioning it as a first-step discovery tool.

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

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

Explicitly instructs to use this FIRST when the user does not know what Pipeworx can do, and mentions learning how to call meta-tools. Provides guidance on when to use with no arguments vs. passing a topic, and implicitly differentiates from direct query tools.

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

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

The description adds valuable behavioral detail beyond the annotations: the row is deactivated rather than deleted, and historical events remain available via recent_alerts. It also discloses ownership enforcement. This goes beyond the annotations' readOnly/destructive hints without contradicting them.

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

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

The description is two concise sentences, front-loaded with the primary action and immediately followed by key behavioral caveats. Every sentence adds meaningful information without redundancy.

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

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

For a simple, single-parameter mutation tool, the description covers the essential outcome (deactivation vs deletion) and future availability of data. It lacks an explicit success response format, but the absence of an output schema and the tool's simplicity make this acceptable.

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 full coverage (100%) for the single 'id' parameter, including that it is a UUID returned by subscribe. The description adds only the ownership constraint, which is contextual rather than parameter-specific, so it does not significantly augment the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation using a subscription id.

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

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

The description provides clear context: it requires a subscription id and enforces ownership, implying use after subscribing. It does not explicitly name alternatives like 'list_subscriptions', but the purpose is unmistakable and the ownership constraint clarifies appropriate use.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals detailed behavior: the two verification paths (SEC EDGAR structured vs. grounded pipeline), exact percent-delta math, the return structure (verdict, value with citation, reasoning), and that it replaces 4-6 sequential calls. This is substantial added 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?

Although the description is longer than typical, every sentence earns its place. It front-loads user intents and core purpose, then efficiently explains routing, outputs, and efficiency gains. For a tool with this complexity, it is appropriately sized and well-structured.

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

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

With no output schema, the description compensates by listing the possible verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported), mentions the pipeworx:// citation, and describes reasoning. The annotations cover safety and open-world aspects, and the tool has only 2 parameters, so the description is complete enough for an agent to use it correctly.

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

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

The input schema already covers both parameters fully (100% schema description coverage), with examples and constraints. The description does not add much parameter-specific meaning beyond what the schema provides, but it does reference 'exact percent-delta math' and 'tolerance implied by the claim wording,' which adds slight context. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with specific verbs: 'natural-language claim verification against authoritative sources.' It includes example user phrasings and distinguishes between financial claims (SEC EDGAR fast path) and other factual claims (grounded pipeline), making its scope unmistakable and distinct from sibling tools like general Q&A or research tools.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for financial vs. other claims. However, it does not name specific alternatives or state when not to use it, so it falls short of a 5.

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