Arcgis Dukescounty

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

Beyond the readOnlyHint annotation, the description discloses the default model (Workers AI Llama-3.3-70b), the BYO-key cost implication for Anthropic, and the response structure (per-model score/confidence/signals/raw_response plus combined view). These details add meaningful behavioral context without contradicting any annotations.

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

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

Three sentences with a clear topic sentence followed by operational details and use cases. No redundant phrasing; every sentence adds new 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 lacking an output schema, the description explicitly states the return shape (per-model fields + combined view), which covers the main missing piece. It also explains the free vs. paid model behavior, making the tool understandable for an agent with no additional 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%, so the baseline is 3. The description adds value by clarifying the relationship between `_apiKey` and the `models` parameter (Anthropic requires the key, and you pay directly), and by noting the default workers-ai model is free.

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 a specific verb ('Probe') and clearly states the resource ('one or more LLMs') and the outcome ('score visibility 0-100 per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on general brand/topic visibility across multiple models rather than competitor-specific analysis.

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

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

The description gives explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternative tools or say when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds rich context beyond that: it routes to 5,462 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and mentions tier availability and one-fast-call performance. This complements the annotations without contradiction.

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

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

The description is long but every sentence is purposeful. It front-loads the critical 'PREFER OVER WEB SEARCH' directive, then organizes domains, triggers, examples, and alternatives in a scannable way. No redundancy or fluff.

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

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

Given the tool's simplicity (one required parameter, no output schema) and strong annotations, the description fully covers purpose, usage, response format, and alternatives. It also addresses edge cases like breaking news and tier availability, making it complete for an agent's 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?

The schema has 100% description coverage for the question parameter and its aliases. The description adds value by scoping the acceptable questions (factual, real-world, current/historical data) and providing concrete examples, going beyond the schema's minimal definition.

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 ask_pipeworx as a question-routing tool for authoritative structured data with citations, using specific verbs like 'routes' and 'returns'. It distinguishes it from sibling tools by naming ask_pipeworx_grounded and deep_research and explaining their different purposes.

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 directives: 'PREFER OVER WEB SEARCH' for a comprehensive list of data types and 'START HERE for most questions'. It also provides concrete triggers ('what is', 'look up', etc.) and examples, and clearly states when to use alternatives (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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial experimental context: it may have candidate routing improvements live, currently none are active, and it is a full working router that falls back to nothing. This informs the agent of potential variability and current equivalence.

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

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

The description is compact yet information-dense, front-loading the beta relationship and covering current state, usage, and caveats in about four sentences 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 tool with one primary parameter and no output schema, the description provides adequate context: what it does, when to use, current state, and relationship to the stable router. It could explicitly mention that the stable router is ask_pipeworx, but that is implied by the context.

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

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

The input schema covers all 6 parameters with descriptions, including aliases, so schema coverage is 100%. The description's mention of 'same arguments' adds no new semantic detail 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 this as a beta version of ask_pipeworx, a universal router forwarding to 5,462 tools, and explicitly distinguishes it from the stable sibling. It states the specific purpose (routing questions with candidate improvements) and differentiates from ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains current behavior (no candidate active, so identical to stable) and notes results are compared against the stable router, giving clear context for usage.

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

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

The description goes well beyond the readOnly/idempotent annotations by detailing the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), enumerating refusal reason codes, and disclosing the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but each sentence earns its place: value proposition, mechanism, return format, use cases, and cost trade-off. It is front-loaded with the primary purpose and structured for quick parsing.

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

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

With no output schema, the description fully explains return values and failure modes, including specific refusal reasons. It also addresses cost and routing complexity, leaving no significant gaps for an agent to invoke correctly.

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

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

Schema coverage is 100% as all six parameters are aliases for 'question' with descriptions in the schema. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode that routes through the same pipeline as ask_pipeworx, fetches data, and extracts an answer using only the tool result. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and high-stakes use cases.

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

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

It explicitly says to use whenever answers will be quoted, cited, or acted on, and warns against using for casual lookups due to extra LLM cost, recommending ask_pipeworx instead. This provides clear when-to-use and when-not-to-use guidance with an alternative named.

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

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

The description goes far beyond the annotations (readOnly, idempotent, openWorld) by disclosing the resolver contract (match confidence, alternatives, suggestions), safety short-circuit behavior, closed/dead market status, wide-spread warnings, cancellation-rule risks, and news fallback behavior. This is rich, actionable 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 well-structured with section headers and examples, but it is very verbose, covering many edge cases and nuances. While each section adds value, the overall length makes it less concise than ideal, though the front-loading of purpose helps.

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

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

With no output schema, the description fully explains return values and behavior: result.market fields, result.analysis with edge/kelly calculations, result.evidence keying, parent_event extractor, news fallback fields, status codes, and resolution-rule risk. It is exhaustive for a complex tool.

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

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

The schema already has 100% coverage with clear descriptions and examples for all three parameters. The tool description reinforces the market parameter's flexibility but adds little new meaning beyond what the schema provides, so the baseline score applies.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the tool's scope and lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which distinguishes it from sibling tools like polymarket_edges or arbitrage.

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

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

It explicitly states when to use the tool with three direct example queries. However, it does not mention when not to use it or point to alternatives, so it stops short of full usage guidance.

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

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

The description provides rich behavioral details beyond the readOnlyHint and idempotentHint annotations: it specifies data sources (SEC EDGAR/XBRL, FAERS/FDA), handles off-calendar fiscal years, and explains output sorting and citation URIs. This gives the agent a clear mental model of what happens when the tool is invoked.

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 yet front-loaded with the core purpose and trigger phrases. Every sentence contributes information—data sources, sorting behavior, output format, and performance benefits—without redundancy. It earns its length.

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

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

For a comparison tool with two distinct types and no output schema, the description explains input constraints, data sources, output characteristics (paired data, citation URIs), and even performance implications. It gives the agent everything needed to use the tool appropriately and expect reasonable results.

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

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

Although schema coverage is 100%, the description adds substantial meaning to the 'type' parameter by enumerating exactly what metrics are pulled for company vs drug. It also enriches 'values' with concrete examples (['AAPL','MSFT'], ['ozempic','mounjaro']). This far exceeds the schema's basic descriptions.

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

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

The description states exactly what the tool does: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with explicit trigger phrases ('X vs Y', 'rank these companies'). It clearly distinguishes from siblings like entity_profile by positioning itself as the preferred comparison tool over 'sequential single-pack lookups'.

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

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

It provides strong usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives specific query examples. While it doesn't name an alternative tool, it clearly implies when to use (comparison queries) and what to avoid (sequential lookups). Slightly fewer explicit exclusions prevent a 5.

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

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

Annotations already declare readOnly/idempotent, and description adds extensive behavior: account/paywall requirements, parallel decomposition across 5,462 tools, findings packet fields (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[]/contradictions[], hop field, citation_uri resolvability, semantic excerpting, and expected latency 15-60s/~90s.

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

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

Long but front-loaded with the account caveat and core one-call value proposition; every subsequent sentence adds a distinct behavioral fact or alternative. No filler or tautology.

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

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

No output schema, but description fully specifies return packet structure and edge cases (gaps[], contradictions[], citation_uri only when fetchable). Includes timing, prerequisites, limitations (breaking news not covered), and explicit alternative paths, making it self-sufficient for invocation.

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

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

Schema coverage is 100%, so baseline 3; description adds value by reinforcing that question can be broad/multi-part and explaining how depth tiers behave in practice (e.g., standard gap recovery, thorough paid leads-chasing). It also notes depth:'thorough' requires a paid plan, which is not in schema.

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

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

The description states 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' with a specific verb and resource, and explicitly contrasts with ask_pipeworx for single lookups. It also clarifies what it is NOT ('this is NOT open-web search'), distinguishing it from siblings.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and gives concrete examples. It names alternatives directly: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', plus account-tier fallback.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond these: it returns top-N most relevant tools with names, descriptions, and full input schemas, and states results are ready to call directly with no second lookup needed. This clarifies the output format and immediate usability, which 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 three sentences, front-loaded with the core purpose, and every sentence adds value: what it does, when to use, and what it returns. No wasteful filler or repetition of 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?

Given the tool's moderate complexity (6 params, mostly aliases, no output schema), the description covers the essential aspects: it explains the return value (top-N tools with schemas and examples), the use case, and the distinctive feature of being callable directly. It is complete for an agent to decide when to invoke this 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%: every parameter including aliases has a description. The description reinforces that 'query' is a natural language description and gives example domains, but it does not add essential information beyond what the schema already provides. The domain list is helpful for forming queries but not critical for understanding parameter syntax.

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

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

The description clearly states that the tool finds tools by describing a data or task, with a specific verb ('Find tools') and resource (available tools). It also lists domains like SEC filings, financials, FDA drugs, etc., which distinguishes it from siblings that may search data directly. This makes the purpose unmistakable.

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

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

The description gives explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. It does not name alternatives or give when-not scenarios, but the context is clear and practical.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses real behavior: one parallel fan-out, return fields with up to 5 filings and pipeworx URIs, fundamentals sorted by period_end DESC, PatentsView sunset soft-fail, and GDELT→GNews fallback. No contradiction with annotations.

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

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

The description is long but information-dense and front-loaded with trigger examples. Each clause adds behavioral or usage context; the many example queries are somewhat redundant but do help the agent recognize when to invoke the tool.

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

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

Given there is no output schema, the description fully specifies what will be returned (cik/company_name, recent_filings, fundamentals, patents, news, LEI) and covers failure modes (Patents API sunset, name resolution, fallback chain). It leaves little ambiguity about inputs, outputs, or edge cases.

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 schema already documents type/value, ticker/CIK examples, and the no-names rule. The description mostly repeats these constraints rather than adding new parameter-level meaning beyond user phrasing examples.

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

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

Description clearly identifies the action as building a full cross-source profile of a US public company in one parallel call, with specific resources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes from sibling chaining by explicitly preferring this tool for holistic company lookup and points to resolve_entity as the alternative when only a name is available.

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 trigger examples ("Tell me about X", "brief me on Tesla") and states a clear preference over chaining single-pack lookups. It also gives a concrete exclusion: names are not supported and directs users to resolve_entity first, which is strong when-to-use/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, so the description doesn't need to repeat that. It adds context about clearing sensitive data, but does not disclose behavior for missing keys or return values. Since annotations cover safety, a 3 is appropriate.

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

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

Two concise sentences deliver purpose and usage guidance. No wasted words, front-loaded with the primary 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 one-parameter delete tool, the description covers purpose, usage timing, and relationship to siblings. The lack of return value details is minor for a delete operation; overall complete enough.

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

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

Schema has 100% coverage: the 'key' parameter is described as 'Memory key to delete.' The description mentions 'by key' but adds no extra syntax or format details beyond the schema. Baseline 3 is warranted.

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 resource 'previously stored memory by key.' It unambiguously distinguishes from sibling tools 'remember' and 'recall' by specifying deletion.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, clarifying its role among siblings.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by explaining that it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' and that the output is a single text blob. This 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 concise (three sentences), front-loaded with the key purpose, then explains behavior and usage. Every sentence earns its place with no redundancy. The use of bullet-like 'Useful for' list is effective.

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

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

The description explains the output format and highlights the use cases, which is sufficient given the simple parameter set and rich annotations. It does not cover edge cases (e.g., invalid URLs or network errors), but for a read-only, idempotent tool with clear output, this is acceptable and nearly 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 covers 100% of parameter descriptions, so the description adds little beyond the schema. It mentions 'link entries' which relates to max_links, but does not explain defaults or limits beyond what the schema already provides. The schema itself is sufficient.

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 a specific verb ('Generate') and resource ('llms.txt file for any URL'). It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on producing the actual llms.txt file rather than merely assessing visibility.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), which gives clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by detailing the exact returned schema components (fields, geometry type, record count, capabilities), which clarifies what the tool delivers without contradicting annotations.

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

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

The description is a single, well-structured sentence that front-loads the verb and resource, then lists specific outputs. No redundant words or filler.

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

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

For a simple metadata retrieval tool with one well-documented parameter, strong annotations, and no output schema, this description is fully adequate. It tells the user what they will get (schema details) 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 input schema fully covers the single required parameter (url) with a description and example, so baseline of 3 applies. The tool description adds no parameter-specific meaning 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 gets an ArcGIS Feature/Map Service layer's schema by URL, enumerating specific outputs (fields, geometry type, record count, capabilities). This specific verb+resource combination distinguishes it from sibling tools like query_layer.

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

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

The description implies when to use the tool (when you need layer schema metadata) but does not explicitly mention alternatives or exclusions. Context is clear enough for selection.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description's 'List' action is consistent. The description adds value by disclosing the exact return fields (id, type, params, etc.) and scoping to the caller's active subscriptions. No contradiction with annotations.

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

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

The description is two sentences with no redundant information. It front-loads the action and return values, making it highly concise and effective.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete. It specifies what is returned, the default scope (active), and a practical use case.

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

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

The input schema fully documents the single parameter include_inactive with a description, achieving 100% coverage. The tool description does not add additional parameter semantics, so the baseline score of 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes it from sibling tools like subscribe/unsubscribe by focusing on review. It also enumerates return fields, reinforcing the list purpose.

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

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

It provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool, but it doesn't mention alternatives or exclusions beyond that.

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

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

The description discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a `claim_token`'), and the team's daily digest process ('The team reads digests daily and signal directly affects roadmap'). These behaviors go beyond the neutral annotations and paint a complete picture of side effects.

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 purpose, then provides usage, exclusions, token behavior, and operational details in a logical sequence. Every sentence adds meaningful guidance, making it appropriately sized for the tool's complexity.

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

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

The description covers the tool's purpose, usage, exclusions, claim-token tracking, rate limits, and team processing. With no output schema, it clarifies return behavior via claim_token. It is complete enough for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: it explains the claim_token workflow conditionally ('Filing without an account returns a `claim_token`') and advises against pasting end-user prompts ('don't paste the end-user's prompt'), which refines the message parameter usage.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by specifying it's for feedback specifically about Pipeworx tools and excludes tools from other MCP servers.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states exclusions and alternatives: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.'

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

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

Beyond the annotations (readOnlyHint=true, etc.), the description adds valuable behavioral context: it explains the data source ('derived from CF analytics-engine'), privacy ('no PII'), output format ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This fully discloses operational characteristics.

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 and front-loaded: the first sentence states the core purpose, followed by return details and a numbered list of use cases. While the numbered list adds length, each item is purposeful and helps the agent decide when to use the tool. It is slightly verbose but not wasteful.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains the input window choices, return contents (top tools, packs, call volume), use cases, data provenance, privacy, and caching. There are no significant gaps; an agent could invoke it correctly without further clarification.

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

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

The schema already provides 100% coverage for the single 'window' parameter, including enum values and semantic guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description adds only minor extra context about caching varying by window, so baseline 3 is appropriate given the schema's completeness.

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

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

The description clearly states the tool's function with a specific verb and resource: 'What other AI agents are calling on Pipeworx right now' and then details output ('top tools, top packs, and total call volume'). It distinguishes itself from siblings like discover_tools by emphasizing real-time aggregated usage trends rather than static tool listings.

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: 1, 2, 3'), giving clear context on when to use the tool. However, it does not mention alternatives or explicitly state when NOT to use it, so it falls short of the highest bar requiring exclusions/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?

Although annotations already declare readOnlyHint=true and destructiveHint=false, the description adds rich behavioral detail beyond that: it discloses internal checks (partition_check summing YES prices, semantic anchor Jaccard similarity, placeholder filtering), explains the fill_check against live CLOB depth, and warns that realizable_edge_pp <= 0 means 'do not trade it.' This level of transparency 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 ~350 words, which is long, but it is well-structured with uppercase headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with a clear purpose sentence. Each section provides unique, non-redundant details, though the length is close to the upper bound of appropriate for a tool description.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It explicitly details the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases like thin_legs and skipped_low_similarity, making it self-sufficient for an agent.

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

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

Schema coverage is 100% and both parameters already have descriptions, but the tool description adds substantial value: concrete examples of event slugs ('fed-decision-may-2026'), acceptance of full Polymarket URLs, and detailed behavioral differences between event and topic modes (walks child markets vs flattening related events). This exceeds the baseline for full 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 opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which is a specific verb+resource+method. It clearly distinguishes this from sibling tools like polymarket_edges (likely predefined edges) and polymarket_fill_risk (sizing). The two-mode design (event/topic) further clarifies what the tool accomplishes.

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 mode-specific guidance: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also explicitly directs users to a sibling tool: 'For custom sizing use polymarket_fill_risk.' However, it does not explicitly compare against other scanning tools like polymarket_edges or polymarket_kalshi_spread, leaving some usage boundaries implicit.

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. Beyond that, the description adds valuable behavioral context: caching at KV level for 1 hour keyed on knobs, 'rare-by-design' for concentrated longshots, a 24h-move warning that the edge may already be priced, and _diagnostics to explain why segments are empty. It also discloses the unreliability of the Fed signal without paid data.

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

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

The description is dense but well-structured with capitalized segment labels and parenthetical details. It is front-loaded with purpose and then methodically covers models, response shape, knobs, and diagnostics. However, it is quite long (300+ words) and could overwhelm some agents; a slightly more condensed structure would improve scannability.

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

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

With no output schema, the description must explain return values, and it does thoroughly: top-level by_segment structure, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), diagnostics funnel counters, and even the fed_candidates/fed_note. It also covers caching, model details, and gate relaxations, making it complete for a complex tool.

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

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

