Arcgis Kinston

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: the default free model, the BYO-key mechanism with direct costs to the user, and the return structure. No contradiction with annotations; it would be a 5 with more detail on network effects or rate limits.

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

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

The description is front-loaded with the main purpose, followed by essential operational details (default/cost), return format, and use cases. It is compact, with every sentence contributing distinct value and no redundancy or fluff.

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

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

The description covers purpose, default behavior, cost, return structure, and use cases. With no output schema, it appropriately outlines per-model and combined responses. It could be more precise about what the 'combined view' contains or any limits on the number of models, so it is not a perfect 5.

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 marginal value by restating the default model and cost implication, but the schema already documents each parameter's purpose. There are no gaps for the description to compensate for, making 3 appropriate.

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

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

The description clearly states the tool's function with specific verbs ('Probe', 'score visibility') and specifies the resource (LLMs) and output (0-100 per model). It is distinct from generic question-answering tools but does not explicitly contrast with sibling tools like scan_competitor_ai_presence, so it stops short of a 5.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic model via _apiKey. It lacks explicit when-not-to-use guidance or named alternatives, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context that it routes to 5,564 tools, fills arguments, and returns stable pipeworx:// citation URIs. It also mentions it works on every tier and is a fast call. While it doesn't specify what happens on failure or no results, it provides meaningful behavioral context beyond annotations.

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

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

The description is front-loaded with the core instruction ('PREFER OVER WEB SEARCH') and immediately lists data domains. It includes examples and usage guidance, but the grammar is occasionally informal and the length is somewhat long for a single tool description. Overall, it's well-structured and earns its sentences, though slightly 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's complexity (routing to 5,564 tools) and that output schema is absent, the description provides robust guidance on expected behavior and return format (structured answer with citation URIs). It covers key aspects for an agent to decide when to use it, but does not explain what happens when no matches are found or how errors are handled, which would round it out.

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

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

Schema description coverage is 100%, so baseline is 3. The description explains the 'question' parameter accepts natural language and even lists aliases (query, q, prompt, text, input), which is not in the schema's field description. It also gives example questions that implicitly show the expected format, adding 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 routes questions to a network of tools/sources and returns structured answers with citations. It lists specific data domains (SEC filings, FDA, FRED, etc.) and provides concrete example questions, making its purpose unambiguous and distinct from siblings like web search.

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 to prefer this over web search for factual questions, provides trigger phrases ('what is', 'look up', 'get the latest'), and gives step-up alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also clarifies when not to use it (breaking news, world opinions), satisfying the when/when-not criteria.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds valuable context about beta status, live candidate routing improvements, and the fact that no candidate is active currently. This goes beyond the annotations without contradicting them.

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

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

The description is somewhat verbose, repeating the identity to ask_pipeworx and reassuring that it is a working router. While well-structured and front-loaded, it could be trimmed for conciseness without losing 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?

Given the tool is a beta variant of a known sibling, referencing the same response shape is mostly sufficient. The description adds current-state details, usage context, and clarifies the experimental nature, making it complete enough for an AI agent to invoke correctly.

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

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

The input schema has 100% coverage with detailed descriptions for the question parameter and its aliases. The description does not add further parameter semantics, but the schema already handles it, so the baseline 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with the same tools and response shape. It explicitly distinguishes itself from the stable sibling by highlighting its experimental edge and current state of matching ask_pipeworx exactly.

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

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

It provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it is a full working router with no fallback behavior. However, it does not explicitly state when NOT to use it, though the reference to stable ask_pipeworx implies the alternative.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds significant behavioral context: it extracts answers only from tool result content, returns explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and discloses the extra LLM call cost. This fully discloses the failure modes and guarantees against hallucination 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?

Although 5 sentences long, every sentence earns its place: purpose, routing behavior, response schema, refusal modes, usage guidance, and cost trade-off. It is front-loaded with the core purpose and structured to answer the agent's selection questions without redundancy.

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

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

Given the tool's moderate complexity (6 aliases, no output schema), the description is remarkably complete: it explains the success/failure return shapes, the routing mechanism, the anti-hallucination guarantee, and the cost trade-off relative to ask_pipeworx. No important behavioral or usage aspect is left uncovered.

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 six parameters are aliases for the same 'question' string. The description does not add parameter-level semantics beyond what the schema already states (e.g., 'Accepts query, q, prompt, text, input as aliases'). Per the rubric, baseline is 3 when the schema covers everything, and nothing in the description improves on that.

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

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

The description opens with a specific verb+resource+scope: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from ask_pipeworx and ask_pipeworx_beta by describing the grounded extraction behavior and explicit refusal responses, leaving no doubt 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?

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This directly tells the agent when to choose this tool over the sibling, with concrete use cases like financial verdicts, legal claims, and medical lookups.

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 goes far beyond these by detailing behavior such as fan-out to category-specific data packs, resolver contract fields (market_match_confidence, score, alternatives), statuses for low-confidence and closed markets, tradeability warnings, and cancellation-rule risk. It even warns about EDGE already being priced in and recurring flat-50¢ void settlements, providing deep behavioral context.

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

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

Although long, every section is purposeful and clearly labeled (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). The opening sentence immediately states the core action and input format. The structured format makes dense information scannable and each example earns its place by illustrating real fan-out patterns.

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

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

