Arcgis Charleston

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context about cost/auth (BYO Anthropic key, direct billing) and return structure, which goes beyond the annotations. It does not mention rate limits or failure modes, but for a read-only probe this is adequate.

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

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

The description is compact (four sentences) and front-loaded with the core action and output. Every sentence adds value: function, default/cost behavior, return format, and use cases. No fluff or redundancy.

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

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

Despite having no output schema, the description clearly explains the return payload (per-model score, confidence, signals, raw_response, plus combined view). It covers default behavior, optional authentication, and typical use cases. For a read-only tool with simple parameters, this is complete.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description largely restates what the schema already says (default model, _apiKey needed for Anthropic) without adding deeper semantics beyond that baseline. Thus a 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 ('probe') and resource ('one or more LLMs') and clearly states the output (visibility score 0-100 per model). It distinguishes itself from siblings by focusing on cross-model visibility scoring with a defined return format, making it distinct from tools like scan_competitor_ai_presence.

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

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

The description gives clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which implies when to use it. It does not explicitly mention alternatives or exclusions, so it falls short of a 5 but provides context beyond a mere statement of function.

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

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

Annotations already declare readOnly/idempotent. The description adds meaningful behavioral context: routes to 5,462 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. This 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 long but well-structured and front-loaded with the most important directive. Every sentence adds value: preference, mechanics, triggers, examples, escalation path. A bit verbose, but not wasteful.

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

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

With no output schema, the description explains the return format (structured answer with citations), routing behavior, usage scope, and alternatives. It is comprehensive for an AI agent to know when and how to invoke the tool.

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

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

Schema description covers all six parameters with 100% coverage, explaining the main 'question' parameter and its aliases. The description adds example queries but no new semantic details 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 explicitly states the tool routes factual questions to a large set of verified sources and returns structured answers with citations. It uses specific verbs and distinguishes from siblings by naming ask_pipeworx_grounded 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?

The description gives explicit when-to-use guidance: prefer over web search, use as default entry point, step up only for grounded or broad research. It provides trigger phrases, examples, and clarifies that breaking news is already handled.

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 this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it is a full working router with no fallback, its behavior may change live during candidate tests, and currently matches ask_pipeworx exactly. This goes beyond annotation basics, though it doesn't detail response shape specifics.

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 purpose and includes necessary details about equivalence, experimental status, and current state. It is slightly verbose (e.g., specific date and tool count) but every sentence contributes to understanding, making it well-structured for its 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?

Given no output schema, the description adequately covers what the tool does, its relationship to ask_pipeworx, and its current status. It omits specific response structure but the reference to 'same response shape' and 'universal router' gives sufficient context 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?

Schema description coverage is 100%; all 6 parameters are aliases for 'question' and are fully described in the schema. The description adds no additional parameter detail beyond confirming 'same arguments' as ask_pipeworx, 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 clearly defines the tool as a beta version of ask_pipeworx, a universal router with 5,462 tools, and distinguishes it from the stable version by its experimental routing improvements. It uses specific verbs ('use', 'routes') and references the sibling tool, making its purpose unambiguous.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also indicates the alternative (stable ask_pipeworx) and explains that results are compared against the stable router, providing clear usage context and exclusions.

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

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

Annotations already mark readOnly/idempotent/non-destructive, but the description adds essential behavioral context: it only uses tool result content, returns verbatim evidence, and can refuse with specific reason codes such as 'not_in_source' and 'data_truncated'. It also discloses the extra LLM call cost, going well beyond annotation hints.

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

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

The description is front-loaded with the core value proposition, then proceeds through mechanism, return format, failure modes, use cases, and cost tradeoff in a logical order. Every sentence earns its place—no fluff, no repetition, and it remains readable despite its length.

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

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

With no output schema, the description fully specifies what the tool returns on success and every refusal reason, including the exact structure with null fields. It also explains the underlying routing scale (5,462 tools) and the cost implication, making the tool's behavior completely self-contained for an agent.

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

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

The input schema fully documents all 6 parameters (5 aliases plus question) at 100% coverage, so the description doesn't need to add parameter-level detail. The description implies the main argument is a natural-language question, but that's already stated in the schema, so no value is added beyond the structural baseline.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' with a specific mechanism: route through the same tool network as ask_pipeworx, fetch data, then extract answers only from tool results. It also distinguishes itself from siblings by naming the return contract and the explicit refusal 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives a when-not-to-use directive: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff in plain terms.

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

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

Even though annotations already declare readOnly=true, openWorld=true, and idempotent=true, the description adds extensive behavioral detail: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return 'market_closed_or_inactive', wide spreads flag 'illiquid_wide_spread', and cancellation rules parse refund_50_50 scenarios. This goes far beyond annotation defaults.

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 densely packed with information. Every section (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) earns its place and uses clear headers to aid scanning. It is verbose but not wasteful; complexity warrants the detail.

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

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