Schema coverage is 100%, so parameters are documented well. The description goes further: for slippage_pp it gives concrete market context (zero fees but 20-50bp hits) and guidance to adjust; it explains why min_kelly doesn't filter partitions and introduces min_partition_leg_kelly; and it clarifies 'NET of slippage' for edge. These are practical semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage (cross-market arbitrage) and polymarket_edge_tracker (edge monitoring), and the added 'what should I bet on today' frames the intent sharply.

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 ('Built for ... discover opportunities without paging hundreds of markets') and detailed knob guidance (e.g., min_liquidity, max_spread_pp, min_partition_leg_kelly). However, it does not explicitly state when to prefer this over specific siblings or when not to use it, so it lacks exclusions or named alternatives.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description reveals key behaviors: history depth bounded by a 60-day snapshot TTL, snapshots written only on cache-miss so gaps mean days with no scans, and decay computed from daily closes rather than intraday. This is substantial additional 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 lengthy but well-structured into Args, RESPONSE, and LIMITS sections. It front-loads the core purpose and every sentence contains actionable information without redundancy. The length is justified by the complexity of the tool's output and constraints.

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

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

Given there is no output schema, the description thoroughly explains the full response format: tracked[] with fields like edge_pp_net time-series, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[] with explanation of gaps. It also discloses limitations on history depth and calculation method, providing a complete picture for correct use.

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

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

