Arcgis Johnsoncity

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

Annotations already indicate readOnly and idempotent behavior, and the description adds valuable context: it explains that the tool makes external LLM calls, that Anthropic calls require a user-provided API key, and that the user pays Anthropic directly. It also discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view), which is beyond the annotation hints. It does not mention rate limits or potential non-determinism, but the confidence field partially covers uncertainty.

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

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

The description is four short sentences, each covering a distinct aspect: purpose, configuration/cost, return format, and use cases. There is zero filler or redundancy. It is front-loaded with the core purpose, making it easy to scan, and every sentence earns its place.

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

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

With no output schema, the description takes responsibility for explaining what the tool returns, and it does so clearly: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also covers model selection, cost implications, and typical use cases. Given the moderate complexity (4 params, 1 required), this is a complete description that leaves no major questions unanswered.

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 meaningful parameter context by stating the default model (Workers AI Llama-3.3-70b, free) and explaining that _apiKey is only needed for Anthropic and is passed straight through. It also clarifies the `context` parameter's disambiguation purpose implicitly through the examples. This goes beyond the schema descriptions, making the tool easier to invoke correctly.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility.' It clearly states the output (0-100 visibility score) and the scope (per model), distinguishing it from sibling tools like ask_pipeworx or deep_research. The use cases (AI-marketing audits, pre-launch brand checks) further clarify its niche.

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

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

The description provides clear context for when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains how to choose between models (default Workers AI vs. Anthropic with _apiKey), which acts as practical usage guidance. However, it does not explicitly name alternative tools or state when not to use this tool, so it does not earn a 5.

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

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

The description discloses behaviors beyond the annotations: it routes to 5,462 tools across 1,419 sources, returns stable pipeworx:// citation URIs, works on every tier, and is fast. This complements the readOnlyHint and idempotentHint annotations without contradiction, giving a clear picture of what the tool does internally.

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 verbose but every sentence carries meaningful information: directives, scope, examples, alternatives, and citation details. It is well-structured, starting with the most important guidance ('PREFER OVER WEB SEARCH') and then detailing use cases. Slightly long 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 tool's complexity and lack of output schema, the description is remarkably complete. It explains the return format (structured answer with stable URIs), lists domains covered, gives examples, and explicitly mentions when to escalate to sibling tools. No critical operational detail 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% with all aliases documented, so the baseline is 3. The description adds value by providing concrete example questions and phrasing triggers ('what is', 'look up', 'find'), which enriches the semantics of the 'question' parameter beyond the schema's simple 'Alias for question' entries.

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: it routes factual questions to appropriate data sources and returns structured answers with citations. It uses specific verbs ('routes', 'returns') and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the tool's scope unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives ('Step up only when needed' with specific conditions for ask_pipeworx_grounded and deep_research). It also lists example queries and domains, leaving no ambiguity about appropriate use 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?

Beyond the readOnlyHint/idempotentHint annotations, it adds critical context: it is a 'full working router' that 'falls back to nothing,' and that results are compared against the stable router for merge decisions. This clarifies the operational behavior and experimental nature 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?

Four sentences, each earning its place: defines the tool, states current status, gives usage direction, and disambiguates from a fallback. It is front-loaded and compact, with no fluff.

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

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

Given there is no output schema, the description compensates by noting the 'same response shape' as ask_pipeworx and clarifying the functional completeness ('falls back to nothing'). It could add more on return format, but the explicit comparison covers the main gap.

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

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

The input schema already contains 100% coverage, describing the `question` field and all its aliases. The description only says 'same arguments' as ask_pipeworx, adding no new parameter-specific meaning, so the baseline of 3 applies.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx' and a 'universal router' with the same set of 5,462 tools and response shape. It distinguishes itself from the stable sibling by noting experimental routing improvements, satisfying the verb+resource+scope criterion.

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 it exactly like ask_pipeworx when you want the newest routing,' and notes that currently it matches ask_pipeworx exactly because no candidate is active. This gives clear when-to-use context, though it stops short of explicitly saying when NOT to use it (e.g., preferring stable routing).

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, openWorldHint, idempotentHint, destructiveHint), the description discloses the additional LLM call cost, the exact success and refusal return structures, and the specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). No contradiction with annotations exists.

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

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

The description is dense but every sentence and clause earns its place: it defines the operation, the routing, the extraction constraint, the return shape, refusal modes, when to use, and the cost tradeoff versus ask_pipeworx. It is front-loaded with the core purpose and structured logically.

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

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

Despite having no output schema, the description fully explains the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal states. It also explains the relationship to ask_pipeworx, making the tool's role within the sibling set clear.

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% as all six parameters are documented aliases for the 'question' field. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that routes through the same tool selection as ask_pipeworx, extracts answers using only tool results, and returns a structured response with refusal reasons. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded, evidence-only nature.

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

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

Provides explicit when-to-use guidance: whenever the answer will be quoted, cited, or acted on and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements). It also tells when not to use it, naming ask_pipeworx as the preferred alternative for casual lookups and noting the extra LLM call cost.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond with operational details: resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits (status:'low_confidence_match' for low-confidence matches, status:'market_closed_or_inactive' for dead markets), wide-spread illiquidity warnings, and cancellation-rule risk (refund_50_50 with EV impact). This is exceptional behavioral disclosure.

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

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