With no output schema, the description compensates by detailing response shape (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, suggestions), parent-event extractor, news fallback fields, and resolution-rule risk. It covers edge cases exhaustively, making it complete for an agent to act on.

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 does not add much beyond schema for parameters; it reiterates the market input forms and provides fan-out examples, but these are illustrative rather than adding new semantic constraints. The schema already documents depth and include_raw adequately.

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 differentiates from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on per-bet research and evidence gathering. The use-case examples ('should I bet on X') further cement the purpose.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context, but it does not mention when not to use or name alternative tools, so it falls short of a 5.

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

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

The description adds substantial context beyond the read-only/idempotent annotations: it details data sources (SEC EDGAR/XBRL, FAERS, FDA), specific metrics (revenue, net income, cash, long-term debt, adverse-event counts, trial counts), sorting by primary metric, and citation URIs. It also highlights correct handling of off-calendar fiscal years, providing robust behavioral insight.

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

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

The description is well-structured and information-dense, starting with trigger phrases, then core function, usage preference, per-type details, and output format. Every sentence earns its place, with no wasted words.

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

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

For a tool with two parameters and no output schema, the description fully covers purpose, data sources, sorting behavior, return format (paired data + citation URIs), and even the efficiency gain over sequential lookups. It also addresses edge cases like off-calendar fiscal years, making it 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 coverage is 100% and already describes type and values clearly. The description adds semantic meaning by explaining what each type pulls (10-K financials vs FAERS/FDA/trial counts) and how results are sorted, which goes beyond the schema but not excessively, given the schema's high quality.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It lists trigger phrases ('Compare X and Y', 'rank these companies') and contrasts with sequential single-pack lookups, clearly distinguishing it from single-entity tools like entity_profile.

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 indicates when to use the tool (comparing entities, ranking) and explicitly prefers it over sequential single-pack lookups. However, it does not mention alternative tools for cases where deep qualitative research is needed, so it stops short of fully explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description goes much further: account requirement, parallel tool routing, gaps[] behavior, latency, citation fetchability, semantic excerpting, contradiction detection. No contradictions with annotations.

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

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

Long but densely informative; every sentence earns its place given the tool's complexity and need to differentiate from siblings. The account requirement is front-loaded, but the prose could still be trimmed slightly.

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 covers input, output packet shape, limitations, latency, auth, and alternatives comprehensively. It answers the likely questions an agent has for selecting and invoking this tool.

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

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

The schema already documents both params at 100% coverage; description adds practical depth semantics (paid tier for thorough, gap recovery, contradiction scans) and guidance on question phrasing. These enrich meaning without conflicting with 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?

Clearly identifies a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx. The scope (broad/multi-part questions over structured data) is concrete and non-tautological.

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 names when to use: broad/multi-part questions over structured data; and when not to: if not signed in, single lookup, breaking/current news, each pointing to ask_pipeworx. Also gives examples of appropriate questions and paid-tier requirements.

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 and idempotent, and the description adds valuable behavioral details: it returns top-N tools with full input schemas and curated examples, ready for direct invocation without a second lookup. No contradictions with annotations; the description enhances transparency beyond the structured fields.

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

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

The description is moderately sized but efficiently structured: the opening sentence is a clear summary, the domain list provides useful coverage context, and the final sentence gives an actionable usage directive. It is slightly verbose due to the long list of domains, but every part serves a 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?

Since there is no output schema, the description must explain the return format, and it does: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... ready to call directly.' It also covers the key decision of when to use the tool, making it complete for an agent to decide and invoke.

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 every parameter, including aliases and examples. The description adds general guidance that the query is a natural language description, but it does not significantly enrich parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource that clearly states the tool's purpose. It further distinguishes itself from siblings by emphasizing its role as a discovery meta-tool and explicitly saying 'Call this FIRST when you have many tools available.'

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST...' This clearly indicates when to prefer this tool over directly answering or using other tools, and implies alternative behavior for specific answers.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), discloses the patents API sunset and soft-fail behavior, and specifies the fallback chain (GDELT→GNews). This significantly exceeds the annotation coverage.

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 well-structured, front-loaded with example user queries and the core action. It includes many details (return fields, source list, failure modes) that justify the length. However, the long list of example phrasings could be condensed without losing key information, making it slightly overlong for its 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 the tool's complexity (returns data from 5+ sources) and the absence of an output schema, the description is remarkably complete. It enumerates all return components (cik, company_name, recent_filings with URIs, fundamentals fields, patents, news, LEI), explains the patents API sunset, and clarifies the input restriction. No critical context is missing.

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

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

The input schema already provides 100% description coverage for both parameters. The description adds value by giving concrete examples ('AAPL', '0000320193'), emphasizing 'zero-padded CIK', and explicitly restating the 'names not supported' constraint. While not essential, these examples help disambiguate format requirements.

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: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs (tell me, research, brief me) and explicitly distinguishes from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is requested.

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

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