Schema coverage is 100% with clear parameter descriptions. The description restates the parameters ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') but does not add new semantic meaning beyond the schema. It meets the baseline but does not exceed it.

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

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

The description clearly states it is 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This explicitly distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge detection.

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 contextual guidance: 'a fresh wide edge and a 3-week-old wide edge are different trades' and 'the median lifespan is your competition clock'. This implies using the tool for time-sensitive edge analysis, but it does not explicitly name alternative tools or state when not to use it, so it falls short of a full 5.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: it walks the book ladder, returns top_of_book/vwap_fill_price/slippage_pp, identifies thin legs, and names forced_directional_risk. There is no contradiction with annotations.

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

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

The description is long but every sentence earns its place given the tool's dual-mode complexity. It is front-loaded with the core purpose and uses clear SINGLE-MARKET/BASKET structure, making dense information scannable.

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

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

For a tool with no output schema, the description lists the key return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, thin_legs, etc.) and covers input constraints, defaults, and the dominant failure mode. It is complete for the tool's complexity.

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

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

Although schema coverage is 100%, the description enriches meaning by explaining single-market vs basket modes, side defaults, size interpretation as spend vs target proceeds, and basket settlement notional. This goes well beyond the schema's basic property descriptions.

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

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

The opening phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' names a specific verb and resource, and clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges. It also explicitly states it should be used before those tools.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why, citing untappable theoretical overround and the risk of partial basket fills creating unhedged directional positions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral context: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment impact, and the skipped_cross_type/subtype counters. It also cautions that most pre-mapped topics return warnings today, setting accurate expectations. 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 lengthy but well-organized with uppercase section labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries substantive information, including caveats and edge cases. It is not as concise as the two-sentence TDQS 4.3 example, but the complexity of the tool justifies the length.

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

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