The description is long but exceptionally well-structured with clear section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section adds operational value. It is not 'concise' in length but is efficiently organized and front-loaded with the core purpose. A 5 would require tighter prose; a 4 reflects good structure 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?

Given the tool's complexity (classifiers, many data sources, resolver logic, response shapes, safety behavior) and the absence of an output schema, the description is remarkably complete. It covers response shapes (result.market, result.analysis, result.evidence, result.parent_event), news fields, blocking behaviors, and cancellation rules. No critical context 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 description coverage is 100%—all three params (market, depth, include_raw) have detailed descriptions. The tool description adds real-world input examples (slug, URL, question text) and explains how the resolver handles ambiguous matches, which nuances the market parameter. Given the high schema coverage, a baseline of 3 applies, but the description's examples and resolver context push it to a 4.

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

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

The description opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states what the tool does (resolves, classifies, fans out, returns evidence packet + market-vs-model comparison) and distinguishes it from general research tools like ask_pipeworx and edge-specific tools like polymarket_edges.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples across bet categories. However, it does not explicitly state when NOT to use the tool or mention alternative sibling tools, so it falls short of a 5.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint) already covering safety, the description adds substantial behavioral context: it pulls specific financial metrics from SEC EDGAR/XBRL for companies and FAERS/FDA/trial data for drugs, handles off-calendar fiscal years correctly, sorts by primary metric so 'largest' reads off the top, and returns paired data with citation URIs. This far exceeds the structured annotations.

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

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

The description is longer than average, but every segment earns its place: trigger phrases, explicit preference rule, per-type data details, sorting behavior, and return format are all packed in. It is front-loaded with the most important usage cues and uses formatting (quotes, em-dashes) for readability. It could be slightly tightened, but the density of useful information justifies the length.

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

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

With only 2 params, no output schema, and clear annotations, the description fully explains what the tool does, how it behaves, what data it returns (paired data + citation URIs), and why it should be preferred. It even anticipates edge cases like off-calendar fiscal years. For a tool of this complexity, the description is remarkably complete.

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

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

The schema already covers both parameters with descriptions (100% coverage), so a baseline of 3 is warranted. However, the description adds significant semantic value by explaining what each type actually retrieves (e.g., 'company' → latest 10-K revenue + net income + cash + long-term debt; 'drug' → FAERS counts + FDA approvals + trial counts), and by giving concrete examples for values (tickers/CIKs vs drug names). This goes beyond the schema's minimal definitions.

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

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

The description opens with concrete query examples ('Compare X and Y', 'X vs Y', 'rank these companies') and states the core function: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It distinguishes itself from sequential lookups ('Replaces 8–15 sequential lookups') and from sibling tools like entity_profile by explicitly focusing on multi-entity comparison.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving direct usage guidance. It also lists example queries that should trigger this tool, implicitly covering when to use it. No exclusion criteria are needed because the examples plus the 'ALWAYS PREFER' instruction clearly delimit the intended use case.

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 numerous behavioral traits beyond the readOnly/idempotent annotations: parallel routing to 5,462 tools, returns a findings packet with evidence/confidence/source/fetched_at, never invents data, exposes gaps[], contradictions[], hop field, fetchable citation_uri, semantic excerpting, and latency expectations (15-60s, up to ~90s). This far exceeds the annotation-provided safety profile.

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

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

The description is dense but every sentence contributes unique information: account requirement, alternative tool, data sources, mechanism, output, gaps, depth behavior, citation semantics, latency. It is front-loaded with the most critical operational constraint (account/paid plan) and is well-structured for an AI to parse.

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

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