The description gives explicit when-to-use guidance with example user intents ('Tell me about X', 'research Acme', 'brief me on Tesla'), and provides an explicit exclusion: 'names not supported (use resolve_entity first if you only have a name).' It clearly names an alternative tool and states the preference over chained 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 provide destructiveHint and idempotentHint. The description adds context about what is deleted (memory by key) and why (stale context, sensitive data), going beyond the annotations. It doesn't contradict them.

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

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

Three sentences, all valuable: purpose, usage context, and sibling relationship. No filler, well 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 one-parameter tool with full schema coverage and no output schema, the description is complete. It covers what, when, and related tools, leaving no critical gaps.

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

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

The schema covers 100% of parameters with a clear description ('Memory key to delete'). The description adds no additional meaning beyond 'by key', 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 tool deletes a previously stored memory by key, using the specific verb 'delete' and identifying the resource. It also distinguishes itself from sibling tools by explicitly mentioning 'remember' and 'recall' as complementary tools.

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

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

The description provides explicit when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with remember and recall, giving clear relational context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: the tool fetches the page, extracts key elements, and emits a standard markdown text blob ready to drop at site-root. This goes beyond the annotation hints.

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

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

The description is two sentences, front-loaded with the primary purpose and process, followed by use cases. Every sentence earns its place with no redundancy or filler.

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

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

For a tool with two simple parameters and no output schema, the description is highly complete. It explains the output format (single text blob for site-root), the underlying process, and typical use cases, giving the agent everything needed to select and 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 input schema fully describes both parameters (url and max_links) with examples and defaults. The description reinforces that url can be any URL but adds little beyond the schema. Since schema coverage is 100%, 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 uses a specific verb-resource pair ('Generate a production-ready llms.txt file') and explains the exact process (fetches, extracts title/description/key links, emits markdown). It distinguishes from siblings like scan_competitor_ai_presence by focusing on any URL and AI crawler indexing.

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

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

The description explicitly lists three concrete use cases: getting a client's site indexed, drafting llms.txt for one's own project, and auditing a competitor's site. It does not mention when to avoid this tool or name alternatives, but the context is sufficiently clear.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds context about the returned schema components, which is helpful, but does not disclose additional behavioral traits such as API requirements, error cases, or response structure.

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

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

A single concise sentence that front-loads the action ('Get schema') and lists the key return fields. There is no redundancy or irrelevant detail, and every word contributes to the tool's 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?

With no output schema, the description appropriately enumerates the expected return data (fields, geometry type, record count, capabilities). It could be more exhaustive about the response structure, but for a low-complexity read-only operation, it is sufficiently complete.

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

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

The sole parameter 'url' is fully documented in the schema with a description and example, providing 100% coverage. The description adds no further nuance beyond referencing the URL, so it matches the baseline for high schema coverage.

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

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

The description clearly states the tool's function: retrieving schema metadata from an ArcGIS Feature/Map Service layer. It lists specific return values (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that retrieve actual features.

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

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

The description implies the tool is for inspecting layer metadata before querying, but it does not explicitly state when to use it instead of alternatives such as query_layer or search_within. No exclusions or alternative tools are mentioned.

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, openWorldHint, idempotentHint, and destructiveHint:false. The description adds context beyond these, such as the fact that it returns the caller's own subscriptions, only active ones by default, and the specific fields returned. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the action and result. The second sentence adds use-case guidance, and no words are wasted. It is appropriately sized for the tool's simplicity.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers what it does, the return fields, and when to use it. The annotations cover safety aspects, making the overall description complete for an AI 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?

The input schema has 100% coverage for the single optional parameter include_inactive, with a description in the schema itself. The description's mention of 'active subscriptions' provides some context, but it does not need to add more since the schema already fully explains the parameter.

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

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

The description opens with 'List the caller's active subscriptions', which is a specific verb+resource combination that clearly states what the tool does. It also lists the return fields, distinguishing it from sibling tools like subscribe/unsubscribe by focusing on the read operation.

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

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

'Use this to review what you're monitoring before adding more or to find an id to cancel' explicitly states when to use this tool, and implicitly contrasts it with adding (subscribe) and canceling (unsubscribe). This gives the agent clear guidance on choosing this tool over alternatives.

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

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

Annotations are all false, so the description carries the full transparency burden. It discloses the claim_token follow-up flow, rate limit (5 per identifier per day), free usage, and that the team reads digests daily. This goes well beyond annotations and leaves no contradiction.

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

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

The description is a single dense paragraph with several clauses, some minor details (e.g., 'The team reads digests daily and signal directly affects roadmap') that are not essential for invocation. However, it is front-loaded with the core purpose and flows logically from when to use to how to use. Slight over-length keeps it from a 5.

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 4 parameters, 0 required, a nested context object, and no output schema, the description compensates by explaining exactly what happens when filing without an account (claim_token returned), how to later retrieve status, and the exact conditions for use. It is complete enough for an agent to invoke correctly and even handle the follow-up flow.

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

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