For a 3-parameter tool with no output schema, the description thoroughly explains what the response contains (leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_* counters). It also covers edge cases and limitations, making the tool self-contained. Despite no output schema, the description compensates fully.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains how 'topic' auto-fetches from a pre-mapped list, and how explicit kalshi_event_ticker/polymarket_event_slug override the mapped side. It provides concrete examples and clarifies the relationship between parameters. This is above baseline but not extremely deep.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by focusing on the cross-venue comparison and the delta between participant pools. The two modes (topic shortcuts and explicit tickers) are explicitly stated.

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

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

The description explicitly explains two usage modes and when to use each. It also provides exclusion guidance: when bet shapes are non-equivalent (compatibility_warning), the spread is not a real signal, and it warns that pre-mapped topics are not necessarily tradeable. This is explicit 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by noting it returns 'attribute rows (and geometry)' and uses SQL-like where clause and pagination, which goes beyond the annotations. No contradiction.

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

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

Two sentences, front-loaded with the primary action, followed by parameter summary and return type. No wasted words.

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

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

With no output schema, the description explains the return format (attribute rows and geometry) and provides a usage tip. It covers the core workflow (use with search_datasets, sampling) and relies on schema for param details. Adequate, though it could mention error handling or service format constraints.

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 repeats parameter names (where, out_fields, order_by, limit, offset) but doesn't add new syntax details beyond the schema. The sampling tip is a small value-add, so score remains at 3.

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

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