This is a complex research tool with no output schema, yet the description covers inputs, outputs, limitations, error/gap handling, depth semantics, authentication, and alternatives. It tells the agent everything needed to set expectations and invoke correctly, including edge cases like missing data and open-web topics.

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 value by providing example question shapes ('compare X and Y's regulatory + financial exposure'), clarifying that broad/multi-part questions are appropriate, and giving practical depth-tier behavior beyond the schema (e.g., 're-angles unanswered gaps', 'chases leads', paid plan requirement for thorough).

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 performs 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, with a specific verb and resource. It also distinguishes itself from siblings like ask_pipeworx by explicitly noting it is 'NOT open-web search' and decomposes questions into facets.

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

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

Provides explicit when-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx', and also states account requirements and when to use different depth levels. This gives clear context for tool selection 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 readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral context beyond annotations: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and results are 'ready to call directly, no second schema lookup needed.' This describes return behavior meaningfully.

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

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

Four sentences with a clear front-loaded purpose ('Find tools by describing the data or task'). The long domain list is arguably verbose but informative, and every sentence contributes to understanding when and how to use the tool. No redundant content.

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

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

For a tool with no output schema, the description clearly states what is returned (top-N tools with names, descriptions, schemas) and the intended use case. It addresses the core needs of an agent: what it does, when to use it, and what to expect. Minor omissions like relevance ordering or edge cases don't detract significantly.

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 all parameters with descriptions and aliases, giving high coverage. The description adds a wide list of example topic areas (SEC filings, FDA drugs, etc.) that help formulate queries, but it doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It distinguishes itself from siblings by being a meta-tool discovery service, explicitly listing the types of data/tasks it covers and noting it returns full schemas, making it unique among search-oriented siblings.

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

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

Provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and a strong directive 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when not to use it (when you have one specific answer in mind), though it doesn't name alternative tools explicitly.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial context: it fans out across five sources, notes the patent API sunset with a soft-fail, mentions the GDELT→GNews fallback chain, and details the return structure (e.g., 'fundamentals (LATEST 10-K... sorted period_end DESC)'). This goes beyond the annotations and sets accurate expectations about limitations.

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

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

The description is long but information-dense: every sentence earns its place. It opens with concrete user prompts, immediately states the core purpose, then packs in sources, return fields, and input constraints using a compact semicolon-separated structure. There is no fluff or redundancy.

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

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

With no output schema, the description fully covers the return contract: CIK and company name, up to 5 filings with URIs, specific fundamentals metrics and sorting, patent status and soft-fail, news fallback chain, and LEI. It also covers input formats and the resolve_entity alternative. This is highly complete for a complex cross-source 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%: the schema already explains the 'type' enum and 'value' as ticker/CIK with the 'names not supported' caveat. The tool description repeats this information nearly verbatim, without adding new meaning beyond the schema. The baseline of 3 applies because the description does not enrich parameter semantics 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 the tool's function with a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It is distinguished from siblings through the explicit 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' guidance and by listing the exact data sources and return fields, leaving no ambiguity about what the tool does.

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

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

The description includes explicit usage timing ('when the user asks for a holistic view'), a strong preference directive ('ALWAYS PREFER'), and clear when-not-to-use guidance: names are not supported, so 'use resolve_entity first if you only have a name.' This provides clear alternatives and exclusions.

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

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

Annotations already indicate destructive and idempotent behavior, so the bar is lower. The description adds useful context about the scope (previously stored memory, sensitive data) and relationships with siblings, without contradicting the annotations.

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

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

Two concise sentences, front-loaded with the primary action, followed by usage guidance and sibling reference. No unnecessary words or repetition of schema details.

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

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

For a simple deletion tool with one parameter and no output schema, the description covers the purpose, usage conditions, and relationship to siblings. It doesn't detail error handling for missing keys, but the idempotent annotation partially addresses that, and such detail is not essential for a basic delete.

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 describes the single 'key' parameter with 'Memory key to delete' at 100% coverage. The description's phrase 'by key' doesn't add meaningful semantics beyond the schema, 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 opens with a specific action and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like 'remember' and 'recall' by specifying the delete operation on memory entries.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' providing clear context 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits a 'single text blob ready to drop at site-root/llms.txt.' This goes beyond the annotations by explaining the internal pipeline and output format, though it does not discuss error handling or network failures.

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

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

The description is two sentences long, front-loaded with the core purpose, and every clause adds value. It efficiently covers what the tool does, how it does it, the output format, and concrete use cases without any fluff or repetition.

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

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

For a simple two-parameter tool with no output schema, the description sufficiently explains the output format and use context. It covers the main workflow and expected deliverables. It lacks mention of potential failure modes (e.g., unreachable URLs) or prerequisites, but given the tool's simplicity and the strong annotations, it is reasonably complete.

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

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

Schema description coverage is 100%, and both parameters (url, max_links) are already well-described in the schema, including default and max values for max_links. The description adds minimal semantic value for parameters, only reinforcing that the URL can be any site or landing page. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action: 'Generate a production-ready llms.txt file for any URL' and follows with the concrete steps of fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. It distinguishes this tool from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than merely checking visibility or scanning presence.

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: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. This clearly indicates when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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 the operation as read-only, idempotent, and non-destructive. The description adds value by disclosing exactly what will be returned (fields, geometry type, record count, capabilities), which goes beyond the annotations and gives the agent a good sense of the tool's output.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and enumerates the return value details efficiently. Every word earns its place with no redundancy.

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

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

For a simple 1-parameter tool with strong annotations, the description is complete: it states what the tool does, how it is invoked (by URL), and what information the agent can expect to receive. There is no output schema, but the description itself provides the necessary outcome details, making it sufficient for the agent to decide correct usage.

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

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

The input schema already provides a description of the url parameter with an example. The description's mention of 'by url' adds minimal semantic meaning beyond what the schema already provides, so the baseline of 3 is appropriate given 100% schema coverage.

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

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

The description states a specific verb ('Get') and a specific resource ('ArcGIS Feature/Map Service layer's schema'), and explicitly lists the key information returned. This clearly distinguishes it from sibling tools like query_layer, which presumably queries actual data.

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

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

The phrase 'by url' clearly indicates that the tool requires a layer URL and is meant for retrieving schema metadata. It does not explicitly name alternatives or state when not to use it, but the context is reasonably clear given the described purpose.

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

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

Annotations already cover read-only, non-destructive, idempotent behavior. The description adds value by disclosing the return field list, caller scoping ('caller's'), and the active-only default, all beyond what annotations convey.

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

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

Two concise sentences. The first states the action and return fields; the second provides usage guidance. No filler or redundant content.

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

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

For a simple list tool with one optional parameter, the description covers scope, return fields, and use cases. Annotations handle safety. No important gaps apparent.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, and the schema description is clear. The tool description does not add parameter-specific semantics, but the baseline of 3 is appropriate given the schema does the heavy lifting.

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

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

The description clearly states the tool lists the caller's active subscriptions, uses a specific verb ('List') and resource, and enumerates the returned fields. It distinguishes itself from subscription-related siblings by framing use cases (reviewing before adding more, finding an id to cancel).

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

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

Provides explicit when-to-use context: 'review what you're monitoring before adding more' and 'find an id to cancel.' This implies alternatives (subscribe/unsubscribe) without naming them explicitly, so it stops short of a 5.

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

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

Annotations are all false, so the description carries the full burden. It discloses the non-account claim_token return, how to check status later, rate limiting ('5 per identifier per day'), and that it doesn't count against tool-call quota. It also clarifies that feedback is read daily and influences roadmap, giving a clear 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?

Though lengthy, every sentence earns its place: purpose, eligibility, exclusions, token flow, rate limit, and quota impact. It is front-loaded with the main purpose and then logically flows through instructions. No redundant or vague wording.

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-mode tool without an output schema, this description is highly complete. It explains what happens when filing (returns claim_token), how to retrieve status later, what the team does with feedback, and practical constraints (rate limit, quota). No critical operational context 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% with rich per-parameter descriptions. The description adds value by explaining the two invocation modes: filing (type/context/message) vs. reading a claim (claim_token alone with no other arguments). It also reinforces that context should reference Pipeworx tool/pack names, which goes 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature/data_gap, praise) and distinguishes itself from sibling research/subscription tools. The dual-mode behavior (filing vs. claiming with a token) is also explained up front.

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 ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...', 'when something worked surprisingly well') and when not to ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). It also warns against pasting end-user prompts and explains the claim_token follow-up 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: it is a self-aggregating signal derived from CF analytics-engine, states 'no PII, just (pack, tool, count)', and discloses caching (5min-1h depending on window)—all 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 a single paragraph with a clear purpose statement followed by a 'Useful for:' list and provenance note. All sentences contribute, though the list could be slightly trimmed without losing value.

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

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

With no output schema, the description states the return content (top tools, top packs, total call volume) and clarifies the data shape as '(pack, tool, count)'. It also covers caching and data source, making it complete for a 1-param read-only tool.

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

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

The input schema fully covers the only parameter 'window' with its enum values and trade-off explanation. The tool description adds no additional parameter semantics beyond mentioning the window, so with 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Returns') and resource ('top tools, top packs, and total call volume'), and frames it specifically as 'what other AI agents are calling on Pipeworx right now.' This distinguishes it from sibling tools like discover_tools by emphasizing the aggregated, social-signal aspect.

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 'Useful for:' list provides three explicit use cases, and the window guidance contrasts short vs long windows. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond this by disclosing internal logic such as monotonicity/partition-sum checks, Jaccard similarity threshold (≥0.30), placeholder filtering (>20% returns null), and fill-check behavior (realizable_edge_pp ≤0 means 'do not trade it'). It also describes response fields and edge cases, adding rich context without contradicting the annotations.

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

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

The description is lengthy but each sentence contributes necessary detail for a complex tool. It is front-loaded with purpose and invocation modes, but could be more scannable with structured lists or bullet points. Still, no sentence feels wasted, so it earns a high score.

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: opportunities[] with fields, partition_check structure, and fill_check details. It also covers filtering logic, skipped_low_similarity, and references a sibling tool for custom sizing. All invocation modes and edge cases are addressed, making it highly 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% for both parameters, but the description adds substantial meaning: it defines event slugs with concrete examples ('fed-decision-may-2026'), topic seed questions ('Strait of Hormuz traffic returns to normal'), and behavior of each mode. This goes far beyond the schema's basic descriptions, helping the agent choose and format parameters correctly.

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', using a specific verb and resource. It clearly distinguishes this from sibling tools by detailing event and topic modes and referencing polymarket_fill_risk for custom sizing, 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 explicitly explains three invocation modes: no args for trending_scan, event for single-event checks, and topic for cross-event scans. It contrasts single-event vs cross-event capabilities and points to polymarket_fill_risk for custom sizing, providing clear when-to-use and alternatives 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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail beyond that: it explains the return structure (by_segment, fed_candidates, _diagnostics), the caching behavior (Cached 1h at the KV level keyed on all knobs), the per-leg slippage assumption, the 24h-move warning, and the internal model families. It also explains why segments can be empty, which is valuable for callers. No contradictions with annotations.

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

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

The description is long, but it is densely packed with unique, valuable information structured by segments and knobs. It front-loads the core purpose and then systematically details the three model families, response fields, and filters. There is little redundancy, and every sentence contributes context. It could be more parsimonious, but the complexity of the tool justifies the length.

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

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

Since there is no output schema, the description carries the full burden of explaining the return value structure. It thoroughly describes the top-level response (by_segment with three named keys, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips). It also explains the meaning of each opportunity field (e.g., edge_pp_net after slippage, kelly_fraction capped at 0.25). This is complete for a complex tool with no output schema.

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

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

The input schema already has 100% description coverage for all 9 parameters, so the baseline is 3. The description adds extra context that enriches the schema, such as explaining that min_kelly does not filter partition_overround opportunities because partition-level kelly_fraction_half is always 0 by design, and explaining the rationale behind min_liquidity and max_spread_pp. This goes beyond simple parameter descriptions, earning a 4.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states what the tool does and distinguishes it from siblings like polymarket_arbitrage (which likely focuses on cross-market arbitrage) and polymarket_edge_tracker (which tracks edges over time). The phrase 'Built for what should I bet on today' adds a clear use case.

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

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

The description explicitly states the intended use case ('what should I bet on today') and provides guidance on how to use the knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It also notes a caveat about Fed bets being excluded from ranking. However, it does not explicitly contrast with alternative sibling tools, 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, openWorld, idempotent), the description adds substantial behavioral context: 60-day snapshot TTL, snapshots written on cache-miss causing gaps, decay computed from daily closes not intraday, and detailed response semantics. This enriches the safety profile without any 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 well-structured with clear sections for arguments, response, and limits. It is front-loaded with the core question, and every sentence provides meaningful information. Despite its length, it remains efficient and readable.

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 thoroughly explains the return value (tracked[], expired[], snapshot_dates[]) and their meanings, including derived metrics and caveats. It also covers data freshness and TTL limits, making the tool fully understandable without external references.

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

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

The input schema already provides complete descriptions for both parameters (defaults, clamps, allowed values), and the description largely repeats these details. It adds 'snapshot family' context for window but no significant new semantics, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as providing 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series rather than current edge values.

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

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

The description implies usage context by noting it is 'built from daily polymarket_edges snapshots', suggesting it is for historical persistence/decay analysis versus the current-edge tool. However, it does not explicitly name an alternative tool 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?

The description provides extensive behavioral context beyond the annotations: it details the ladder-walking computation, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), mode-specific interpretation of size_usd, and the failure mode of partial basket fills ('convert an arb into an unhedged directional position'). It also warns about thin books and lists forced_directional_risk as a return. Annotations only state readOnly/idempotent; the description adds far more.

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

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