Schema covers 100% of parameters, but the description adds significant practical semantics: it explains the claim_token round-trip (pass it back with no other arguments to read status) and guides message content ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches the plain schema definitions.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback categories and is immediately distinguishable from sibling tools like ask_pipeworx or discover_tools, which serve different purposes.

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

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

It explicitly states when to use: '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 an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is a textbook example of 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 read-only, idempotent, non-destructive, and open-world. The description adds meaningful context: self-aggregating, derived from CF analytics-engine, no PII, and caching behavior (5min-1h), going well beyond the structured hints.

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

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

Every sentence earns its place: opening definition, return values, use cases, data source/privacy, caching. Well-structured and front-loaded with the core purpose, no fluff or repetition.

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

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

For a simple one-parameter tool with rich annotations and no output schema, the description fully covers purpose, return shape, use cases, data provenance, privacy, and caching. It is sufficiently complete for an agent to decide when and how to invoke it.

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

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

Schema covers 100% of the single parameter 'window' with enum and a baseline description. The description adds comparative semantics: shorter windows highlight current trends, longer windows show steady-state demand, which enriches 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 returns top tools, packs, and call volume over recent windows, and frames it as 'what other AI agents are calling on Pipeworx right now.' This specific verb+'resource' framing distinguishes it from sibling tools like discover_tools 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?

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). While it doesn't name alternative tools or state when not to use it, 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses key behavioral traits: it performs a fill check against live CLOB depth, warns that realizable_edge_pp <= 0 means the arb is not tradeable, explains how the partition filter drops placeholder slugs, and surfaces skipped_low_similarity counts. No contradictions with annotations.

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

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

Although lengthy, the description is well-organized with semantic sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded core functionality. Every sentence provides necessary operational detail for a complex tool; 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?

Given the tool's high complexity, the absence of an output schema, and the presence of rich sibling tools, the description is strikingly complete. It defines the response structure (opportunities[], partition_check fields), explains edge cases (fill check, placeholder filtering), and references related tools for further context. No critical gaps.

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

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

The input schema already provides descriptions for event and topic with examples, but the tool description goes further by explaining exactly what each mode does with the parameter, how it walks child markets, what checks are performed, and what output fields to expect. This adds substantial 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 opens with a precise verb-object pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes among three modes (trending_scan, event, topic) and differentiates itself from sibling tools by focusing on arbitrage detection and fill-check pricing, not just edge listing.

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

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

It explicitly states when to use no args, when to use event, and when to use topic, with concrete examples. It also directs users to polymarket_fill_risk for custom sizing, naming an alternative tool. The guidance is actionable and covers mode selection and trade execution decisions.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds deep behavioral context: it details the five model families with their formulas (lognormal barrier, GDELT ratio), per-sport alpha corrections, placeholder-slug filters, gate relaxation history, the 24h-move warning, the caching key structure, and the diagnostics funnel. This significantly enriches the agent's understanding of what the tool does internally.

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

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

The description is long but every section earns its place. It is front-loaded with the core purpose, then organized into labeled blocks: model families, opportunity fields, tradeable-edge knobs, response top-level, and caching. The use of uppercase labels and structured lists makes it scannable despite the density, and there is no redundant filler.

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

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

With no output schema, the description must describe the response structure fully, and it does so comprehensively: it lists the top-level keys (by_segment, fed_candidates/fed_note, _diagnostics), explains the contents of each segment, enumerates the fields carried by every opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and describes the diagnostics funnel. The 9 parameters are all explained in the schema and the description ties them to the filtering logic. This is a complete, self-sufficient description.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the motivation behind the knobs, e.g., 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade' for slippage_pp, and by clarifying that min_partition_leg_kelly works per-leg inside top_legs because parent-level Kelly is zero by design. This contextual info goes beyond the schema's structural descriptions.

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

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

The description opens with a precise verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and differentiates from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreements. The response segments (model_driven, structural_arbitrage, concentrated_longshot) further clarify scope.

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

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

The description clearly provides the usage context ('for what should I bet on today', discovery without paging hundreds of markets) and explains how knobs like min_liquidity/max_spread_pp filter opportunities. However, it stops short of explicitly naming when to prefer alternatives or when not to use this tool, so it lacks the explicit exclusion/alternative guidance needed for a 5.

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

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

Annotations already declare readOnly/idempotent/destructive hints, and the description adds substantial behavioral context: snapshot TTL limits, cache-miss gaps meaning no scan, decay computed on daily closes (not intraday), and signed edge values with negative = SELL YES. No contradiction with annotations.

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

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

The description is lengthy but well-structured with labeled sections (RESPONSE, LIMITS) and every sentence provides necessary detail for a complex telemetry tool. It is front-loaded with the core purpose. Slightly verbose but justified by the output 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 thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), semantics of each field, and limitations (TTL, cache-miss gaps, daily closes vs intraday). This is complete for an agent to understand what the tool returns and its constraints.

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

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

Schema coverage is 100% and both parameters have descriptions. The description repeats defaults ('default 14', 'default 1wk') and adds the valid window values ('24hr | 1wk | 1mo') that match the schema. It adds slight interpretive context ('lookback', 'snapshot family') but does not significantly go 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?