There is no output schema, so the description compensates thoroughly by describing result.market, result.analysis, result.evidence, resolver contract fields, parent_event, news fields, and safety statuses. It covers edge cases like low-confidence matches, closed markets, and wide-spread illiquidity, giving an agent enough context to use the tool correctly 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 covers 100% of parameters with descriptions, including enum values and defaults. The description's mention of 'quick' and 'thorough' matches the schema, and it adds context like default thorough and include_raw recommendation, but these are largely redundant with the schema's own text. Baseline 3 is appropriate since 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the input types (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges or ask_pipeworx by focusing on data-pull research. The classifier list and fan-out examples further reinforce its unique role.

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 usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive fan-out examples for different bet categories, implying when this tool is appropriate. It does not name specific alternatives to exclude, but the strong categorical examples serve as practical 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 readOnlyHint=true already set, the description goes beyond annotations by disclosing data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting behavior, and the inclusion of citation URIs. This is rich behavioral context that 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?

The description is detailed but every sentence earns its place: triggers, core scope, explicit usage preference, data sources, edge-case handling, sorting, output, and efficiency claim. It is front-loaded with user phrases and remains tightly organized without redundancy.

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

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

Although no output schema exists, the description specifies the return format (paired data, sorted, with pipeworx:// URIs). It covers parameters, type-specific behavior, data provenance, and off-calendar fiscal year handling, making the tool fully understood in context without additional documentation.

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

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

The description significantly enriches the schema by explaining what metrics are pulled for each 'type' value (revenue, net income, cash, debt for companies; adverse events, approvals, trials for drugs) and gives concrete examples for 'values' (AAPL/MSFT, ozempic/mounjaro). Even with 100% schema coverage, this adds practical semantic depth.

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 trigger phrases and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes this from sequential single-pack lookups and sibling tools like entity_profile by specifying the comparison scope and supported entity types.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also details what each entity type returns (10-K metrics for companies, FAERS/FDA/trial data for drugs), making the appropriate use case unmistakable.

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 declaring readOnly, openWorld, idempotent, and non-destructive hints, the description adds rich behavioral context: parallel routing, findings packet contents, gaps[] semantics, contradictions[], citation_uri fetchability, excerpting behavior, hop behavior, and expected latency. No contradictions with annotations are present.

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

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

The description is long but information-dense; the account requirement and alternative tool guidance are front-loaded, and each sentence contributes a distinct operational consideration. It could be tightened slightly, but the structure is logical and appropriately detailed for a complex multi-tool orchestrator.

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

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

For a complex tool with no output schema, the description fully covers return format, latency, edge cases, limitations, alternatives, and depth semantics. It leaves no major gap the agent would need to guess about.

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

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

The schema already covers 100% of parameters, so the baseline is 3. The description adds meaning beyond the schema by clarifying that 'Broad/multi-part is fine — decomposition is the point' for the question parameter, and by explaining depth behaviors like gap recovery and contradiction scanning in operational terms.

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

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

The description uses a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call.' It clearly distinguishes this from sibling tools by explicitly contrasting with ask_pipeworx and by stating 'this is NOT open-web search.'

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' with concrete examples. It explicitly names alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also covers account-tier prerequisites.

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 readOnly, idempotent, non-destructive behavior. The description adds valuable context beyond this: it returns the top-N most relevant tools with names, descriptions, full input schemas, and curated examples, and states results are ready to call directly without a second schema lookup. This clearly discloses the tool's output behavior and operational characteristics.

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

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

The description is well-structured: it opens with a clear purpose statement, then provides usage context and return value details. It is longer than a minimal one-liner but every sentence carries useful information. The list of domains is comprehensive but necessary to convey scope. Minor redundancy in synonyms ('browse, search, look up') but not distracting.

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 discovery tool with no output schema, so the description's explanation of return content (names, descriptions, full schemas, curated examples, direct-call readiness) is essential and fully supplied. The annotations provide the safety profile (read-only, idempotent). Sibling tools are numerous, and the description clearly establishes this tool as the entry point, making the context complete for an agent.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters (query, q, task, limit, search, description) with descriptions and aliases. The tool description adds minimal parameter-specific meaning beyond mentioning 'top-N' in the return context, which aligns with the limit parameter but doesn't explain syntax or types beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this from sibling tools by positioning it as a discovery mechanism for the many specialized tools in the set, listing concrete domains and tasks. This is unambiguous and differentiates effectively from siblings like deep_research or search_datasets.

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

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

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' for a long list of topics, and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use context and implicitly states when not to use it (when a single direct answer is required, use the specific 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?

The description reveals significant behavioral details beyond annotations: it fans out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; lists the exact returned fields; and discloses fallback/failure behavior (USPTO PatentsView API sunset with soft-fail, GDELT→GNews fallback). Annotations only declare read-only/open-world/idempotent, so this context is valuable.

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

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

The description is long but well-structured, front-loaded with usage examples, and contains critical operational details (return fields, fallbacks, edge cases). While every sentence earns its place, the description is denser than necessary; a slightly tighter rewrite could improve clarity without losing information.

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

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

With no output schema, the description fully compensates by enumerating the return payload: cik, company_name, recent_filings with URIs, fundamentals, patents, news, and LEI. It also covers failure modes and fallback behavior, making it 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 coverage is 100%, with both parameters already fully described (type enum, value examples like 'AAPL' and '0000320193', and the restriction that names are not supported). The description repeats these constraints but adds no new parameter-level meaning; thus baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('profile') and resource ('US public company'), and explicitly frames it as a 'full cross-source profile' in 'ONE parallel call.' It distinguishes from siblings by noting it should be preferred over chaining single-pack lookups and that name-only queries should use resolve_entity.

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 when to use the tool: 'when the user asks for a holistic view.' It provides concrete alternative guidance ('use resolve_entity first if you only have a name'), and states a strong preference over chaining single-pack lookups. It also specifies input requirements (ticker or zero-padded CIK) and disallowed inputs (names).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds context that this affects 'previously stored memory' and can 'clear sensitive data,' but it doesn't describe edge cases like key-not-found behavior or whether deletion cascades. With annotations present, this is adequate but not rich.

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

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

Two sentences, front-loaded with the primary action, and each sentence adds value: the first defines the operation, the second provides usage guidance. 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 one-parameter, no-output-schema tool, the description covers the purpose, usage triggers, and related tools. It doesn't mention return values or missing-key behavior, but these are less critical given the tool's simplicity and the idempotent/destructive hints from annotations.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete.' The description's phrase 'by key' adds no new semantics beyond the schema. Baseline 3 applies.

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

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

Description clearly states the tool deletes a previously stored memory by key, using a specific verb ('Delete') and resource ('memory'). It distinguishes itself from sibling tools like 'remember' and 'recall' by explicitly framing this as the deletion counterpart.

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

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

The description provides explicit use cases: stale context, completed task, or clearing sensitive data. It also suggests pairing with 'remember' and 'recall,' though it doesn't explicitly state when not to use it or contrast with alternative tools for retrieval/updating.

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

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

Beyond the annotations (readOnly, idempotent), the description explains the process ('Fetches the page, extracts title/description/key links') and the output format ('standard llms.txt markdown format', 'single text blob'). This adds meaningful behavioral detail that annotations don't cover.

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

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

The description is three sentences, tightly scoped: purpose, process, and use cases. Every sentence earns its place with no redundancy or fluff.

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

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

The description covers the output format and purpose, and the annotations provide safety and idempotency context. With a simple 2-parameter schema, this is sufficiently complete, though it doesn't mention error handling for invalid URLs or edge cases.

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

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

Schema coverage is 100% with clear descriptions for both 'url' and 'max_links'. The description adds no parameter-specific detail beyond what the schema already provides, so 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 uses a specific verb+resource ('Generate a production-ready llms.txt file for any URL') and clearly distinguishes from siblings by focusing on llms.txt generation. It also specifies the target audience (AI crawlers) and the output, making the purpose unmistakable.

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

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

The description provides concrete 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'). It lacks explicit exclusions or alternatives, but the context is clear and actionable.

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

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

The description adds value beyond the annotations by listing exactly what schema details are returned (fields, geometry type, record count, capabilities). While annotations already declare read-only/idempotent behavior, the description enriches understanding of the tool's output 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 a single, front-loaded sentence that lists the output components compactly. Every word earns its place, and 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 simple single-parameter metadata retrieval tool, the description fully explains what the tool does and what it returns. There is no output schema to detail, and the tool's complexity is low, so the description is complete for an agent to invoke it correctly.

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

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

The schema already provides complete coverage of the single parameter (url) with a clear description and example. The tool description adds no further parameter-specific meaning beyond restating that it operates 'by url', so the baseline of 3 is appropriate.

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

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

The description clearly states the action (Get), the specific resource (an ArcGIS Feature/Map Service layer's schema), and the key outputs (fields, geometry type, record count, capabilities). It distinguishes itself from siblings like query_layer by focusing on schema/metadata rather than data.

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

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

The description clearly implies when to use this tool: when you need layer schema information by URL. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds value by specifying the caller-scoped nature and the exact returned fields (id, type, params, created_at, last_fired_at, fire_count). This goes beyond what annotations provide.

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

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

Two compact sentences: the first states the action and return format, the second gives usage guidance. No redundant words or 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 list operation with one optional parameter and no output schema, the description provides all essential context: scope, return fields, and usage. Annotations cover safety and side-effect profile, so no further detail is needed.

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

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

Schema coverage is 100% for the single optional include_inactive parameter, which has its own description in the schema. The tool description adds no extra parameter-level detail, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists the exact return fields. This distinguishes it from sibling tools like subscribe 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?

Provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke it, including before subscribing or unsubscribing, which implies 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?

Even with annotations present, the description adds substantial behavioral context: the claim_token workflow for anonymous filing and later retrieval, rate limiting ('5 per identifier per day'), that it is free and does not count against tool-call quota, and that the team reads digests daily. This goes beyond the annotations' simple hints and gives the agent a clear model of side effects and constraints.

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 covers the core action, usage triggers, exclusions, claim_token flow, and operational constraints. It is front-loaded with the main purpose and remains readable despite its length, with no filler or repetition of schema 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?

Despite having no output schema, the description clearly explains return behavior: anonymous filing returns a claim_token, and passing that token later returns status and resolution details. It also covers rate limits and quota, making the tool's full lifecycle transparent. Given the tool's moderate complexity (4 params, no required fields), the description is complete and self-contained.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful extra semantics. It explains the claim_token parameter's dual role (returned when filing without an account and passable later to read status) and advises describing issues 'in terms of Pipeworx tools/packs,' which enriches understanding of the context and message parameters. It does not redundantly restate schema fields.

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 explicitly enumerates feedback types (bug, feature/data_gap, praise) and clearly distinguishes itself from sibling tools like ask_pipeworx and discover_tools by focusing on reporting issues about Pipeworx tools rather than querying or exploring.

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: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a strong exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs to file elsewhere for non-Pipeworx MCP servers, plus a heuristic for identifying Pipeworx tools.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description adds valuable behavioral context: it discloses the data source ('derived from CF analytics-engine'), the privacy aspect ('no PII, just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This gives the agent confidence about the tool's side effects and freshness of data.

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

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

The description is well-structured: a one-sentence summary of what it returns, followed by a bulleted 'Useful for' list, and a closing sentence on data provenance and caching. Every sentence carries useful information without redundancy. The key facts are front-loaded, making it easy for an agent to scan and understand.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is fully self-contained. It explains the return payload conceptually, the intended use cases, data source, privacy guarantees, and caching. There are no missing pieces an agent would need to decide whether and how to invoke it correctly.

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

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

The schema already documents the window parameter thoroughly, including enum values and the guidance 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' The description adds marginal value by mentioning the window options ('24h, 7d, or 30d') and the caching implications ('Cached 5min-1h depending on window'), which explains why the choice matters for data freshness. 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?

The description opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It then explicitly lists the return values: 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This distinguishes it from sibling tools like discover_tools or search_datasets by focusing on real-time aggregated usage trends rather than directory listings or search.

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

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

The description provides explicit use cases prefixed by 'Useful for:' with three concrete scenarios (discovering hot data sources, confirming canonical tool choice, aligning with agent needs). It also gives guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly mention when NOT to use this tool or name alternatives, so it falls slightly 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 discloses critical behavioral details: the fill check pricing against live CLOB depth, the condition 'realizable_edge_pp ≤ 0 means ... do not trade it', the partition filter for placeholder slugs, and the skipped_low_similarity output. This goes far beyond annotation hints and provides actionable safety context.

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

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

The description is long but justifiably so given the tool's complexity. It is front-loaded with the core purpose and modes, then uses clearly labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to present edge cases and safety checks. Every sentence adds value, and the structured caps break up dense information effectively.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers all three execution modes, explains the response shape (opportunities[], partition_check, gap_pp, etc.), describes failure/skip conditions (placeholder fraction, skipped_low_similarity), and notes how fill check integrates with fill risk. Given the tool's sophistication, no significant 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?

Although the schema already describes both parameters (event and topic) with 100% coverage, the description adds substantial meaning: exact slug examples ('fed-decision-may-2026'), seed question examples, and mode-specific behavior (walking child markets, cross-event flattening). It explains semantic anchors and partition filters that are not in the schema, enriching the parameter semantics significantly.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges (which likely finds edge cases) and polymarket_fill_risk (which handles fill risk), and it breaks down three distinct modes (trending_scan, event, topic) with concrete examples.

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

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

Usage guidelines are explicit: 'Call with NO args for a `trending_scan`... pass `event` for... or `topic` for...' It also recommends `event` for specific markets and directs users to `polymarket_fill_risk` for custom sizing, providing an alternative tool. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavior beyond that: 1h KV-level caching, edge_pp_net computed after slippage, a 24h-move warning, diagnostic funnel counters for empty segments, and rare-by-design gates for concentrated longshots. It also clarifies that partition_overround returns kelly_fraction_half=0 at parent level, which is non-obvious.

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

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

The description is long and dense, but every sentence carries unique information about the model families, response structure, knobs, and diagnostics. It is front-loaded with the core purpose and then organized into numbered segments. While it borders on overwhelming, the structure and density are appropriate given the tool's complexity.

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

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

With no output schema, the description fully specifies the response shape: by_segment with three named keys, fed_candidates/fed_note, and _diagnostics with funnel counters. It explains field semantics (edge_pp_net, kelly_fraction, market fields), covers edge cases (why a segment might be empty), and even describes the caching layer. The tool is completely self-contained.

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

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

Schema coverage is 100%, but the description adds meaningful semantics not present in the schema: it distinguishes min_kelly (single-leg) from min_partition_leg_kelly (per-leg inside partitions), explains that Kelly fractions are capped at 0.25, and provides context for slippage_pp (zero fees but thin depth). It also explains how knobs aggregate and interact with segments, making parameter behavior clear.

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 statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage (cross-market gaps) and polymarket_edge_tracker (historical tracking). It also outlines the three output segments (model_driven, structural_arbitrage, concentrated_longshot), making the purpose concrete.

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 states an explicit intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when to use tradeable-edge knobs (min_liquidity, max_spread_pp) and why Fed bets are excluded from ranking. However, it does not explicitly name sibling tools as alternatives, so it stops short of full exclusion guidance.

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

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

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description goes far beyond them. It details the exact response structure (tracked, expired, snapshot_dates), explains the meaning of trend and decay_pp_per_day, clarifies that negative edge_pp_net means SELL YES, and discloses that snapshots are written on cache-miss and history is bounded by TTL.

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 and lengthy but well-structured: purpose first, then RESPONSE and LIMITS sections. Each sentence adds necessary detail about response semantics and constraints. It could be slightly more concise, but no information is redundant or wasted.

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 specifies the response shape (tracked[], expired[], snapshot_dates[]) and their meaning. It covers parameter defaults, edge cases (snapshot gaps, TTL limits, signed values), and the non-intraday computation basis. This is complete for an agent to select and invoke the tool correctly.

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

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

The input schema already covers both parameters completely (days, window) with defaults and allowed values. The description's Args section restates this information, adding only the phrase 'snapshot family' to clarify window's role. Schema coverage is 100%, so the description adds 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 defines the tool's purpose: 'Edge persistence and decay telemetry' tracking long-lived market edges. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges by focusing on historical snapshots rather than current edge data.

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

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

The description provides strong usage context, explaining that a fresh wide edge and a 3-week-old wide edge are 'different trades.' It implies the tool is for evaluating edge persistence and decay, which guides when to use it, though it does not explicitly name an alternative 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 declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral detail: it 'walks the ladder', warns that 'partial basket fills convert an arb into an unhedged directional position', and identifies 'forced_directional_risk' and 'thin_legs[]'. This goes well beyond the structured metadata.

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

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

The description is long but well-structured with SINGLE-MARKET and BASKET sections, and every detail serves a purpose. It is slightly dense and repeats some schema info (e.g., slug/URL format), but the complexity of the tool justifies the length. Could be marginally tighter 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?

There is no output schema, so the description carries the full burden of explaining return values—it does so in detail for both modes (verdict, capture_ratio, profit_usd, thin_legs[], etc.). Combined with the rich annotations and explicit usage warnings, the description is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond it: explains `size_usd` differently for single-market ('max spend on buys, target proceeds on sells') vs basket ('settlement notional S' with shares paying $1), documents the default and clamp range, and clarifies `side` defaults per mode. This is exactly the kind of enrichment expected.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two modes (single-market vs basket) and lists concrete return values, making it unambiguous what the tool does and how it differs from sibling tools like polymarket_arbitrage or 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes and the meaning of side/size in each, providing clear context and exclusions (e.g., theoretical overround not capturable on thin books).

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

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

Annotations declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context beyond that: response fields, compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype meanings. It also clarifies that matched_pairs:0 can mean either non-equivalent bet shapes or semantically unrelated events, showing deep transparency.

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?

While long, every sentence earns its place. The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. The density of critical safety 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 no output schema, the description fully compensates by explaining response fields, safety warnings, temporal alignment, and skipped-leg counters. It also sets expectations about the rarity of tradeable spreads, making the tool's behavior and limitations completely 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?

Even with 100% schema coverage, the description adds significant meaning: it lists all valid topic values, explains how kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and describes the two operational modes. This goes far beyond the schema's brief parameter descriptions.

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

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

The description clearly states the tool computes the 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', using specific verbs and resources. It distinguishes itself from siblings by explicitly naming both venues, while sibling tools like polymarket_arbitrage focus on Polymarket-specific opportunities.

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 when-to-use guidance with TWO MODES (topic shortcuts vs explicit ticker/slug), and explicitly warns when spreads are not tradeable ('pre-mapped ≠ tradeable' and compatibility_warning scenarios). However, it does not mention any alternative tools, so it falls short of the 'explicit alternatives' bar for a 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the bar for added value is met by the description's disclosure that it 'returns attribute rows (and geometry)' — a behavioral detail not in the annotations. It also implies SQL semantics and pagination via offset/limit, which helps the agent predict the response shape. It doesn't contradict annotations and adds useful context beyond them.

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

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

The entire description is two sentences: the first defines the action and key parameters, the second gives a practical example of how to use it. Every clause earns its place; no filler or redundant restatement. It is tightly structured and front-loaded with the core purpose.

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 stating the return type ('attribute rows (and geometry)'). It covers the essential workflow (from search_datasets, query with where/out_fields, sample with 1=1) and all parameter semantics are either in the description or schema. Minor gaps like authentication or error handling are not critical for a read-only query tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic flavor: 'SQL-like', 'comma-separated out_fields', and the sampling idiom. This clarifies the query language and option combination beyond bare schema definitions, justifying 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 pair ('Query an ArcGIS Feature Service / Map Service layer by its url') and clarifies the tool's role within the sibling ecosystem by noting the url comes 'from search_datasets'. It distinguishes from nearby tools like layer_info (metadata) and search_within (spatial search), making its purpose unmistakable.

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

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

The description gives clear context for use: querying a layer found via search_datasets, and includes practical usage tips ('Use where="1=1" + out_fields="*" to sample'). However, it doesn't explicitly state when not to use this tool versus alternatives like search_within or layer_info, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context about scoping to the user's identifier (anonymous IP, BYO key hash, or account ID), which goes beyond the annotations. No contradictions.

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

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

Three sentences, each earning its place: functionality, purpose/examples, and scope/relationship. No redundancy or fluff, and the main action is front-loaded.

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

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

For a simple tool with one optional parameter, the description covers its action, use cases, and scope. It lacks explicit detail about return values for missing keys, but given the simplicity and good annotations, this is not a significant 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?

Schema coverage is 100% and already documents the key parameter and the omit-to-list behavior. The description adds examples of typical keys (ticker, address, notes) but does not add significant 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 retrieves a value saved via remember or lists all saved keys when key is omitted. This specific verb+resource structure distinguishes it from sibling tools like remember and forget.

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

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

Provides clear use context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also mentions pairing with remember and forget, giving implicit guidance on alternatives, though not explicitly stating when not to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context about the mark_read side effect and the external mirror, plus the return payload fields. No contradiction with annotations.

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

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

Four sentences deliver the core purpose, return shape, filtering options, and an alternative access method. It is front-loaded and without fluff.

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

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

No output schema exists, but the description covers what each returned alert contains, how filtering works, mark_read behavior, and the mirror URL. This is sufficient for a read tool with rich annotations, though it doesn't explicitly differentiate from recent_changes.

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

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

Input schema covers 100% of parameters with descriptions. The description adds a concrete type example ('sec_8k') and explains mark_read's effect on subsequent calls, but most parameter details are already in 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 pulls fired events from the subscription feed and returns recent alerts with source, citation_uri, and payload. It is specific about the resource (alerts feed) and distinct from sibling tools like recent_changes or list_subscriptions, though it doesn't name them.

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

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

It gives context for when to use: for polling alerts, with filters for type and since, and notes the same feed is available as a GET endpoint for scripts. No explicit exclusions or alternatives are mentioned, but the context is clear.

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

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

The description discloses detailed behavioral traits beyond annotations: it fans out to SEC EDGAR, GDELT→GNews fallback (specifying GDELT preferred, GNews on rate-limit or 5xx), and the USPTO patents source with a soft-fail due to the PatentsView API sunset. It also mentions parallel execution and the output structure. No contradiction with the readOnly/idempotent/non-destructive 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 appropriately sized for the tool's complexity. It front-loads with illustrative query phrases, then covers behavior, parameters, output, and alternatives. The list of example queries is somewhat redundant, but every sentence contributes useful information. It reads as a well-structured, informative paragraph rather than being overly verbose.

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

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

Given the lack of an output schema, the description adequately explains the return value: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers the date handling, fallback logic, source list, and an explicit alternative. This provides sufficient context for an agent to invoke the tool correctly and understand 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 coverage is 100%, but the description adds practical meaning: it explains that `since` accepts ISO dates or relative shorthand, gives examples ('7d', '30d', '3m', '1y'), and recommends '30d' or '1m' for typical monitoring. It also reinforces the `value` parameter's ticker/CIK formats. This goes beyond the terse schema descriptions, though the schema already covers the basics.

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 in the last N days/weeks/months' and enumerates the specific sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes itself from the sibling entity_profile tool by specifying when to use that alternative. The verb is implied through 'change feed' (retrieval), and the resource is well-defined.

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 says 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window,' providing an explicit alternative. It also implies the intended use case through query examples like 'what's new with X' and notes the benefit of 'ONE parallel call,' which helps an agent decide when to use this tool.

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

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

Beyond the annotations (idempotent, non-destructive), the description discloses key behavioral traits: key-value storage scoped by identifier, persistence across sessions for authenticated users, 24-hour retention for anonymous sessions, and pairing with recall/forget. It does not specify overwrite behavior for existing keys, which is a minor gap.

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

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

Three sentences, each earning its place: purpose, usage examples, and persistence details. The description is front-loaded with the core action and avoids redundancy, making it efficient and easy 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?

For a simple 2-parameter tool with a comprehensive schema and helpful annotations, the description covers the essential aspects: what to save, when to save, how it persists, and how it relates to recall and forget. No output schema is necessary for a store operation, so the lack of return-value documentation is not a 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?

Both parameters are fully described in the schema with examples. The description adds the 'key-value pair' concept and scoping context, but does not provide new parameter semantics beyond what the schema already offers. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with the verb 'Save' plus the resource ('data the agent will need to reuse later'). It distinguishes from siblings by explicitly mentioning recall and forget, making its role in the memory lifecycle 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 when-to-use guidance ('Use when you discover something worth carrying forward') with concrete examples. It also names the complementary tools (recall, forget) and notes persistence differences between authenticated and anonymous sessions, giving clear context for choosing 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?

The annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral context: cascading lookups across multiple endpoints, graceful degradation (LEI/FIGI unavailable but EDGAR still returns), explicit 'unresolved' field, and source labeling for each identifier. This goes well 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 somewhat long but well-structured: it opens with example queries, then a clear one-sentence purpose, followed by bullet-point details for each supported type. Every sentence adds value, though some details (e.g., the full list of identifiers for company) could arguably be in the schema. Still, it remains readable and front-loaded.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns: identifiers with source labels, an unresolved list for failures, and fallback behavior. It covers all supported types, input formats, and edge cases (ISIN, graceful degradation). The agent has enough information to use the tool correctly 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?

Schema description coverage is 100% (both parameters described). The description adds substantial meaning beyond the schema: it explains the resolution logic for each type (e.g., 'company' returns CIK, ticker, LEI, FIGI; 'drug' returns RxCUI, ingredient, brand), the input formats accepted (ticker, CIK, ISIN, name for company), and special behavior like ISIN-to-LEI mapping. This greatly aids correct parameter usage.

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

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

The description clearly states the tool resolves names to canonical/official identifiers, with specific verb 'resolve' and resource 'name to IDs'. It starts with numerous example queries that make the purpose immediately obvious. It distinguishes from siblings like entity_profile and compare_entities by focusing on the identification step before profile lookups.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also details supported types (company, drug) and what each returns, helping the agent decide when to call this tool. It does not explicitly state when not to use it, but the context is clear enough that if you already have an ID, other tools like entity_profile are more appropriate.

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, and idempotent, so the safety profile is covered. The description adds valuable behavioral context: it reveals internal delegation to ai_visibility_check, states it ranks by score, and discloses the returned fields (score, confidence, signal density), which is especially useful since there is no output schema.

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

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

Four concise sentences with a clear front-loaded purpose. The only minor redundancy is 'ranks by score' in sentence two and 'ranked list with score' in the final sentence, but overall each sentence provides distinct value (purpose, behavior, use case, output).

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

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

With no output schema, the description adequately covers return values ('ranked list with score, confidence, signal density per entity'). Combined with the detailed input schema and rich annotations, it gives the agent enough to decide when and how to call the tool, though it omits any note about cost/rate implications of multi-model probing.

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 aligns 'your brand + N competitors' with the 'entities' parameter and mentions first-entry-as-subject, but this largely mirrors the schema's own text and adds no new parameter-level 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?

Description opens with 'Compare AI visibility across multiple entities side-by-side', using a specific verb and resource. It clearly distinguishes itself from the sibling ai_visibility_check by stating it probes each entity and ranks them, rather than checking a single entity.

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

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

Provides a concrete use case: 'competitive AI-marketing audits' and a quoted example. It implies the multi-entity/competitor comparison use case but does not explicitly state when not to use it or name alternatives like compare_entities, 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description goes further by disclosing degraded behavior on partial failures: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This adds operational context beyond the annotations, such as latency and graceful degradation.

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 opens with the purpose, lists data sources, gives usage triggers, explains ecosystem scope, and details failure behavior. Every sentence contributes useful information without fluff or repetition, making it appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description enumerates the exact return fields (summary block with is_latest, license, bundle sizes, etc., plus per-advisory details, links, and recent alternative versions), covering both success and failure cases. This completeness, combined with the strong annotations, fully equips an agent to reason about tool behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. Both parameters (package and version) are already fully described in the schema, including scoped packages and the version default. The description does not add significant new semantic detail beyond what the schema provides, just slightly reinforces the npm ecosystem context.

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 core function: a composite 'should I add this npm package to my project' check that consolidates deps.dev and bundlephobia data. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes itself from siblings by explicitly noting it is NPM-only in v1 and pointing to deps.dev:version for other ecosystems.

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

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

Provides explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This covers both when to use and when not to use with alternative 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, openWorldHint, idempotentHint, and non-destructive behavior, covering the safety profile. The description adds behavioral context by specifying the exact return fields (name, summary, record_count, owner/org, Feature Service url) and the intended downstream usage, which goes beyond the annotations.

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

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

The description is two sentences long, front-loaded with the action and scope, and includes essential details about return values and downstream usage. Every sentence earns its place with no redundancy or fluff.

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

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

This is a simple, read-only search tool with only 3 well-documented parameters and rich annotations. The description provides the return fields and downstream tool guidance, making it complete for an agent to select and invoke the tool. An output schema is absent, but the description explicitly lists the return fields, which compensates.

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

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

The input schema has 100% description coverage for all parameters (query, limit, org_id), so the schema already documents them well. The description adds no additional parameter-level meaning beyond the schema; it only reiterates keyword search and the return payload.

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

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

The description clearly states the tool searches City of Kinston GIS open geospatial datasets by keyword, which is a specific verb+resource+scope. It also distinguishes from siblings by explicitly mentioning the return of Feature Service URLs for use with query_layer/layer_info.

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

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

The description gives clear context: use this to discover datasets and obtain URLs for downstream tools. It names query_layer and layer_info as the tools to pass the returned URL to, which is strong usage guidance. However, it does not explicitly state when not to use this tool or mention alternatives for similar searches.

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

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

Beyond the read-only/idempotent annotations, the description discloses the internal search mechanics (BGE-base-en embeddings, cosine similarity, 500-char overlapping windows), the 200K character cap with truncation flagging, and the exact return elements (top-N passages with character offsets and similarity scores). This gives the agent a clear model of tool behavior.

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

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

The description is four sentences, each serving a distinct purpose: what it does, when to use it, how it pairs with a sibling, and technical implementation details. It is front-loaded with the core action and avoids redundancy, though it is slightly longer than ideal, 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 fully explains what the tool returns (passages, character offsets, similarity scores) and handles edge cases (200K truncation flagged). It also situates the tool within a larger workflow (fetch via gateway, ground over passages), making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by explaining that 'text' should be a fetched record (with examples like SEC 10-K body), reinforcing the expected usage, and noting truncation behavior for long inputs. It doesn't significantly expand parameter meaning beyond the schema, but the contextual framing justifies 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 clearly identifies the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the resource (a fetched record) and the action (semantic search), and distinguishes itself from siblings by emphasizing that the text is already pulled by the agent, not fetched via the gateway.

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

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

Usage guidance is explicit: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also directly names a complementary sibling, ask_pipeworx_grounded, and explains how to combine them, which is more concrete than generic 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=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it requires an OAuth account, mentions that anonymous and BYO users cannot persist subscriptions, details SMS verification and the 10/day cap, and states that webhooks auto-disable after 10 consecutive failing runs. This enriches the safety and operational profile without contradicting the annotations.

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

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

The description is dense and packed with information, but it remains well-structured with a clear progression: purpose, requirements, types, and delivery channels. While longer than ideal, every sentence contributes value, and the front-loaded opening sentence immediately clarifies the core action. A slightly more organized layout (e.g., bullets) could improve scannability, but the current form is acceptable.

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

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

Given the tool's complexity (multiple subscription types, nested params, delivery options) and the absence of an output schema, the description is quite complete. It covers return values (subscription id and webhook secret), prerequisites, constraints, and operational details like auto-disabling. Minor gaps include any hard limits on the number of subscriptions or behavior for duplicate subscriptions, but the idempotentHint helps fill that 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?

Even though schema description coverage is 100%, the description adds significant depth. It gives concrete examples for each type (e.g., "sec_8k" with items:["5.02"] for officer changes, "polymarket_edge" with topic:"fed") and elaborates on delivery channel specifics like the one-time webhook signing secret and the validation rules. This goes well beyond the schema's already detailed property descriptions.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and provides specific subscription types with examples.

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

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

The description provides clear context on when to use the tool (to set up proactive monitoring) and includes prerequisites like requiring a Pipeworx OAuth account. It also hints at alternatives by noting that feed events can be pulled via recent_alerts or the registry URL, but it does not explicitly contrast with sibling tools like list_subscriptions or unsubscribe.

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 behavioral context: it draws from the live catalog of thousands of tools, returns category-bucketed example questions, and allows optional topic focusing. It also clarifies that omitting the topic returns a full spread, which goes beyond the annotations.

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

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

The description is three dense sentences that front-load example queries, then explain purpose, return value, parameter behavior, and usage. Every sentence earns its place with no filler or redundancy.

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

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

For a read-only onboarding tool with one optional parameter and no output schema, the description is complete: it explains what the tool does, what it returns, when to use it, and how to vary the parameter. The lack of an output schema is compensated by the detailed description of the return format (category-bucketed example questions with tool+argument shape).

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 description already covers the `topic` parameter fully (100% coverage). The tool description adds examples ('finance', 'pharma', 'betting') and explains the effect of passing vs omitting the parameter (focus vs full spread), providing additional meaning beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape for each. It distinguishes itself from sibling tools like discover_tools by focusing on 'what is worth asking' and how to call meta-tools, providing a specific verb+resource+scope.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools. It provides clear context for when to use it, though it does not explicitly state when not to use it or name alternative tools for comparison.

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

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

The description goes beyond annotations by disclosing that ownership is enforced and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This complements the annotations (idempotentHint, destructiveHint) nicely, adding meaningful behavioral context.

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

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

Two sentences, zero fluff. The first sentence states the core action, the second adds crucial behavioral nuance. Perfectly sized.

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 tool with rich annotations, the description covers purpose, constraint, and effect on data. No output schema exists, but the return value of a cancel action is typically trivial, so this is 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?

The input schema already fully documents the 'id' parameter as a UUID returned by subscribe, with 100% coverage. The description merely restates 'by id' without adding new semantics, so the schema carries the burden.

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

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

The description clearly states the action (Cancel) and the resource (subscription by id). It distinguishes itself from sibling tools like subscribe and list_subscriptions by specifying the ownership constraint and the soft-deactivation behavior.

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 that this tool cancels subscriptions and only allows cancellation of your own subscriptions. It doesn't explicitly reference alternatives or when-not-to-use, but the context is sufficient for an agent to know when to invoke 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses crucial behaviors: the two routing paths, verdict meanings, the critical caveat that could_not_verify is not evidence and must not be shown as one, the exact percent-delta math for financial claims, and the pipeworx:// citation format. This is substantial 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 long but well-organized: trigger phrases, core purpose, processing paths, return values, caveats, and efficiency note. Each sentence contributes useful information, though it could be slightly tightened by trimming redundant phrase examples. It is front-loaded with the central purpose and readability is good.

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 (two paths, multiple verdicts, no output schema), the description adequately covers the return shape, error handling (could_not_verify vs unsupported), and evaluation criteria. It doesn't detail every possible source or error code, but it provides enough for an agent to invoke and interpret results correctly.

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

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

The schema already covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra value by explaining tolerance_pct's override semantics, default cap of 5, and the recommendation to set 1-2 for hallucination detection. It also provides concrete examples for the claim parameter, 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 clearly defines the tool as 'natural-language claim verification against authoritative sources' with explicit trigger phrases and examples. It distinguishes between two processing paths (SEC EDGAR financial vs grounded pipeline for other claims), which differentiates it from sibling tools like ask_pipeworx and deep_research.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains that non-financial claims fall through to the grounded pipeline. However, it does not name specific sibling tools as alternatives or provide explicit exclusion criteria (e.g., when to use deep_research instead), 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.