The description is long but highly structured with bolded mode indicators (SINGLE-MARKET, BASKET) and a direct 'USE THIS' instruction. Every sentence adds functional value, and content is front-loaded with purpose. It loses a point for sheer length, but the organization makes it 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?

In the absence of an output schema, the description fully enumerates all return values for both modes, explains the interpretation of results (e.g., theoretical_sum vs realizable_sum, capture_ratio, profit_usd), and contextualizes the tool's place in a workflow. It even names the specific sibling signals it should precede. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and the schema descriptions are already detailed. The description adds critical non-obvious semantics: the requirement of exactly one of `market` or `event`, the default of `side` in basket mode ('auto from partition sum'), and how `size_usd` is interpreted differently in each mode. This boosts the value above schema baseline, though the schema itself already covers some of the same 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 opens with a precise statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This uses a specific verb ('check') and resource ('live CLOB order-book depth'), and clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk verification rather than trade discovery or execution.

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 embedded: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use single-market mode vs basket mode, and clarifies the downside of not using it (partial fills → unhedged directional risk). This is model guidance for when to choose this tool and when not to.

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?

Goes far beyond the readOnlyHint and idempotentHint annotations by disclosing specific failure modes (compatibility_warning cases), temporal alignment semantics, and skipped-type counters. This gives the agent deep insight into how the tool behaves and what its results mean.

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

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

