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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes to one of 5,801 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond annotations and provides insight into execution behavior 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 front-loaded with the key 'PREFER OVER WEB SEARCH' directive and clear usage conditions. Every sentence serves a purpose: examples, alternatives, and when to use each. It is structured with bolded keywords and logical flow, making it efficient despite 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 tool with this complexity (routing to thousands of sources), the description covers when to use it, how it behaves, what output to expect (structured with citations), and distinguishes from siblings. Since there is no output schema, the description adequately fills that gap by describing the return format. Nothing critical is missing.

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

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

Schema coverage is 100% and the schema already describes the question parameter with aliases. The description does not add additional parameter-level detail, but the baseline of 3 is appropriate because the schema fully documents the parameter. The description's examples illustrate usage but don't reveal new semantics.

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

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

The description clearly states the tool routes questions to appropriate tools and returns structured answers with citations. It differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases, so an agent knows exactly what this tool does and what it doesn't.

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 instructs to prefer this over web search for factual questions, provides trigger phrases ('what is', 'look up', etc.) and concrete examples. It also specifies when to step up to alternatives ('for a hallucination-resistant single answer...', 'for a broad/multi-part question...'), leaving no ambiguity about selection.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds genuinely useful context beyond those: that behavior may vary when a routing candidate is under test, that no candidate is currently active (so it currently matches ask_pipeworx exactly), and that results are compared against the stable router to decide merges. It also clarifies it does not fall back to anything else — it is a full working router. This is real added value over 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 key facts are front-loaded (beta of ask_pipeworx, identical router). However, the description is somewhat wordy — it repeats the 'identical' point several ways and explains the fallback in two different phrasings. A slightly tighter version would earn the same clarity with less text. Not bloated, but not maximally lean.

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 is a complex universal router with no output schema, the description covers what matters: the beta nature, the current no-candidate state, how results are used, and that the response shape matches ask_pipeworx. An agent can decide whether to call it and what to expect. The only missing piece is naming the specific current routing candidate state, but that is inherently volatile and the description handles it correctly by saying none is active now.

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% — all 6 parameters (question plus 5 aliases) are documented in the schema itself. The description adds no parameter-level detail beyond that, which is acceptable since the schema fully carries this burden. Baseline 3 is correct.

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

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

The description states a specific purpose: it is the beta version of ask_pipeworx, an identical universal router with the same 5,801 tools, arguments, and response shape, differing only by experimental routing improvements. It explicitly distinguishes itself from its sibling ask_pipeworx and from ask_pipeworx_grounded by framing itself as the 'experimental edge.' No ambiguity about what it is.

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 it 'exactly like ask_pipeworx when you want the newest routing,' giving clear when-to-use guidance. It doesn't state when to prefer the stable ask_pipeworx instead (e.g., for production/reliability-critical calls), so the when-not side is only implicit — a small gap but not misleading.

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, idempotentHint, etc.), the description discloses the extra LLM call cost, the routing mechanism, and the full refusal reason taxonomy (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). No contradiction with annotations; it adds rich behavioral context that annotations cannot 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?

The description is moderately long but every sentence carries value: purpose, mechanism, return format, usage guidance, and cost trade-off. It is front-loaded with the key selling point (hallucination-resistant) and structured logically. 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?

Given the absence of an output schema, the description fully explains the return structure and refusal cases. It covers the routing behavior, the data-fetching steps, and the explicit use-case boundaries. An agent has all necessary information to decide when to call it and interpret results.

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

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

The schema already documents all six parameters as aliases for the question string, with 100% coverage. The description adds no new semantic information about the parameter beyond what the schema states, so the baseline of 3 applies. It doesn't clarify which alias to prefer, but the schema already says they are interchangeable.

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

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

The description states a specific verb (ask/extract) and resource (Pipeworx data across 5,801 tools/1,517 sources), and clearly distinguishes itself from ask_pipeworx by the grounded extraction mechanism. It also defines the exact success and refusal return shapes, making its purpose unambiguous.

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

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

Explicitly states when to use it ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'), directly naming the alternative. This gives clear decision criteria for the agent.

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

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

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 readOnlyHint/openWorldHint/idempotentHint/destructiveHint, and the description adds substantial behavior beyond them: the 15-60s (up to ~90s thorough) latency, the account/paid-plan requirement, gap-recovery and lead-chasing hops per depth, contradictions[] scans, semantic excerpting ('not head-truncated'), and the conditional presence of citation_uri ('present only when the source emits one that resources/read can actually serve'). No contradiction with annotations; the description meaningfully extends them.

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

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

The description is long (roughly 250+ words), but it is densely packed and every sentence earns its place given the tool's orchestration complexity — no filler or repetition. It front-loads the account gate (critical before any call) and the core 'not open-web search' disambiguation early. It could be tightened slightly, but the length is justified by the behavior it must disclose.

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 multi-tool orchestrator with three depth modes and no output schema, this is remarkably complete: it covers auth/account prerequisites, latency, the return packet (verbatim evidence + confidence + source + fetched_at + citation + gaps[]), edge cases (breaking-news topics yielding empty gaps[]), iteration semantics per depth, contradiction detection, and excerpt behavior. Nothing an agent needs to invoke it correctly or interpret results is missing.

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

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

Schema coverage is 100%, so both parameters are already documented — baseline 3 applies. The description adds real value on top: it explains depth semantics (quick=3 single hop, standard=3 with gap-recovery + contradictions, thorough=6 paid iterative hop) and ties the paid-plan gate to the 'thorough' enum value, which the schema does not convey. It stops short of example values for question, but the schema already carries that.

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

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