The description explicitly states 'Query an ArcGIS Feature Service / Map Service layer by its url' with a specific verb and resource. It distinguishes from sibling tools like search_datasets by noting the URL comes from search_datasets, and from layer_info by indicating it returns attribute rows and geometry.

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

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

The description provides clear context: the tool is for querying a specific layer URL obtained from search_datasets. It includes a practical sampling tip ('where="1=1" + out_fields="*"'), but does not explicitly mention when not to use it or alternatives beyond the implicit distinction from search_datasets.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about data scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior when the key argument is omitted. This enriches the agent's understanding 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 concise, front-loaded with the core action, and every sentence earns its place. It covers purpose, scope, and relationship to other tools in three sentences without redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the operation modes, data scope, and related tools. It does not describe the return format, but the main behaviors (returning a saved value or listing all keys) are clear from the description. The presence of strong annotations reduces the burden, making this mostly complete.

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

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

Schema coverage is 100% and the parameter description already states 'Memory key to retrieve (omit to list all keys)'. The tool description mirrors this and adds use-case examples but does not introduce new parameter-level details. Since the schema does the heavy lifting, a baseline score of 3 is appropriate; the description does not significantly enhance parameter understanding.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes the tool from siblings by naming 'remember' and 'forget' as complementary operations, and provides concrete example use cases (ticker, address, research notes) that make the purpose immediately understandable.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also points to alternatives: 'Pair with remember to save, forget to delete.' This gives clear context and names related tools, though it does not formally state 'when not to use' beyond that.

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, lowering the bar. The description adds valuable behavioral context by explaining that mark_read:true flags events as read and affects subsequent calls, plus noting the feed is persisted and includes citation_uri. This goes beyond what annotations state.

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

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