The description is long but information-dense, covering modes, response fields, and safety semantics. It is well-structured with labels like 'TWO MODES' and 'SAFETY FIELDS', though some sentences are run-on and could be tightened without losing value.

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

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

Even without an output schema, the description thoroughly explains the response structure: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped-type counters. This is sufficient for an agent to correctly interpret and use the tool's output.

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

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

The schema covers all three parameters with descriptions, and the tool description adds meaningful semantics: the topic shortcuts auto-fetch matching events, explicit parameters override the mapped side, and the two-mode distinction clarifies parameter relationships. This exceeds the baseline for high schema coverage.

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

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

Clearly identifies the tool's function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. The description explicitly names both venues and the unique 'spread' concept, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit usage guidance for two modes: pre-mapped topic shortcuts vs explicit event identifiers, and when each is appropriate. It also states clear when-not-to-use conditions (e.g., incompatible bet shapes, temporal misalignment) and warns that 'pre-mapped ≠ tradeable', giving strong practical context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the return type ('attribute rows (and geometry)') and the SQL-like query nature. No contradictions with annotations exist.

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

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

The description is two sentences, front-loaded with the action and resource, and every clause earns its place. It conveys the core functionality, a usage pattern, and a sampling tip without any fluff.

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

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

For a tool with 6 parameters and no output schema, the description covers the essential workflow (query layer by URL, return rows/geometry) and links to search_datasets. While it does not detail pagination or error handling, the schema already documents `offset` and `limit`, making the description sufficiently complete for an agent to start using the tool correctly.

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

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

The input schema provides 100% coverage for all 6 parameters, so the baseline is 3. The description adds a convenient usage pattern for `where` and `out_fields`, but it does not clarify individual parameter semantics beyond what the schema already contains. The added value is marginal.

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 ('Query') and a specific resource ('ArcGIS Feature Service / Map Service layer'), clearly distinguishing it from sibling tools like layer_info (metadata) and search_within (spatial). It also specifies the source ('from search_datasets'), making the tool's role 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?

It implies a workflow by referencing 'from search_datasets' and gives a practical sampling tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly exclude alternatives or state when not to use this tool in favor of siblings like layer_info or search_within, leaving room for clearer guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: scoping to an identifier (anonymous IP, BYO key hash, account ID) and the dual behavior of retrieving a single key vs listing all keys. This goes beyond the schema and annotation baseline, though it doesn't address potential edge cases like empty memory or error handling.

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, all information-dense with no redundancy. The main action is front-loaded, followed by usage context, scoping, and sibling relationships. Every clause earns its place.

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

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