States a specific, compound action — 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call' — with a precise verb/resource and an explicit negative ('this is NOT open-web search'). It names the decomposition-and-parallel-routing mechanism and the findings packet it returns, and it clearly distinguishes itself from siblings (ask_pipeworx, bet_research, compare_entities). An agent can tell exactly what this does and what it is not.

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 routes the agent across alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx — it routes to live news APIs', plus the account gate ('If you are not signed in, use ask_pipeworx instead'). It also gives a concrete fit example ('compare X and Y's regulatory + financial exposure'). When/when-not and the exact alternative are all stated — nothing left to inference.

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/idempotent/openWorld hints, it discloses the fan-out across multiple data sources, soft-fail behavior for the USPTO API, that empty sections mean real absence of data, private company handling, and how sources_used/sources_failed behave. This is unusually thorough and does not contradict 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?

Long but justified for a multi-source profile tool; every block adds substance (return fields, edge cases, failure semantics). It is slightly rambling and repeats some input-shape detail from the schema, but the front-loaded trigger examples and preference rule give it usable structure.

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 carries the return-value burden: it enumerates every section of the profile, explains edge cases (private company, empty FDA section, patents API sunset), and clarifies sources_used/sources_failed. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description still adds examples for ticker, CIK, and company name, explains that type values are interchangeable, and clarifies that names resolve via SEC EDGAR. It also explains the resolved:false/notes behavior for private companies, going well 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 names a specific verb and resource: a full cross-source profile of a US public company. It provides concrete trigger examples and explicitly differentiates from chaining single-pack lookups, so an agent can tell what this tool is for.

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 lists clear trigger phrasing ('tell me about X', 'research Acme', 'brief me on Tesla') and states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' That gives an explicit when and the alternative to avoid.

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 mark this as read-only, idempotent, non-destructive, and open-world; the description adds substantial behavioral depth beyond that. It discloses safety fields, compatibility codes, null semantics for temporal_alignment, that unknown legs are never paired, the gross-vs-net fee caveat, and that pairing is keyword-based rather than source-verified. No statement contradicts 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 long, but it is structured into modes, response, safety fields, code explanations, and caveats, with the core purpose front-loaded. Each block adds necessary context, though the opening color about participant pools could be trimmed without losing essential agent guidance.

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

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

Given the tool has no output schema, the description does an unusually complete job of explaining what the response contains, how to read safety flags, which comparisons are skipped, when null values appear, and what caveats apply. An agent has enough information to call the tool correctly and interpret results without additional documentation.

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

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

Schema coverage is 100%, but the description still adds meaning beyond the schema by explaining the two modes, the exact topic shortcut list, and how kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. It also clarifies that both modes run the identical token-overlap matcher, which affects how the parameters should be interpreted.

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

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

The first sentence names a specific verb and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates from siblings by emphasizing cross-venue and naming both venues, plus the two modes (topic shortcuts and explicit tickers) make the function unambiguous.

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

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

The description gives concrete guidance on when to use each of the two modes, including the pre-mapped topic list and how explicit tickers override it. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped does not equal tradeable. It does not explicitly name sibling alternatives such as polymarket_arbitrage or polymarket_edges, so an agent must infer when to choose this tool over them.

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?

The description goes far beyond the annotations by explaining ambiguous-name behavior, the `figi_candidates` fallback, explicit `unresolved` reporting, graceful degradation of LEI/FIGI enrichment, and internal multi-endpoint cascading. None of this conflicts with the readOnly/openWorld/idempotent hints.

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

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

The description is long and dense, but it is structured with query examples, a SUPPORTED TYPES split, and failure/fallback details. Every sentence contributes useful information for a genuinely complex multi-source tool, though tighter formatting 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 semantics, and it does: it lists the identifier types, ownership data, FIGI candidates, unresolved fields, and citation behavior. It also covers accepted inputs and failure modes, so an agent has enough context to call and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance: it clarifies what each entity type resolves to, emphasizes passing the entity name only, and explains why trailing security-class words break FIGI matching. This adds value beyond the schema's own descriptions.

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

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

The description states a specific verb and resource: resolving user-spoken names to canonical/official identifiers. It includes concrete query examples and enumerates supported types, clearly distinguishing this tool from likely siblings like entity_profile or compare_entities.

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

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

"Use FIRST whenever you have a name but need an ID" gives explicit decision guidance, and the description clarifies which inputs each type accepts. It does not explicitly name alternatives to avoid, but the conditional context is strong enough for an agent to select this tool correctly.

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?

The description goes well beyond the annotations by explaining the two execution paths (SEC EDGAR fast path and grounded pipeline), the return verdicts, the meaning of could_not_verify vs. unsupported, and the presence of citations and reasoning. It also discloses failure modes via verification_error, providing rich behavioral context.

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

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

Although long, every sentence earns its place. The description is front-loaded with trigger phrases and purpose, then efficiently details routing, return values, caveats, and the efficiency benefit. It is well-structured and free of redundant information.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description fully compensates by explaining the return values, verdict meanings, error semantics, and examples. It covers edge cases and provides enough detail for an agent to invoke it correctly without 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 coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema, particularly for tolerance_pct: it explains how the default is derived from claim wording, how to override it for hallucination detection, and the range constraint. The claim parameter is further illustrated with examples, adding value.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with explicit trigger phrases like "fact check" and "verify the claim that." It distinguishes itself from sibling tools by focusing on verifying factual claims and returning verdicts, rather than general Q&A or research.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," and explains the routing for company-financial vs. other claims. It does not name alternative tools, but the "Replaces 4–6 sequential calls" statement implies a comparison to a manual multi-step workflow. It lacks an explicit 'when not to use' clause, so a 4 is appropriate.

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