Description states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage (arbitrage).

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

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

Description implies usage context with the contrast 'a fresh wide edge and a 3-week-old wide edge are different trades' and explains the value of expired opportunities ('median lifespan is your competition clock'). It does not explicitly name alternative tools or state when not to use, 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?

Annotations already mark readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that. It explains that the tool 'walks the ladder,' details both single-market and basket modes, clarifies how size_usd is interpreted differently per mode, and enumerates all return fields including edge cases like verdict and forced_directional_risk. This goes far beyond the annotations' safety hints and adds genuine context without contradiction.

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

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

The description is long but every sentence earns its place. It uses a clear two-mode structure with explicit labels (SINGLE-MARKET, BASKET) and all-caps for the critical usage directive. The one-line summary is front-loaded, followed by detailed yet scannable instructions, making it highly effective despite its length.

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

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

With no output schema, the description compensates fully by listing every return field for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.) and defining edge cases like thin_legs and forced_directional_risk. It also addresses the 0-required-parameter situation by requiring one of market or event, and clarifies the absence of enums via explicit side values. The practical warning about partial basket fills rounds out the contextual picture.

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

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

Although schema description coverage is 100%, the description adds significant meaning to each parameter. It defines side defaults per mode, explains auto-detection in basket mode, and clarifies the polymorphic semantics of size_usd (max spend for buys, target proceeds for sells, settlement notional for baskets). The clamp range and default value are also specified, enriching the bare 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 precise purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on executability and fill risk rather than just edge identification. The verb 'check' plus the resource 'live CLOB order-book depth' makes the purpose specific and actionable.

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 when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale—theoretical overround on thin books is not capturable and partial fills create unhedged directional risk—effectively teaching when not to rely on raw arbitrage signals. Naming sibling tools as alternatives exceeds the requirement.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior. The description adds substantial behavioral context: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type vs not), temporal_alignment fields, and skipped_cross_type/subtype counters. It discloses that most pre-mapped topics return warnings today, which is far beyond annotation coverage. 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?

The description is long but highly structured: it uses uppercase section labels ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') to organize dense content. Every sentence adds value and explains a nuanced aspect (compatibility warnings, temporal alignment, skipped pairs). While not brief, the structure and density justify its length for the tool's complexity.

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

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