For a simple one-parameter read-only tool, the description covers both operational modes, explains scoping, and situates it within the memory workflow (remember/forget). Given the rich annotations and schema, no critical information is missing. The lack of return format details is acceptable since no output schema exists and the tool's behavior is straightforward.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this by explicitly stating 'omit the key argument' and provides concrete examples of key values (user's target ticker, address, research notes), which helps the agent understand what constitutes a meaningful key. This adds value beyond the schema alone.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes itself from siblings by explicitly referencing remember and forget, making the tool's role within the memory system 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?

Explicit guidance is provided: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names the counterparts (remember, forget) and clarifies the omit-key behavior for listing all keys, giving the agent clear when-to-use and alternative context.

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

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

The description states that setting mark_read:true flags events as read, which modifies state, directly contradicting the readOnlyHint annotation that declares the tool read-only. This is a clear annotation contradiction, so the score is 1 per the rubric.

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. It packs substantial detail into each sentence without fluff. The second sentence is somewhat dense but remains readable and all content is relevant.

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 return payload, filtering, mark_read side effect, polling, and an alternate HTTP access point. It omits nothing critical, and the schema covers remaining parameter details. It would be complete if not for the transparency contradiction.

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?

While the schema covers all parameters at 100%, the description enriches meaning by giving a concrete example for type (sec_8k), specifying ISO timestamp for since, and explaining the side effect of mark_read. This goes beyond 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 opens with 'Pull fired events from your subscription feed,' which specifies a clear verb, resource, and scope. It distinguishes itself from sibling tools like list_subscriptions by focusing on fired alert events, and adds details about the payload and filtering.

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

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

The description provides clear usage context: filtering by type and since, mark_read behavior, and polling suitability. It also names an alternative endpoint for scripts/dashboards, offering an explicit alternative. It does not explicitly exclude sibling tools, but the guidance is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context beyond this: it details the fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), explains fallback logic for rate limiting (GNews when GDELT fails), and notes soft-fail for patents due to API sunset. This is exactly the kind of behavioral depth annotations alone cannot convey.

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

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

Despite its length, every sentence serves a purpose: the opening lists real-world query examples, the middle covers sources and fallbacks (including the PatentsView sunset caveat), and the closing explains return format and alternative tool. The information is front-loaded with purpose, and the structure is logical. There is no filler or redundant repetition beyond what schema already provides for parameters.

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

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

The tool has no output schema, yet the description clearly specifies the return shape: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers the multi-source fan-out, fallback behavior, and the distinction from entity_profile, making it complete for an agent to decide when to invoke this tool and what to expect.

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

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