The description is three tight sentences: states the core action, lists key return fields and filters, then gives a poll-ability note and an alternative access point. Every sentence earns its place, with no filler 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?

With no output schema, the description appropriately describes return payload components. It covers the main parameters, mark_read side effects, and even provides an external endpoint for automation. Given the moderate complexity (5 optional params, persisted feed), this is fully complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful elaboration: it gives a concrete example type ("sec_8k"), explains mark_read's side effect, and clarifies the since parameter as an ISO timestamp. This exceeds the schema descriptions without becoming 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 states the tool pulls fired events from the subscription feed, with a specific verb ('Pull') and resource ('fired events from your subscription feed'). It also describes the return payload (source, citation_uri, raw event payload), distinguishing it from siblings like list_subscriptions which manage subscriptions themselves.

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

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

The description gives clear context: it is for reading alerts, supports polling, and mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses significant behavioral traits: multi-source fan-out, GDELT→GNews fallback triggers, USPTO soft-fail due to API sunset, and the return structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). This adds substantial context not present in annotations.

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

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

The description is dense but well-organized. It front-loads example queries, then defines the core behavior, lists sources, explains fallback logic, and closes with an alternative tool. Every sentence contributes necessary context, with no redundancy or filler.

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

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

There is no output schema, so the description takes on the burden of explaining return values—it does so clearly (structured changes[] grouped by source, total_changes count, citation URIs). Combined with the detailed source and fallback behavior, the description fully covers the tool's operational context.

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

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

Schema coverage is 100%, so the schema already documents all three parameters (type, since, value). The description only reiterates the `since` format and examples already in the schema, without adding new meaning. Per the rubric, the baseline is 3 when schema coverage is high, and the description does not elevate it.

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

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

The description clearly states the tool's function: 'change feed for a company in the last N days/weeks/months'. It uses concrete example queries and explicitly lists the data sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes itself from the sibling tool entity_profile by noting its focus on dynamic changes rather than static profiles.

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 entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also gives natural language examples of appropriate queries and explains fallback behavior (GDELT preferred, GNews on rate limit/5xx), making the tool's intended use clear.

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

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

Annotations already declare idempotent=true and destructive=false. The description adds persistence semantics (authenticated users persistent vs anonymous 24-hour sessions) and scoping by identifier, which are behavioral traits beyond what annotations convey. No contradiction.

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

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

Four dense sentences, front-loaded with the primary action. Each sentence adds distinct value—use case, storage format, retention policy, companion tools—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 two-parameter tool with no output schema, the description covers purpose, usage, persistence, and companions. It fully equips an agent to invoke it correctly.

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

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

Schema covers both parameters fully (100%), so the description doesn't need to elaborate. It adds general key-value framing and identifier scoping, but no parameter-specific syntax beyond 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?

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It distinguishes the tool from siblings by naming recall and forget, and clarifies the key-value scope and cross-session persistence.

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

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

It explicitly says 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address). It also says to pair with recall and forget, giving clear alternative and companion tool guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally' and notes auto-disambiguation and citation URIs. This goes beyond annotations, though it omits potential failure modes or rate limits.

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

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

Despite being lengthy, it is densely informative and well-structured: example queries, purpose, usage rule, type-specific details with citation URIs, and a cost note. Every sentence earns its place, and formatting like 'SUPPORTED TYPES' aids scannability.

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

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

For a tool with two entity types, multiple input formats, and no output schema, the description covers inputs, outputs, citation schemes, auto-disambiguation, and cascading behavior. It leaves no obvious gaps for an agent deciding whether and how to call it.

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

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

Schema coverage is 100%, but the description enriches the 'value' parameter with concrete formats: for company 'ticker (AAPL), CIK (0000320193), or name' and for drug 'brand or generic name.' It also clarifies return fields (ticker + CIK + company_name, RxCUI + ingredient + brand), adding meaning beyond the raw 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 concrete query examples then states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This clearly identifies the verb (resolve), resource (name-to-ID), and purpose. It distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID' and listing supported types accordingly.

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

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