The tool has no output schema and involves complex cross-venue matching. The description compensates by fully explaining the response structure (leg-by-leg prices, matched spread with top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and skipping mechanisms. It covers edge cases like non-equivalent bet shapes and temporal misalignment, making it highly complete for an agent to know 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 has 100% coverage with descriptions for each parameter. The description adds meaning beyond the schema by explaining how the parameters interact: topic auto-fetches a matching event on each venue, and explicit tickers override the topic-mapped side. It also clarifies the output implications for each mode, which the schema alone does not.

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 statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (spread between two venues), the action (compute/return), and distinguishes from sibling tools by focusing on cross-venue comparison. The two modes ('topic' and explicit tickers) further clarify scope.

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

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

The description explicitly describes TWO MODES and when to use each: 'topic' auto-fetches for macro shortcuts, while explicit `kalshi_event_ticker` + `polymarket_event_slug` allow custom pairings. It also warns that real cross-venue spreads are rarer than the shortcut list suggests ('pre-mapped ≠ tradeable'), giving practical usage guidance. However, it does not explicitly name alternative sibling 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: it states the return format ('attribute rows (and geometry)') and provides a sampling technique. 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?

Two sentences, front-loaded with the primary action and resource, then a useful usage tip. Every sentence earns its place with no fluff or repetition.

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

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

The tool has 6 parameters, no output schema, and is a read-only query operation. The description covers the purpose, key parameters, return format, and a sampling tip. Combined with the rich schema and annotations, this is sufficiently complete for an agent to use the tool correctly. It could mention error behavior or limit constraints, but the schema covers limit, and the description is adequate given the 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 description coverage is 100%, so the schema fully documents all parameters. The description restates parameter names (where, out_fields, order_by, limit, offset) and adds the note about 'SQL-like' and 'comma-separated', but these are also in the schema. The only additive semantic is the source of the URL (from search_datasets), which is minor. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It specifies the resource type and the action (query), and mentions it takes the URL from search_datasets, which differentiates it from sibling tools like layer_info or search_within. The return of attribute rows (and geometry) further clarifies purpose.

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

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

The description gives clear context: the URL comes from search_datasets, and it provides a sampling tip (where='1=1' + out_fields='*'). It implicitly distinguishes from metadata tools but does not explicitly exclude alternatives or state when not to use. Overall, clear usage context without exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context about scoping ('Scoped to your identifier') and the behavior of omitting the key (lists all). This goes beyond annotations without contradicting them.

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

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

The description is a single, well-structured paragraph that gets to the point immediately. Every sentence provides useful information: purpose, usage context, scoping, and relationship to siblings. No wasted words.

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

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

For a simple tool with rich annotations and full schema coverage, the description covers all essential aspects: what it does, when to use it, scoping, and integration with related tools. It doesn't detail return formats, but that is not critical for a key-value retrieval tool and the output schema is absent.

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

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

The input schema already provides a full description for the 'key' parameter (including the omit-to-list behavior), so schema coverage is 100%. The tool description repeats this information without adding new semantics, so it meets the baseline but adds no extra value.

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

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

The description opens with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and clearly distinguishes between two modes: retrieving by key and listing all keys. It explicitly contrasts with sibling tools 'remember' and 'forget', making the tool's role 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?

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples. It also names alternatives ('Pair with remember to save, forget to delete'), giving the agent a clear workflow and preventing confusion with siblings.

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

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

The annotations declare readOnlyHint=true and destructiveHint=false, implying no state changes. However, the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which describes a mutating side effect. This directly contradicts the readOnlyHint annotation.

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 adding essential information: purpose, return payload, filtering, and mark_read behavior, plus the HTTP alternative. It is front-loaded with the main action and contains no filler.

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

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

Given the 5-parameter tool without an output schema, the description covers return payload structure, filtering options, mark_read side effects, and offers an alternative access method. It lacks a note on ordering/pagination, but covers most necessary context well. The annotation contradiction somewhat undermines accuracy, but the description itself is fairly complete.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds a small amount of value by providing an example filter type ('sec_8k') and clarifying the consequence of mark_read (next call shows only newer events), but it does not significantly exceed the schema's own descriptions.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull fired events), and provides details about return payload. It differentiates from siblings like list_subscriptions by focusing on alert events rather than subscription metadata.

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 usage context: 'Polls work fine' suggests appropriate use cases, and it gives an explicit alternative for scripts/dashboards via the HTTP endpoint. It does not explicitly compare to sibling tools like recent_changes, but the guidance is otherwise 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?

Despite annotations indicating read-only, open-world, and idempotent behavior, the description adds significant detail: it fans out to SEC EDGAR, GDELT with GNews fallback on rate limits/5xx, and USPTO with a soft-fail due to PatentsView sunset. It also mentions structured output and citation URIs, going well beyond the annotations.

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

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

The description is fairly dense but well-organized: it front-loads user-facing examples, then explains sources and fallbacks, parameter formats, output structure, and ends with an alternative tool. Each clause contributes useful information, and there is minimal 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 complexity of multiple data sources, fallbacks, and no output schema, the description fully compensates. It describes the return shape (changes[] grouped by source, total_changes count, citation URIs), notes the PatentsView API sunset soft-fail, and gives an explicit alternative for static profiles.

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 good parameter descriptions. The description adds extra value by giving concrete examples for `since` (ISO or relative shorthand), recommending '30d' for typical monitoring, and clarifying the `value` parameter accepts ticker or zero-padded CIK.

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 provides a change feed for a company over a time window, with specific example queries like "What's new with X". It explicitly distinguishes from entity_profile by naming the alternative for static profiles.

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

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

Provides concrete natural-language triggers and explicitly tells users to use entity_profile when they need a static profile instead of recent changes. Also explains the source fallback behavior, which informs when the tool is reliable.

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

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

Annotations already cover idempotency and non-destructiveness. The description adds valuable behavioral context, including key-value scoping by identifier, persistence differences for authenticated versus anonymous sessions, and relationship to recall/forget. It does not contradict annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by usage guidance and storage details. Every sentence adds value 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?

For a simple two-param tool with rich annotations and full schema coverage, this description covers purpose, usage, storage semantics, session behavior, and related tools. No critical information is missing.

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

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

Schema coverage is 100% with descriptive parameter text and examples. The description's mention of 'key-value pair' aligns with but does not significantly enhance the schema's parameter documentation. 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 function with a specific verb and resource: 'Save data the agent will need to reuse later.' It also distinguishes itself from sibling tools by explicitly pairing with 'recall to retrieve later, forget to delete,' making its role unique.

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 with concrete examples ('a resolved ticker, a target address, a user preference') and contrasts with alternatives by naming recall and forget. It also clarifies session-based behavior differences, which is actionable context.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds rich behavioral detail: exact data sources (SEC EDGAR, RxNorm), returned fields (ticker, CIK, RxCUI, ingredient, brand), citation URI format, and the internal multi-endpoint cascade. No contradiction with annotations.

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

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

The description is longer than a two-liner but every sentence contributes: examples, usage trigger, type-specific outputs, and internal behavior. It is well-structured with a clear lead, usage instruction, and type breakdown, though slightly dense.

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 specifying the exact output fields for each entity type, sources, and citation URIs. It also explains that the tool replaces 2-3 manual lookups, providing context on its internal complexity. This makes the tool predictable without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameters by mapping each enum value to its return fields (company → ticker+CIK, drug → RxCUI), giving concrete input examples, and noting auto-disambiguation for company inputs. This adds value beyond the schema.

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

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

The description clearly defines the tool as resolving a user-spoken name to a canonical identifier, with specific examples and supported types. It distinguishes itself from siblings by being the first step when an ID is needed, which differentiates it from tools like entity_profile or compare_entities.

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

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

The description explicitly states the trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also provides example queries to recognize the use case. However, it lacks explicit 'when not to use' guidance or named alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, lowering the bar. The description adds valuable context: it 'probes each entity with ai_visibility_check' (an internal tool call) and returns a ranked list with score, confidence, and signal density. This goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary action, followed by method and output, then a use case with an illustrative example. Every sentence contributes meaningfully, with 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?

Given there is no output schema, the description adequately explains the return format: 'ranked list with score, confidence, signal density per entity.' It covers purpose, method, and typical usage scenario. It does not address edge cases or prerequisites like the Anthropic API key, but those are already in the schema, and the tool is read-only and open-world, 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter-specific details; it only paraphrases the 'entities' parameter as 'your brand + N competitors,' which the schema already explains. Since the schema fully documents all parameters, the description provides no additional semantic value.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It further details the behavior (probes each entity, ranks by score, surfaces most/least recognized) and distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison.

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

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

The description gives clear context for use: 'Useful for competitive AI-marketing audits' and includes an example query. It implies that for a single entity one might use ai_visibility_check, but it does not explicitly name alternatives or state when not to use this tool. This is clear but not exhaustive.

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 important behavioral traits beyond the annotations: it mentions NPM ecosystem limitation, partial failures degrading gracefully, the 5-30s first-time bundlephobia measurement, and that a timeout will be listed in sources_failed. These details are not in the readOnly/idempotent annotations, adding significant 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 efficiently structured: it opens with the core purpose, then usage context, then the return shape, and ends with limitations and performance caveats. Despite its length, every sentence carries substantive information and avoids fluff.

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

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

Given there is no output schema, the description compensates by explicitly listing the returned fields (summary block with specific metrics, per-advisory detail, links, alternative versions). It also covers edge cases (timeouts, partial failures, ecosystem scope), making the tool's behavior fully understandable.

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

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

The input schema already provides 100% coverage of both parameters ('package' and 'version') with descriptions including defaults and scoped package support. The tool description adds no additional parameter semantics beyond what the schema already states, placing it at the baseline for high schema coverage.

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

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

The description clearly states the tool's function: a composite check for npm packages using deps.dev and bundlephobia. The verb 'scan' plus resource 'dependency' is specific, and the description differentiates it from the many sibling research tools by detailing its unique composite data sources and outputs.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. The description also gives a clear exclusion: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', indicating when not to use this tool and pointing to an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the tool's safety profile is known. The description adds useful behavioral context by listing the return fields (name, summary, record_count, owner/org, url) and the intended downstream action, going 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 two sentences: the first states the action and scope, the second states the return fields and the follow-up action. Every word earns its place, and the critical workflow hint is front-loaded in the second sentence. No filler or repetition.

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

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

For a search tool with no output schema, the description is remarkably complete. It names the input (keyword), output fields (name, summary, record_count, owner/org, url), and explicitly how to use the result (pass url to query_layer/layer_info). This makes the tool self-sufficient even without an output schema.

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

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

Input schema covers all 3 parameters with descriptions (query, limit, org_id) at 100% coverage, so baseline is 3. The description adds minimal new parameter semantics—it only reinforces that searching is by keyword, which is already in the schema. No additional detail about parameter behavior is provided.

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

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

Description clearly states it searches Charleston County GIS open geospatial datasets by keyword, gives examples (parcels, addresses, zoning), and differentiates itself from siblings by specifying the returned URL is for query_layer/layer_info. This is a specific verb+resource+scope with explicit sibling distinction.

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 tells the agent to pass the returned URL to query_layer/layer_info, establishing a workflow and implicitly indicating when to use this tool (discovery) versus alternatives (querying/inspecting). This provides clear when-to-use guidance and names alternative 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral detail beyond that: returns top-N passages with offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and truncates inputs over 200K chars with a flag. This enriches the agent's understanding of what happens during invocation.

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

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

Four sentences with no fluff. The core action comes first, followed by usage guidance, pairing with a sibling, and technical parameters. Every sentence contributes distinct information, and the structure supports quick comprehension.

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

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

Even without an output schema, the description explains the return format (top-N passages with character offsets and similarity scores), the technical mechanism (BGE embeddings, windowing), and edge-case behavior (truncation with flag). For a moderately complex tool with 3 parameters, this is fully sufficient 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?

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds value by explaining 'text' as 'the text you already pulled' and providing concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue'). These examples clarify the intended usage beyond the schema's generic descriptions.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this from sibling tools by emphasizing that it operates on already-fetched text rather than fetching new data, and explicitly contrasts with ask_pipeworx_grounded.

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

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

Explicit when-to-use guidance is provided: 'Use when the record is too big to cram into the prompt.' It also names the complementary tool (ask_pipeworx_grounded) and explains how the two should be chained, offering concrete context for selection versus alternatives.

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

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

Annotations already set readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond these hints: OAuth account required, SMS must match verified phone with a 10/day cap, the feed is always on, and the tool returns a subscription id. It does not contradict any annotation and enriches the agent's understanding 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 well-structured: it front-loads the purpose, then prerequisites, supported types with inline examples, and delivery channels with caveats. Every sentence earns its place, though some delivery details overlap with the schema's nested descriptions.

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 thoroughly covers three subscription types (sec_8k, polymarket_edge, fred_series) but omits two valid enum types (patent_grant and clinical_trial) that appear in the input schema. It also omits the webhook delivery channel from the summary. While the schema fills these gaps, the description alone is incomplete for a tool with five types and three delivery options.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds interpretive examples like 'items:["5.02"] = officer change' and clarifies that polymarket_edge uses a topic filter while fred_series uses series_id. These meaningful examples go beyond the schema's raw definitions.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource. It also states 'Returns the new subscription id', clarifying exactly what the tool does. This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description gives a clear use case (creating monitoring subscriptions), a prerequisite ('Requires a Pipeworx OAuth account'), and details on delivery channels. However, it does not explicitly name alternatives or state 'use list_subscriptions to view existing subscriptions', so it lacks a direct when-not-to-use pointer.

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 hints. The description adds valuable context beyond annotations by explaining the return format (category-bucketed example questions with exact tool+argument shapes) and that it draws from a live catalog of thousands of tools. No contradictions found, though it could mention potential limitations or that results are illustrative.

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

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

The description is well-structured and front-loaded with the purpose, followed by what it returns and how to call it. The list of natural-language synonyms ('What can I ask...?', 'give me ideas', etc.) is slightly verbose but earns its place by helping an AI agent match user intents to this tool. Overall concise for the amount of useful guidance it provides.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the full behavioral context (returns example questions with tool shapes), parameter semantics (topic optional, omit for full spread), and usage context (use first when onboarding). It covers return values, usage timing, and parameter behavior without needing an output schema.

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

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

The schema already provides 100% coverage for the optional `topic` parameter, listing the allowed focus areas and instructing to omit for a cross-category spread. The description essentially repeats this ('Call with no arguments for the full spread, or pass `topic` to focus') and adds example values (finance, pharma, betting), but this is redundant with the schema description. 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: it is the onboarding entry point that answers 'what can I ask?' and returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings like discover_tools and ask_pipeworx by explicitly positioning itself as the first-stop discovery and learning tool.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names alternatives (ask_pipeworx, entity_profile, compare_entities) and indicates the optional topic parameter for focused queries, making the when and how 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds meaningful behavioral details: ownership enforcement and soft-delete behavior (row deactivated, not deleted) with a pointer to recent_alerts for historical events. This is rich, valuable context that aligns with and extends the annotations.

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

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

Two sentences, front-loaded with the core action, followed by two high-value behavioral notes. No filler or redundancy. Every word earns its place.

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

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

For a single-parameter tool with no output schema and well-covered annotations, this description fully covers the semantics: what it does, the ownership constraint, the soft-delete behavior, and where to find historical data. It is 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?

The input schema already provides 100% coverage with a clear description ('Subscription id (uuid) returned by subscribe.'). The description only repeats 'by id' and adds no new parameter-level meaning, 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 uses a specific verb+resource ('Cancel a subscription by id') and clearly distinguishes this tool from siblings like subscribe and list_subscriptions. The ownership enforcement detail further clarifies its 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 clearly conveys the action and the constraint that only own subscriptions can be canceled. It implicitly contrasts with subscribe and recent_alerts, though it does not explicitly mention alternative tools or exclusion cases. 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the internal fast-path vs. grounded-pipeline routing, the 'exact percent-delta math' for financial claims, and the output structure (verdict types, citation, reasoning). This gives the agent a clear behavioral model of what happens inside.

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

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

The description is moderately long but well-structured: query examples, purpose, routing logic, output summary, and efficiency claim. Each sentence contributes useful information, and the front-loaded examples help pattern-matching. Could be trimmed slightly, but no waste.

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

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

With no output schema, the description carries the burden of explaining returns—it does so concisely (verdict, value, citation, reasoning). It also covers scope (all factual claims) and the two-path behavior. Minor gaps: does not define the precise criteria for each verdict (e.g., 'unsupported' vs 'inconclusive').

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 high detail (100% coverage). The description adds semantic context beyond the schema by mentioning 'exact percent-delta math' and the 'approximately_correct' verdict, which clarifies how tolerance_pct influences the comparison.

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

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

The description opens with concrete query phrases ("fact check," "verify the claim that…") and states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly differentiates from sibling tools like ask_pipeworx by focusing on claim validation rather than general Q&A.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for others). However, it does not name alternative tools to use instead, nor provide explicit when-not-to-use instructions.

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