Schema description coverage is 100% and the schema already explains each parameter thoroughly (e.g., 'since' format and typical usage). The description mostly repeats this information rather than adding new meaning. It adds context about the overall window ('last N days/weeks/months') but does not materially enhance parameter understanding 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 identifies the tool as a change feed for a company, with explicit examples of user queries ('What's new with X', 'latest on Y'). It distinguishes itself from sibling tools by naming entity_profile as the alternative for static profiles, making the scope and resource type 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?

Provides explicit usage scenarios and parameter guidance (e.g., 'since' with formats and typical values). It also explicitly names entity_profile as the alternative when static profile data is needed, offering clear exclusion criteria. The fallback behavior between GDELT and GNews is disclosed, helping the agent set expectations.

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

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

Annotations already signal read/write and idempotence, but the description adds valuable context: key-value scoping by agent identifier, persistence differences for authenticated vs anonymous sessions (persistent vs 24-hour retention), and pairing with recall/forget. 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?

Three sentences, front-loaded with the core function, followed by usage guidance and storage behavior. No redundant wording; every sentence earns its place. It efficiently communicates what, when, and how without excess.

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

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

For a simple two-parameter write operation with no output schema, the description fully covers what the tool does, when to use it, persistence semantics, and relationship to siblings. Nothing critical is missing; the complexity is low and the description is proportionate.

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 (key and value), so the schema already provides full technical detail. The description only adds real-world examples of content to store, which is helpful but not parameter-level semantics. This matches the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes this tool from siblings by naming paired tools (recall, forget) and giving concrete use-case examples (ticker, address, preference, research subject). This makes the tool's purpose unmistakable.

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

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

It explicitly states when to use the tool ('Use when you discover something worth carrying forward... so you don't have to look it up again') and names the complementary tools for retrieval and deletion. Though it doesn't list negative use cases, the guidance is clear and actionable enough to prevent misuse.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds substantial context beyond these: it lists exact return fields (ticker, CIK, citation URI, RxCUI, etc.), notes auto-disambiguation, and reveals internal cascading that replaces multiple manual lookups.

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

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

The description is front-loaded with example queries and a clear purpose sentence, followed by types and return details. At roughly 180 words, it is slightly long but each sentence contributes distinct value, and the structure logically flows from generic purpose to specifics.

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

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

Since there is no output schema, the description compensates by detailing exact return fields and citation URIs per type. It omits error-handling behavior (e.g., what happens on ambiguous or unknown names), but the tool's simple 2-param interface and openWorldHint make it reasonably complete.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description mostly echoes schema information (e.g., accepts ticker/CIK/name) and adds only a minor behavioral note ('auto-disambiguated') rather than new semantic meaning for the parameters.

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

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

The description uses specific verbs ('resolve') and resources ('name to canonical/official identifier'), with concrete example queries and a clear scope for company and drug lookups. It differentiates from siblings by stating this produces IDs that other tools require.

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 instructs 'Use FIRST whenever you have a name but need an ID', providing a clear trigger context. However, it does not name alternative tools or explicit when-not-to-use conditions beyond implying that if you don't need an ID, you don't need this tool.

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

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

Annotations already claim read-only, idempotent, open-world, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. This provides useful context for how the tool operates without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the action and differentiated purpose. Each sentence provides distinct value: method, use case, and output format. The quoted example is concise and helpful, 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?

With no output schema, the description compensates by specifying the return structure (ranked list with score, confidence, signal density). Parameters are fully covered by schema, and annotations cover safety. It could mention rate limits or auth details, but the schema already covers the _apiKey parameter, making this 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% and each parameter has detailed descriptions, so the baseline is 3. The description does not add significant parameter meaning beyond echoing the entities concept, while the schema already explains first-entry-as-subject and model/API key constraints.

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 ('Compare'), a specific resource ('AI visibility across multiple entities'), and explicitly distinguishes from the sibling ai_visibility_check by indicating it probes each entity and ranks by score. The tool's purpose is 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?

It provides a clear use case for competitive AI-marketing audits and explicitly contrasts with ai_visibility_check by describing how it probes each entity. However, it does not mention alternatives such as compare_entities or state when not to use the tool, so it lacks explicit exclusions.

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

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

Beyond the read-only and idempotent annotations, the description discloses behavior such as fanning out across two services, partial failure degradation, and the 5-30s latency for bundlephobia's first measurement. It also explains the 'sources_failed' output when timeouts occur. This adds significant behavioral context that annotations alone do not provide.

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

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

The description is dense but every sentence serves a purpose: purpose, use cases, output summary, ecosystem scope, and failure handling are clearly delineated. It front-loads the primary function and avoids fluff. Despite its length, it remains well-structured and 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 composite tool with no output schema, the description fully accounts for complexity: it lists the exact output fields, describes per-advisory detail and links, explains ecosystem limitations, and covers failure modes with graceful degradation. This is complete enough for an agent to confidently invoke the tool 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 input schema already provides complete descriptions for both parameters (package name and version). The main description adds only a brief mention of scoped packages and default-to-latest behavior, which is already implied by the schema. Since schema coverage is 100%, the description adds minimal extra value for parameter semantics, aligning with the baseline of 3.

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

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

The description opens with a specific verb and resource: "Composite 'should I add this npm package to my project' check in ONE call." It clearly distinguishes the tool from siblings by naming the external data sources (deps.dev, bundlephobia) and the exact question it answers. This makes its purpose unambiguous and unique among the listed sibling tools.

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

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

The description explicitly states when to use the tool: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also gives an exclusion criterion for non-NPM ecosystems, directing users to "deps.dev:version directly" for PyPI/Maven/Cargo/Go. This provides clear context and a fallback alternative.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds exact return fields (name, summary, record_count, owner/org, Feature Service url) and explains how to use the returned url, going beyond annotations.

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

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

Two sentences with no fluff. First sentence states purpose and scope; second lists return fields and chaining. Front-loaded and efficient.

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

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

For a search tool with 3 optional params and no output schema, the description covers the core: what it searches, what it returns, and how to use results. It also accounts for sibling tools by pointing to query_layer/layer_info. No significant gaps.

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

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

Schema describes all three parameters with clear descriptions (query, limit, org_id), so the baseline is 3. The description adds minimal parameter semantics beyond 'by keyword', but it does not conflict with schema and provides contextual scope.

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

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

The description uses a specific verb ('Search') and names the exact resource ('City of Johnson City GIS open geospatial datasets') with examples of scope ('parcels, zoning, public works & city services'). It clearly distinguishes from sibling tools like query_layer by stating it returns Feature Service URLs for further querying.

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 tells the agent what to do with the results ('pass that url to query_layer / layer_info'), giving clear guidance on when to use this tool versus alternatives. The chaining instruction implies this tool is for discovery, while query_layer/layer_info are for data access.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail beyond these flags: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. 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 longer than minimal but every sentence contributes: purpose, use case, pairing with sibling tool, and technical details. It is front-loaded with the core semantic search action, then explains why to use it, and ends with implementation specifics. 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?

With no output schema, the description bears responsibility for explaining return values, which it does explicitly: 'top-N passages with character offsets and similarity scores.' It also covers the full context: when to use, technical implementation, input limits, and integration with ask_pipeworx_grounded. This is a complete picture for a semantic 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue'), clarifying the type of text expected (SEC 10-K, article, long tool result), and mentioning the 200K char limit. This goes beyond the schema descriptions and helps the agent craft appropriate inputs.

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

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

The description uses a specific verb ('semantic search') and resource ('a fetched record') with explicit scope ('INSIDE a fetched record'). It gives concrete examples (SEC 10-K body, article) and clearly differentiates from broader search tools by focusing on searching within already-fetched text, not external sources.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It also explains the tradeoff (saves context) and pairs with ask_pipeworx_grounded, describing the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear usage context and relationship to an alternative.

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

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

The description discloses several behavioral traits beyond the annotations: requires an OAuth account, phone verification for SMS, a 10/day SMS cap, and the always-on feed behavior. These details add real-world constraints and side effects that the annotations alone do not convey.

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

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

The description is dense but well-structured: it leads with the core purpose, then requirements, supported types, and delivery options. Each sentence delivers necessary information without fluff, making it appropriate for a tool with multiple types and delivery modes.

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

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

The description covers the essential aspects: purpose, return value, authentication requirements, supported types, and delivery channels. The main omission is webhook as a delivery channel in the main description, though the schema thoroughly documents it. Given the tool's complexity and lack of an output schema, it is nearly complete, but the webhook omission could mislead an agent reading only the description.

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 description enriches the schema by providing concrete examples for each supported type (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE') and clarifying delivery channel behavior. Even with 100% schema coverage, these examples add meaningful context that goes beyond the raw parameter descriptions.

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

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

The description 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 combination distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

It gives explicit prerequisites (Pipeworx OAuth account, verified phone for SMS) and clarifies that anonymous/BYO cannot persist subscriptions. It also explains the always-on feed and how to retrieve alerts via recent_alerts, providing good usage context. However, it does not explicitly state when not to use this tool or contrast it with alternatives like list_subscriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond that: it describes the return format (category-bucketed example questions), the source (live catalog of thousands of tools), and the effect of the topic parameter (focus vs. full spread). This gives the agent a clear picture of what to expect without any contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads example queries, then explains the output and parameter behavior, and ends with direct usage guidance. The structure uses clear separators and examples that make it easy to scan. Despite its length, there is no redundant or filler content.

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

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

For a tool with only one optional parameter and no output schema, the description is exceptionally complete. It explains the purpose, the exact output structure (categories, examples, tool+argument shape), how to control scope, and when to use it. It even names related meta-tools to learn, giving the agent full context for onboarding. There is no missing information that would prevent correct invocation.

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

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

Schema coverage is 100% and the schema already describes the topic parameter with a list of focus areas. The description goes further by giving concrete examples ('finance', 'pharma', 'betting') and explaining the behavioral difference between omitting and providing the parameter (full spread vs. focused). This reinforces and enriches the schema description, adding real-world context that helps the agent select appropriate values.

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

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

The description clearly states what the tool does: it is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses a specific verb ('suggest questions') combined with a resource ('Pipeworx capabilities') and distinguishes it from siblings by focusing on 'what can I ask' rather than tool discovery. The clarification that it also teaches how to call meta-tools further sets it apart.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', giving a clear when-to-use condition. It also explains how to tailor usage (no args for full spread, topic to focus) and mentions alternative meta-tools to learn about. However, it does not explicitly state when not to use the tool (e.g., once you already know what to ask), so it falls slightly short of a perfect 5.

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

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

Annotations indicate this is a write, non-destructive, idempotent operation. The description complements this by clarifying that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. It also reveals ownership enforcement, which is not captured 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 three concise sentences, front-loaded with the action, then detailing constraints and consequences. No filler; every sentence provides essential information.

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

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

For a simple single-parameter mutation, the description covers purpose, ownership, and the soft-delete behavior. Coupled with strong annotations and complete schema, it is fairly complete. It doesn't specify return values or error conditions, but the absence of an output schema and low complexity reduces the burden.

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 id parameter (uuid returned by subscribe), so the description adds little new information about parameters. The schema description coverage is 100%, so a baseline score of 3 is appropriate; the description's 'by id' reinforces the parameter without adding 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 opens with 'Cancel a subscription by id,' which clearly specifies the verb (cancel), resource (subscription), and scope (by id). It also adds ownership enforcement, distinguishing it from general subscription management tools like subscribe 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?

It provides clear context by stating ownership is enforced and that the subscription is deactivated rather than deleted, implying when to use it (when you want to cancel your own subscription and preserve history). However, it does not explicitly mention alternatives like list_subscriptions or explain when not to use it beyond ownership.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond these: exact percent-delta math for financial claims, fallback to grounded pipeline, return verdict types, citation format, and evidence usage. It does not discuss error cases or latency, so not a perfect 5.

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 but is front-loaded with query intents and structured with em dashes and semicolons. It contains some redundancy (e.g., 'fact check' appears twice), but every sentence contributes substance: usage, routing, output, and efficiency. Slightly long, though not verbose.

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

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

Given the tool has only 2 parameters and no output schema, the description fully compensates by detailing the return format (verdict types, actual value with pipeworx:// citation, reasoning), the two processing paths (SEC EDGAR vs grounded), and the claim types covered. It is complete enough for an agent to understand both invocation and expected 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?

Schema description coverage is 100%, so both 'claim' and 'tolerance_pct' are already well documented. The description repeats claim examples but does not add new parameter-specific details; it focuses on tool behavior. The baseline of 3 is appropriate since the description adds only marginal semantic value beyond the schema.

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

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

The description clearly states the tool performs natural-language claim verification with explicit user intents ('fact check', 'verify the claim that…'). It distinguishes itself from sibling tools by focusing on truth confirmation against authoritative sources and by noting it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance: financial claims use the SEC EDGAR/XBRL fast path, while all other claims fall through to the grounded pipeline. This gives clear when-to-use context without requiring cross-referencing with sibling tool descriptions.

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