Provides explicit when-to-use: 'Use FIRST whenever you have a name but need an ID.' It explains that it replaces 2-3 manual lookups, giving contextual benefit. However, it does not explicitly state when not to use it or name alternative tools like entity_profile, so it falls short of a 5.

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

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

The annotations already declare readOnly, openWorld, and idempotent hints, so the description doesn't need to restate safety. It adds valuable behavioral context by explaining that it 'probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density per entity.' It also hints at the subject/competitor ordering, which improves transparency beyond the schema.

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

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

The description is efficiently front-loaded with the primary action and purpose in the first sentence. The second sentence provides use case and return value. Every sentence earns its place with no redundancy or fluff.

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

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

Despite having no output schema, the description explicitly states the return format (ranked list with score, confidence, signal density) and explains the practical application. Combined with the presence of annotations for safety and idempotency, the description fully equips an agent to understand when and how to use the tool.

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

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

Schema coverage is 100% as all four parameters have descriptions. The description adds semantic meaning by clarifying that entities represent 'your brand + N competitors' and that the first entity is treated as the subject, which is not fully captured in the schema. This enhances the parameter understanding beyond the baseline.

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

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

The description clearly states a specific action and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison and mentions ranking and output highlights, making its unique purpose obvious.

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

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

The description provides clear context by stating it is 'useful for competitive AI-marketing audits' and references ai_visibility_check as the underlying probe. It does not explicitly exclude when to use alternatives like ai_visibility_check for single entities, but the multi-entity focus implicitly guides selection. This is clear context without formal exclusions, meriting a 4.

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

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

Beyond the read-only, idempotent, and non-destructive annotations, the description discloses key behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the sources_failed field handles timeouts. This gives the agent crucial runtime expectations.

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

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

The description is a single dense paragraph with clear flow: purpose, usage trigger, return summary, ecosystem caveat, and failure behavior. Every sentence adds essential context, though it is slightly long due to the output field enumeration.

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

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

With no output schema present, the description compensates by fully enumerating the return fields, explaining partial failure semantics, listing ecosystem limitations, and detailing timing behavior. It provides a complete picture of the tool's behavior and expected response.

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 both parameters, with the schema already explaining the package name and version default behavior. The description adds context about output fields that depend on the parameters, but adds little new parameter-level meaning beyond what the schema provides.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, enumerating specific data sources (deps.dev, bundlephobia) and output fields. It distinguishes itself from siblings by focusing on npm package evaluation, with explicit 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?

Explicitly says 'Use whenever an agent asks...' and provides example queries. It also gives a clear alternative for non-NPM ecosystems ('fall under deps.dev:version directly'), guiding the agent away from this tool in those cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail about the response shape (name, summary, record_count, owner/org, url) and mentions open datasets, which communicates public availability. No contradictions.

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

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

Two sentences: first defines the action and scope, second details the return and downstream use. No redundant wording or unnecessary 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?

With no output schema, the description explains the return fields and how to use the URL with query_layer/layer_info. The optional params are well-described in the schema, so the description is sufficient for a simple 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?

Input schema covers all 3 parameters with descriptions, including defaults (limit=20, org override). The description does not add parameter-specific details beyond the schema, but provides domain context ('Dukes County GIS', 'geospatial') that helps interpret the query and org_id. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool searches Dukes County GIS open geospatial datasets by keyword, listing example dataset types (parcels, addresses, zoning) and specifying return fields. This distinguishes it from sibling tools like query_layer and layer_info, which operate on a specific layer's features.

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

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

Provides a clear usage context: use to discover datasets and obtain their Feature Service URLs. The instruction to pass the URL to query_layer/layer_info implies next steps and when this tool is appropriate, but lacks explicit when-not-to-use guidance or alternative tool suggestions.

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

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

The description discloses key behaviors beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and truncates inputs over 200K chars with a flag. Annotations (readOnly, openWorld, idempotent, non-destructive) are consistent and no contradiction exists.

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

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

The description is information-dense but well-structured, front-loading the core purpose, then usage context, then technical details. It is a bit long, but every sentence adds value without redundancy.

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

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

Given the absence of an output schema, the description adequately covers return values (passages, offsets, similarity scores), usage context, technical implementation, limits, and how it pairs with other tools. It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% with each parameter described clearly. The description adds extra meaning by explaining that 'limit' corresponds to top-N passages, 'text' is the document to search, and 'query' takes natural-language examples. It also mentions character offsets and similarity scores, which enriches parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: semantic search inside a fetched record. It gives specific examples (SEC 10-K, article) and differentiates from siblings by emphasizing 'INSIDE' a record and by referencing ask_pipeworx_grounded as a companion, making the purpose unmistakable.

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

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

Explicit guidance is provided: use when a record is too large to fit in the prompt, and pair with ask_pipeworx_grounded to ground over relevant passages. This clearly states when to use the tool and mentions an alternative workflow.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the OAuth requirement, the always-on feed with retrieval method, SMS verification and daily cap, webhook signing process, and auto-disable after 10 failures. This is extensive behavioral detail.

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

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

The description is a single dense paragraph with a lot of detail. It is front-loaded with the core purpose, but the length and lack of bullet points reduce scannability. Each sentence adds value, though the structure could be improved.

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 nested parameters and no output schema, the description covers prerequisites, supported types, delivery options, limits, and webhook mechanics. It is sufficiently complete for an agent to use 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 schema already has 100% coverage with detailed type-specific parameter examples and delivery channel descriptions. The description largely restates this information, adding only minor context like the meaning of item codes. Since the schema does the heavy lifting, 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. This specific verb+resource distinguishes it from sibling tools like unsubscribe and list_subscriptions.

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

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

The description explains prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist subscriptions) and details supported subscription types and delivery channels. While it doesn't explicitly state when not to use it, the context strongly implies it for creating subscriptions vs. listing/unsubscribing.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds context about what the tool actually does: it returns category-bucketed example questions sourced from a live catalog, and that each example includes the exact tool and argument shape. This is valuable behavioral detail 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 a single dense paragraph that front-loads example queries and efficiently packs in the tool's purpose, output format, call patterns, and when to use it. Every sentence contributes value; no filler or redundancy.

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

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

For a tool with one optional parameter and no output schema, the description fully explains the return value (category-bucketed examples with tool+argument shapes), the calling convention (no args or with topic), and the recommended usage scenario. It also lists the categories. This makes the tool self-sufficient.

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

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

Schema coverage is 100% (the `topic` parameter has a description), but the tool description adds meaningful context: it lists concrete examples ('finance', 'pharma', 'betting') and explains that omitting the argument yields a full spread. This enriches the schema's enum-like list.

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: 'the onboarding entry point' that 'Returns category-bucketed example questions' with each tool and argument shape. It lists specific categories (company financials, drugs, etc.) and distinguishes itself from siblings like ask_pipeworx by explaining it teaches how to call those meta-tools.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools'. It also explains call variations (no arguments vs. with topic) and gives examples of topic values. This clearly positions it relative to alternatives.

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

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

Discloses important behavioral traits beyond annotations: ownership enforcement, row deactivation rather than deletion, and preservation of historical events via recent_alerts. This adds substantial context that the annotations (non-destructive, idempotent) do not fully capture.

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

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

Three sentences, each earning its place: core action, ownership restriction, and deactivation semantics. No redundancy or unnecessary detail.

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 no output schema, the description fully covers the tool's purpose, constraints, and downstream effects. An agent has enough information to know when to invoke it and what will happen.

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 the id parameter with 100% coverage, describing it as 'Subscription id (uuid) returned by subscribe.' The description only repeats 'by id' without adding new semantic detail, so baseline score of 3 applies.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from siblings by noting ownership enforcement and deactivation behavior, which are unique to unsubscribe compared to subscribe or list_subscriptions.

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

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

Provides clear context on when to use by explaining ownership restriction and the consequence that historical events remain available via recent_alerts. However, it does not explicitly name alternative tools or state when not to use this tool, though the context is sufficient for a straightforward action.

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

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

Annotations provide readOnly/idempotent context, and description adds significant behavioral detail: automatic routing between SEC EDGAR/XBRL and a grounded pipeline, tolerance semantics, and verdict categories. It discloses that the tool returns citations and reasoning, which 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?

Description is a single dense paragraph but well-organized, starting with trigger phrases and ending with return value and benefit. It is longer than strictly necessary but every sentence contributes important routing, return, or usage 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?

With no output schema, the description enumerates the exact verdict types, includes actual value with citation, and mentions reasoning. It covers both financial and non-financial claim paths and tolerance override. Minor ambiguity remains about how citations are formatted for the structured SEC path versus the grounded path.

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

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

Schema already covers both parameters (100% coverage). Description adds value beyond schema: claim examples clarify expected phrasing, and tolerance_pct is given practical usage guidance ("set 1–2 for hallucination detection") plus note on default behavior caps.

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 states a specific verb and resource: "natural-language claim verification against authoritative sources." It distinguishes itself from siblings by focusing on fact-checking claims with explicit verdicts, unlike 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?

Explicitly states when to use: "Use whenever the agent needs to check whether something a user said is factually correct." It also clarifies routing between SEC/financial and other claims, but does not explicitly mention when NOT to use it or name specific alternative sibling tools.

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