Arcgis Lorain

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail: default model selection (Workers AI Llama-3.3-70b free), the BYO-key billing responsibility for Anthropic calls, and the exact return structure ({score, confidence, signals, raw_response} plus a combined view). No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary action and outcome, followed by default behavior, return format, and use cases. Every sentence provides necessary context without 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?

Given four parameters fully described in the schema, strong annotations, and no output schema, the description adequately covers return format, default behavior, and example use cases. It supplies enough information for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds operational semantics beyond the schema: the default model when 'models' is omitted, the dependency between 'models' and '_apiKey' (only needed for 'anthropic'), and the billing implication. This clarifies how to use the parameters correctly.

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

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

The description clearly states the tool's function with a specific verb ('probe') and resource ('LLMs'), and defines the measurable outcome ('score visibility 0-100 per model'). It distinguishes itself from sibling research tools by focusing on LLM knowledge about any entity, not just Pipeworx-specific data.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to include the optional Anthropic model ('pass _apiKey to also probe Anthropic'). It doesn't explicitly exclude alternatives but gives clear context for when this tool is appropriate.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false; the description adds meaningful context by saying it fills arguments internally, returns structured answers with stable pipeworx:// citation URIs, and is intended as a single fast default call. It does not contradict the annotations, though it could disclose failure modes or source limits more explicitly.

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 preference and scope, includes useful examples, and routes the agent to alternatives near the end. It is somewhat long and repeats the web-search preference more than once, but the information density is high and the structure is logical for a broad tool.

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

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

For a tool with no output schema and a very broad domain, the description covers the return shape, input style, example queries, domain scope, and a key alternative. It does not explicitly differentiate close siblings like ask_pipeworx_beta and ask_peworx_grounded, which is a minor gap, but it is otherwise complete enough for an agent 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?

Schema description coverage is 100%, and the schema already documents the 'question' parameter and its aliases. The description adds no significant parameter-level meaning beyond stating that natural-language questions are accepted, which is already present in the schema. 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 states a clear verb and resource: ask_pipeworx answers factual questions by routing them to a large set of verified sources and returning a structured answer with citations. It explicitly differentiates itself from web search and deep_research, so an agent can tell what it is for.

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

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

It gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), says to prefer it over web search even when web search would work, and names deep_research as the alternative for broad or multi-part questions. It also clarifies that breaking-news questions are already covered by ask_pipeworx.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context: it is a full working router, not a fallback; candidate routing may be enabled live; and currently no candidate is active, so behavior matches ask_pipeworx exactly.

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 every sentence earns its place: beta status, identical behavior, current routing state, usage instructions, and confirmation that it is a full router. It is front-loaded with the most important clarification and remains easy to parse.

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

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

For a router with a single required question parameter, 100% schema coverage, and rich annotations, the description is largely complete. It explains the experimental nature, current state, and relationship to the stable sibling, though the actual response shape is referenced by sameness to ask_pipeworx rather than described directly.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter plus aliases. The description only adds that arguments match ask_pipeworx, which is useful but does not add substantial semantic detail beyond the schema.

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

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

The description clearly states that this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx sibling by its experimental routing edge.

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

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

It explicitly tells the agent to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It does not explicitly state when not to use it, but the alternative is clearly named and the intended selection condition is clear.

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

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

The description discloses refusal behavior, the exact refusal_reason enum, the success response shape, and the cost of one extra LLM call. Annotations already mark it read-only/idempotent, and the description adds the grounded-extraction guarantee without contradicting them. No behavioral surprises are left unstated.

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: purpose, routing behavior, return/refusal contract, usage guidance, and cost tradeoff are all packed into one dense but well-organized description. It is front-loaded with the most important distinction and does not waste words.

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

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

With no output schema present, the description fully compensates by documenting the success response, refusal reasons, and failure semantics. It also covers when to choose this tool over its sibling, making it complete enough for an agent to invoke correctly in high-stakes scenarios.

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

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

The input schema has 100% description coverage and documents all aliases for the question parameter, so the description does not need to repeat parameter details. The description adds context that the tool 'fills arguments' itself, but that is behavioral rather than parameter-specific. Baseline 3 is appropriate given the strong 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 identifies a specific mode ('Hallucination-resistant answer mode') and resource ('ask_pipeworx'), and distinguishes it from its sibling by emphasizing extraction restricted to tool-result content. It moves beyond the name by explaining the grounded behavior and explicit refusal contract.

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

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

It gives explicit high-stakes usage criteria ('quoted, cited, or acted on... must not invent facts') and explicitly says to prefer ask_pipeworx for casual lookups. It also states the extra LLM call cost, helping the agent weigh the tradeoff. This is unusually clear routing 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral context: resolver contract with match confidence scores, safety short-circuiting with 'low_confidence_match', 'market_closed_or_inactive' status, wide-spread illiquidity notes, and cancellation-rule risk parser. It also explains fallback behavior for news sources. This far exceeds what annotations provide and helps agents anticipate non-obvious outcomes.

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

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

The description is long but exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Each section is dense with actionable information and the structure makes it scannable. Front-loaded with purpose and usage, then diving into technical contract details. Every sentence adds value for such a complex tool.

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

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

For a complex research tool with no output schema, the description is remarkably complete. It covers input types, output shapes (market, analysis, evidence), resolver matching convenance, parent-event handling, news fallback mechanics, safety statuses, and cancellation-rule edge cases. It also includes examples and warnings about 'phantom matches'. This fully equips an agent to use the tool correctly and interpret results safely.

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

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

The input schema already covers parameters with 100% description coverage. The tool description adds meaningful context beyond the schema: it explains market slug/URL/question-text resolution, depth choices with default 'thorough', and include_raw's impact on response size and use cases. While the schema is already good, the description enriches understanding with concrete fan-out examples and trade-offs, so it earns above 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 begins with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools (e.g., polymarket_edges, arbitrage) by focusing on a single bet, and it gives explicit input examples. The purpose is unmistakable and well-scoped.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains classifier categories and fan-out examples, giving concrete scenarios. The tool also details parameter choices (depth, include_raw) and edge-case blocking paths, making when-to-use very clear.

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

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

The annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial context: it lists specific SEC EDGAR/XBRL fields for companies, FAERS data for drugs, sorting by primary metric, citation URIs, and handles off-calendar fiscal years correctly. This is valuable behavioral disclosure 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 compact and front-loaded with natural-language query triggers, then states the preference rule, then per-type data details. Every sentence earns its place—there is no filler, 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 sufficiently explains return value structure ('paired data + pipeworx:// citation URIs'), sorting behavior, and the parallel-execution advantage. It fully covers the 2-parameter interface and the tool's role relative to siblings, 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% (both parameters have descriptions, enum for type). The description adds meaning by explaining what each type actually returns (revenue/net income for companies; adverse-event/trial counts for drugs) and implicitly confirms the values array maps to tickers/CIKs or drug names. This enriches the schema without redundancy.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, using specific verbs and resource scope. It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' which names the alternative pattern.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and 'Replaces 8–15 sequential lookups.' It also clarifies the company vs drug data sources, helping the agent decide which type to choose.

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 carry readOnlyHint/idempotentHint/destructiveHint, and the description adds a great deal of non-obvious behavior beyond those: parallel decomposition across 5,767 tools, gap recovery hops by depth, contradictions[] scanning, hop fields, citation_uri fetchability caveats, semantic excerpting of large records, and expected latency per depth. It also discloses an account/paywall requirement, which is exactly the kind of behavioral context an agent needs before invoking.

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

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

The description is dense but every sentence earns its place; critical routing and sign-in constraints are front-loaded. It is longer than ideal, but the tool is genuinely complex (three depth tiers, two alternative routes, multi-purpose output), and the length tracks that complexity. Minor redundancy: the 'gap recovery' concept is explained twice, and the depth explainer overlaps with the schema enum description.

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

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

For a tool with two params, no output schema, and a rich behavioral contract, the description is complete: it covers authentication, alternatives, scope, return packet shape, failure behavior (gaps[], never invented), citation semantics, latency expectations, and depth-dependent behavior. An agent can select and invoke this tool correctly without needing to infer anything material.

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 both parameters thoroughly, including the depth enum semantics. The description adds value by explaining what happens at each depth in runtime terms (single hop, gap recovery, contradictions scan, lead-chasing) and by clarifying that decomposition is the point of the question parameter. It doesn't restate schema details verbatim, which 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 states a specific verb ('researches'), a precise resource ('Pipeworx's 1506 STRUCTURED data sources ... in ONE call'), and explicitly distinguishes itself from open-web search ('this is NOT open-web search'). It also contrasts with ask_pipeworx for single lookups, so an agent can tell it apart from siblings.

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

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

The description is explicit about when to use deep_research ('Best for broad/multi-part questions over structured data') and when NOT to use it ('For a single lookup use ask_pipeworx instead'), and it names the alternative conditional on sign-in ('If you are not signed in, use ask_pipeworx instead'). It also advises preferring ask_pipeworx for news-style open-world topics, covering both the sign-in gate and the structured-vs-open-world routing decision.

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, so the description builds on this by disclosing return value behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... no second schema lookup needed.' This adds useful context about efficiency and output format 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 four sentences, front-loaded with the core purpose, and every sentence earns its place. The domain list is lengthy but provides useful context for an agent deciding relevance. 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?

The description covers purpose, when to use, return format, and timing. Given the tool's simplicity and the rich annotations, it is fairly complete. A minor gap is that it doesn't explicitly state what 'tool' means here, but the context makes it clear. Overall adequate.

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 each parameter (query, limit, aliases) is already documented. The description adds no additional parameter-specific meaning, just reaffirms that the query is a natural language description. Baseline 3 is appropriate when the schema handles 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 explicitly states 'Find tools by describing the data or task,' which is a clear verb+resource pairing. It distinguishes from siblings by framing this as tool discovery rather than data querying, and the enumerated domains (SEC filings, FDA drugs, etc.) give concrete 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?

It clearly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' While it doesn't name alternative tools explicitly, the guidance provides strong context on when to invoke this vs. other 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 establish read-only/idempotent behavior, and the description adds substantial behavioral context: the fan-out source list, USPTO sunset soft-fail, FDA-empty-data caveat, empty sections as real no-data, and private-company resolved:false flow. These traits go well beyond the annotations and are crucial for interpreting results.

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

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

The description is long but front-loaded with user-phrase triggers and the main benefit, followed by structured return details. Nearly every clause covers a needed edge case in a complex tool, though it could be trimmed where it repeats the schema's parameter 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?

With no output schema, the description carries the full burden of explaining return shape, source availability, soft-fails, expected-empty sections, and private-company behavior. It covers all major failure and edge paths an agent would encounter when 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?

Schema description coverage is 100%: both type and value already document the interchangeable company/ticker options and accepted value shapes. The description repeats these rules with examples, but adds little genuinely new parameter meaning beyond what the schema states.

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 user-phrase triggers and states a clear verb+resource: full cross-source profile of a US public company in one parallel call. It is unambiguous about what the tool returns, but it does not name or contrast sibling tools explicitly; the only distinction is a generic preference over chaining single-pack lookups.

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

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

It gives explicit trigger examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and an ALWAYS PREFER directive for holistic-view requests. It does not, however, specify when to choose an alternative sibling such as resolve_entity, compare_entities, or deep_research, so exclusion conditions are absent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds useful context about what is deleted (previously stored memory) and the motivation (clearing sensitive data), without contradicting the annotations.

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

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

The description is two sentences long, immediately states the core action, and uses the second sentence for when-to-use guidance. Every word serves a purpose, with no redundancy.

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

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

For a simple one-parameter delete tool with strong annotations, the description covers purpose, usage, and context. It mentions related tools, and since no output schema exists, the description need not detail return values. An agent can 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 schema description coverage is 100% because the single parameter 'key' is fully described as 'Memory key to delete.' The description adds no extra meaning beyond the schema, simply reiterating the concept of deleting by key.

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 ('Delete') and identifies the resource ('previously stored memory') and the mechanism ('by key'). It clearly distinguishes itself from sibling tools like 'remember' and 'recall' by being the deletion counterpart.

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

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

It explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' providing clear situational triggers and complementary workflow 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 readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable process context: it fetches a page, extracts key elements, and outputs a single text blob. It doesn't mention potential failure modes, but the annotations lower the burden, and the behavior is well-articulated.

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

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

Three sentences front-load the purpose and process, with a compact 'Useful for' list. It is concise and structured logically, though the phrase 'production-ready' and 'standard llms.txt markdown format' are slightly redundant. Still very efficient.

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

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

Given no output schema, the description explains the output format ('standard llms.txt markdown format', 'single text blob') and gives use cases. It lacks error-handling details or limitations, but the tool is simple (2 params, strong annotations) and the description covers the essentials well.

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%—both `url` and `max_links` have descriptions in the schema. The tool description adds little beyond the schema; it mentions 'key links' but does not reference the `max_links` parameter or its default behavior. Baseline of 3 is appropriate since the schema carries the parameter documentation.

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: 'Generate a production-ready llms.txt file for any URL.' It explains the process (fetches page, extracts title/description/key links, emits standard markdown) and is distinct from all sibling tools, none of which mention llms.txt.

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

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

Provides clear context for use via the 'Useful for:' list, covering client work, personal projects, and competitive auditing. However, it does not explicitly exclude alternatives or mention when not to use this tool, so it stops short of a 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the exact informational payload that will be returned (fields, geometry type, record count, capabilities), which helps the agent set expectations. No contradiction with annotations.

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

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

A single, dense sentence that front-loads the verb and resource, lists outputs, and includes the URL qualifier. 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 one-parameter read-only tool, the description covers the what, the input, and the expected return contents. Given no output schema, this provides sufficient context for an agent to understand the tool's results and differentiate it from query operations.

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 type and example. The tool description only references 'by url' without adding new details, so it does not enhance the schema's already complete parameter 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 uses a specific verb ('Get'), identifies the resource ('ArcGIS Feature/Map Service layer's schema'), and enumerates the exact output contents (fields, geometry type, record count, capabilities), clearly distinguishing it from data-query siblings like query_layer.

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

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

The description implies its use case (schema retrieval by URL) but does not explicitly state when to prefer it over alternatives or exclude scenarios. The presence of sibling query_layer suggests a distinction, but the description does not articulate this contrast.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value beyond annotations by specifying the return fields (id, type, params, etc.) and the default active-only scope. 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?

Two sentences, no fluff. The first sentence states the action and return fields, the second gives usage guidance. Information is front-loaded and 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 simple list tool with one optional parameter and rich annotations, the description covers purpose, usage, and return fields. The lack of an output schema is compensated by listing return fields. Complexities like pagination or errors are not relevant for this straightforward read operation.

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

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

Schema coverage is 100% for the single parameter include_inactive, which has a clear description. The tool description does not elaborate further on the parameter, so the schema carries the semantic load, warranting the baseline score of 3.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists the exact return fields. It also differentiates from sibling tools like subscribe and unsubscribe by framing the use case for reviewing monitoring and finding ids to cancel.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't name alternatives directly, the context implies that subscribe/unsubscribe are the complementary tools, making the when-to-use clear.

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

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

The description discloses that filing without an account returns a `claim_token` that can be passed back later to check resolution status, a rate limit of 5 per identifier per day, and that it's free with no quota impact. These behaviors are not covered by the annotations, which only set all hints to false.

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 containing multiple distinct pieces of guidance (purpose, exclusions, token workflow, rate limits). While every sentence adds value, it could benefit from structural segmentation (e.g., bullets), but overall it is informative without significant 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?

Given no output schema and minimal annotations, the description covers the tool's full interaction model: what to report, how to identify relevant tools, token-based follow-up, rate limits, and context structuring. It lacks only a detailed return format, which is unnecessary for a feedback tool.

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

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

The input schema already documents all parameters with 100% coverage, including enum meanings and the claim_token workflow. The description adds context about token return without an account and mentions structuring context around Pipeworx tools/packs, but most parameter meaning is already in the schema.

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

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

The description explicitly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the specific resource (Pipeworx team) and differentiates it from other MCP servers' tools, making it clear this feedback applies only to this connection's 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?

It enumerates exact use cases (bug, feature, data_gap, praise) and provides explicit exclusions: if the tool is from a different MCP server, 'file it with that server instead.' It also advises describing issues in terms of Pipeworx tools/packs rather than pasting user prompts, giving clear when-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?

The description adds significant context beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data provenance, privacy, output shape, and caching behavior, which the annotations do not cover.

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

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

The description is three sentences, front-loaded with the core function, followed by a numbered use-case list and then behavioral details. Every sentence adds distinct value, with no filler or redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, return values (top tools, packs, call volume), use cases, and behavioral characteristics. The '(pack, tool, count)' hint compensates for the absent 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 description coverage is 100% for the only parameter, and the schema already explains the default and the trade-off between window lengths. The description repeats the window options but adds no new parameter-level meaning beyond what the schema provides.

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

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

The description clearly states what the tool does with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes from siblings by focusing on aggregate usage trends of other AI agents, not individual discovery or search.

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

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

The description explicitly lists three concrete use cases, including 'confirming a popular tool is the canonical choice before asking your own question.' This provides clear when-to-use guidance and implies alternatives (e.g., asking directly) without naming sibling tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral traits such as the fill check against live CLOB depth, the rule that realizable_edge_pp <= 0 means the overround exists only at last-trade, the Jaccard similarity threshold for semantic pairing, and the partition placeholder filter. These are not in the annotations and add significant context for the agent.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every segment adds necessary detail for a complex tool; however, the length itself borders on verbose, so a perfect score is not warranted.

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

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

For a tool with no output schema, the description fully explains response shapes (opportunities[], partition_check fields), mode-specific behaviors, edge cases (placeholder slugs, low similarity, thin legs), and when not to trade. Combined with the detailed annotations, an agent has everything needed to invoke and interpret the tool correctly.

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

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

Although the schema already covers both parameters (event and topic), the description adds substantial meaning: example slugs, the distinction between single-event and cross-event behavior, how each mode processes markets, and what the semantic anchor does. This goes well beyond the schema's basic 'event slug' and 'topic' 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by describing distinct modes (trending_scan, event, topic) and explicitly recommends polymarket_fill_risk for custom sizing, showing awareness of the tool landscape.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also states for which scenarios to use event vs topic, and explicitly directs custom sizing to polymarket_fill_risk, giving 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 mark the tool as read-only, idempotent, and non-destructive. The description goes far beyond this, disclosing the math behind edge calculations (lognormal barriers, GDELT ratios, overround corrections), Kelly caps, slippage handling, the 24h-move warning, and even the 1-hour KV-level cache. 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 extremely dense and runs as a single block with uppercase labels instead of bullets or paragraphs. Every sentence is informative, but readability suffers. There is also an apparent discrepancy: it says 'FIVE MODEL FAMILIES' but lists only four (crypto_price, news_momentum, partition_overround, concentrated_longshot). While not a functional issue, it shows a lack of polish.

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 full burden of explaining the response. It details top-level fields (by_segment, fed_candidates, _diagnostics), explains why segments might be empty (stale top-N, failed gates, knob filters), and describes caching behavior. It is exceptionally complete for a tool with 9 parameters and zero required fields.

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

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

Schema coverage is 100%, but the description adds crucial inter-parameter context: min_kelly only filters single-leg opportunities, min_partition_leg_kelly applies per-leg inside top_legs, and slippage_pp is subtracted before ranking. It clarifies why min_kelly doesn't filter partition arbs and explains how categories map to the three segments. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings by detailing three specific segments (model-driven, structural arbitrage, concentrated longshot) and the response structure, making it unique among the sibling tools.

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

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

The description frames usage as 'what should I bet on today' and provides context for when to adjust tradeable-edge knobs like min_liquidity and max_spread_pp. It does not explicitly exclude sibling tools, but the detailed segment breakdown implies appropriate use cases. The note about Fed bets and when they're unreliable adds good decision 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, but the description adds substantial behavioral context: 60-day snapshot TTL, snapshot start time, cache-miss writing behavior, daily-close basis for decay, and interpretation of negative edge_pp_net. This goes well beyond the annotation baseline.

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, using labeled sections (Args, RESPONSE, LIMITS) and front-loading the core purpose. Every sentence conveys necessary information; there is no filler, and the structure aids scannability.

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

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

With no output schema, the description thoroughly documents the response structure (tracked[], expired[], snapshot_dates[]) and their semantic meanings, including the 'competition clock' interpretation of median lifespan. It also explains historical limitations, making it complete for the tool's complexity.

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

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

The input schema covers both parameters fully with descriptions (days lookback, window family). The description repeats defaults and adds that window is a 'snapshot family', but does not significantly extend parameter semantics. With 100% schema coverage, a 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 identifies the tool's purpose as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, and articulates the specific question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools that likely focus on current edge values.

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

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

The description implies when to use the tool by focusing on historical persistence and decay, contrasting fresh vs old edges. It provides clear context but does not explicitly name alternative tools or give 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?

Despite having readOnlyHint, idempotentHint, and destructiveHint annotations, the description goes well beyond them. It reveals that the tool walks the order-book ladder, that theoretical overround on thin books is not capturable, and that partial basket fills convert an arb into an unhedged directional position. This is deep behavioral context that materially affects how an agent should interpret results.

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 carefully structured with ALL-CAPS mode labels (SINGLE-MARKET, BASKET, USE THIS) and front-loads the core purpose in the first sentence. Every sentence delivers necessary information for a two-mode tool, and the length is justified by 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?

For a tool with no output schema, the description enumerates every output field for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk, etc.), explains the size_usd interpretation per mode, and states defaults and clamps. It also provides the risk context that matters for an agent deciding when to call this tool. Nothing critical appears omitted.

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

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

Schema coverage is 100%, but the description adds critical semantics missing from the schema: side meaning differs per mode (sell_yes captures overround in basket mode), size_usd is interpreted as max spend on buys vs target proceeds on sells vs settlement notional in basket mode, and exactly one of market/event is required. This enriches the schema descriptions significantly.

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

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

The description opens with a specific verb+object: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly distinguishing it from the sibling arb/edge tools. It also explicitly names the two modes (single-market and basket), leaving no ambiguity about what the tool does.

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

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

The description gives an explicit trigger: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' and explains the risk that necessitates it. However, it does not state when not to use the tool or name alternative tools for different scenarios, 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 mark this as read-only, idempotent, and non-destructive, so the description goes well beyond them by disclosing pairing limitations, compatibility codes, fee treatment, skipped-leg counters, and the meaning of null temporal alignment. This is rich, honest behavioral disclosure that an agent needs before trusting results.

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

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

The description is long, but it is densely packed with critical caveats and safety fields, and it is logically organized with labeled sections for modes, response, safety, and fees. Every section earns its place for a complex tool, though it could benefit from tighter formatting.

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 full burden of explaining return values, failure modes, edge cases, and interpretation of fields like temporal_alignment and skipped counters. It covers these thoroughly and leaves no major ambiguity for an agent deciding whether and how to call it.

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

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

The schema already describes all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics by explaining that the explicit ticker and slug override the topic-mapped sides and that both modes run the identical matcher, which the schema alone does not convey.

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

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

The description clearly identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question, which is specific and descriptive. It does not explicitly contrast itself with sibling tools like polymarket_arbitrage, but the resource and scope are unmistakable.

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

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

The description explains the two modes (topic shortcuts vs explicit ticker/slug) and when each is appropriate, and warns that pre-mapped topics often yield compatibility warnings. It does not explicitly state when to prefer a sibling tool, but it provides clear context for using this tool correctly.

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

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

Annotations already declare readOnlyHint=true, but the description adds that it returns attribute rows and geometry, and describes SQL-like filtering behavior. The sampling tip and explicit mention of output format go beyond the annotations, providing useful behavioral context. 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: first states purpose and key parameters, second gives a usage tip. No fluff, well front-loaded with the verb and resource. 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?

With no output schema, the description's mention of returning rows and geometry helps fill that gap. It also references the predecessor tool (search_datasets) and provides a sample query pattern. Overall, it is fairly complete for a query tool, though it could include pagination behavior notes beyond offset.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining SQL-like semantics ('where', 'out_fields', 'order_by') and giving a practical sampling pattern. It enhances rather than repeats schema info, justifying a score above baseline.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, using a specific verb ('Query') and resource. It distinguishes from sibling tools like layer_info (metadata) and search_datasets (dataset discovery) by focusing on data retrieval.

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 indicates the URL comes from search_datasets, implying a workflow of first finding a dataset then querying it. The sampling tip ('Use where="1=1" + out_fields="*"') provides concrete usage context. However, it does not explicitly exclude alternatives or state when not to use, leaving some ambiguity.

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 a read-only, idempotent, non-destructive operation, so the description doesn't need to restate that. It adds valuable context beyond the annotations by explaining that the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all keys. This gives the agent a clearer picture of the tool's behavior and privacy boundaries.

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 but information-dense. Every sentence serves a purpose: the first defines the primary action and list behavior, the second gives practical examples, the third explains scoping, and the fourth points to complementary tools. There is 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 tool with one optional parameter and no output schema, the description covers all necessary context: what it does, when to use it, how it's scoped, and how it fits into the larger tool ecosystem. The agent has enough information to decide when to invoke this tool and what to expect from it.

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

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

The schema already documents the key parameter with 'Memory key to retrieve (omit to list all keys)', providing 100% coverage. The description reinforces this and adds semantic examples of what kinds of keys are useful (target ticker, address, research notes), which helps the agent understand the intended usage beyond the raw schema.

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

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

The description states exactly what the tool does: retrieves a previously saved value or lists all saved keys when the key argument is omitted. It uses a specific verb ('Retrieve') and resource (saved memories), and clearly distinguishes itself from the sibling tools by referencing remember and forget, which are the companion save/delete operations.

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 tells when to use the tool: to look up context the agent stored earlier, such as the user's target ticker, an address, or prior research notes, without re-deriving it. It also names the complementary tools (remember to save, forget to delete), providing a clear usage context and 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?

The description reveals a side effect: setting mark_read:true flags events as read, which modifies state. This directly contradicts the readOnlyHint=true annotation, making it an annotation contradiction. The description otherwise adds useful context about return fields and external access, but the contradiction forces a score of 1.

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

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

The description is concise and well-structured: it starts with the primary action, then details return fields, filtering, and mark_read behavior, and ends with polling and an alternative endpoint. No redundant information.

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

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

For a tool with five optional parameters and no output schema, the description covers main functionality, return fields, and usage nuances like polling and an external URL. However, the annotation contradiction and lack of explicit mention of unread_only slightly reduce completeness.

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

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

The schema covers all parameters with descriptions, but the description adds practical meaning by giving an example for type ('sec_8k') and explaining the behavioral effect of mark_read on future calls. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, using a specific verb and resource. It distinguishes itself from siblings like list_subscriptions by focusing on alert events and their payloads.

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

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

The description provides clear context on how to use the tool, including filtering by type and since, and setting mark_read. It also mentions polling and an alternative URL for scripts, but does not explicitly compare with sibling tools or state when not to use it.

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

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

Beyond the read-only/idempotent annotations, the description discloses specific behaviors: fans out to multiple sources in one parallel call, fallback logic (GDELT→GNews), and a known limitation (USPTO soft-fails due to PatentsView sunset). It also describes return structure and citation URIs, adding significant value beyond annotations.

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

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

The description is a single focused paragraph with a clear lead-in, examples, mechanism, and alternative. Every sentence contributes, and it remains readable despite covering multiple data sources and the `since` parameter formats.

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?

Though no output schema exists, the description compensates by specifying the return shape: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers edge cases like rate-limiting and API sunset, making it fully contextual for an agent to invoke correctly.

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

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

Schema covers all parameters (100%), but description adds semantic value by explaining accepted date formats and giving usage examples ('Use "30d" or "1m" for typical monitoring'). It reinforces parameter meaning without redundancy.

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

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

The description clearly states the tool's purpose with vivid examples ('What's new with X' / 'latest on Y') and a precise definition: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes from sibling entity_profile by contrasting the static profile vs. change feed 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?

Explicit when-to-use guidance is given through example queries and by stating it fans out to multiple sources. It also tells when NOT to use it: 'Use entity_profile instead when you want the static profile... regardless of window.' This directly guides tool selection among siblings.

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

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

The description goes beyond the annotations by explaining key-value scoping, persistence differences for authenticated vs anonymous sessions, and the 24-hour retention limit. This is valuable behavioral context not captured in the idempotentHint.

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, followed by usage guidance and behavioral details. Every sentence adds necessary information without fluff.

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

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

For a simple memory-write tool, the description covers purpose, usage, persistence, scoping, and related tools. No output schema exists, so the absence of return-value details is acceptable.

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 parameters fully with examples, so the baseline is 3. The description reinforces the key-value concept but doesn't add significant syntactic detail beyond the schema.

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

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

The description opens with a specific action ('Save data') and clearly identifies the resource and purpose. Examples (resolved ticker, target address) and the contrast with recall/forget distinguish it from sibling memory tools.

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

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

The description explicitly states 'Use when...' and gives concrete scenarios. It also names recall and forget as complementary tools, providing clear guidance on when to use this tool 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?

Beyond the readOnly/idempotent annotations, the description discloses meaningful behaviors: cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, asserting nothing on ambiguous matches and returning figi_candidates, and explicitly stating unresolved identifiers under `unresolved` rather than omitting them. This greatly exceeds 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 long but dense with actionable detail, and its key directive 'Use FIRST whenever...' is front-loaded. Some sentences are expansive, like the internal-cascade rationale at the end, but they still convey useful context rather than 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 tool with no output schema, the description gives the agent what it needs: the returned identifier families (CIK, ticker, LEI, FIGI, RxCUI), ambiguity behavior via figi_candidates, unresolved-identifier handling, input formats, and failure-mode degradation. This is unusually complete for a read-only resolver.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value for the `value` parameter: it documents accepted forms (ticker, CIK, ISIN, name), warns against including trailing security-class words, and explains type-specific behaviors such as ISIN-to-LEI resolution for non-US issuers. This goes beyond the schema's brief field 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 leads with concrete query examples and a clear statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This names a specific verb, resource, and output, and positions the tool as the ID-lookup entry point among siblings. It also distinguishes resolved identifiers by type (company, drug), making its scope unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It does not name or exclude sibling alternatives such as entity_profile or compare_entities, so the when-not/alternatives dimension is less explicit than ideal.

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 that it probes each entity with ai_visibility_check, ranks by score, and returns ranked metrics (score, confidence, signal density). This adds behavioral context beyond the annotations (readOnly, openWorld, idempotent) without contradicting them. It does not mention potential rate limits or cost implications of multi-probing, but the core behavior is transparent.

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 with no fluff. It front-loads the purpose, explains the method (probes with ai_visibility_check, ranks), and gives a concrete use case and output summary. Every sentence earns its place.

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

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

With no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also covers the mechanism and use case. It doesn't discuss error handling or limitations, but given strong schema coverage and annotations, this is sufficient for a multi-entity comparison tool.

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

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

Schema coverage is 100%, and the entities parameter description already includes the 'first entry as subject' semantics that the description paraphrases. The description adds no extra parameter meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: compare AI visibility across multiple entities side-by-side, probe each with ai_visibility_check, and rank results. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by emphasizing multi-entity AI visibility and ranking.

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

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

It gives a clear context for when to use: competitive AI-marketing audits, and an illustrative example question. It implies a multi-entity scope but doesn't explicitly name alternatives or exclusion scenarios, such as 'for single entity use ai_visibility_check'. This fits the 'clear context, no exclusions' level.

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

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

Even with annotations readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes further by disclosing graceful degradation, potential 5-30s delay on first measurement, and the presence of a 'sources_failed' field in output. This adds real behavioral context beyond annotations and does not 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?

The description is information-dense yet every sentence earns its place: purpose, use cases, output summary fields, ecosystem limitation, and failure behavior are all covered without excessive wording. The structure front-loads the core purpose and uses a closing sentence for caveats, making it easy to scan for key details.

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

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

Given the tool's complexity (two external APIs, multiple output components) and the absence of an output schema, the description is remarkably complete. It lists the summary block fields, mentions per-advisory detail, links, alternative versions, and explicitly addresses failure/timeout behavior. It also clarifies the ecosystem boundary, leaving no major contextual gaps.

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

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

Schema description coverage is 100%, and the description does not add meaning beyond what the schema already provides. It mentions that the version defaults to latest, but that is also in the schema. The description repeats no explicit parameter details beyond those in the schema, so 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 opens with a specific verb+resource: "Composite 'should I add this npm package to my project' check in ONE call" and clearly distinguishes the tool from siblings by naming the two data sources (deps.dev and bundlephobia). It uniquely addresses npm package evaluation among the sibling list, so there is no ambiguity about 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?

Explicit usage triggers are given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides an exclusion for non-npm ecosystems, stating "PyPI / Maven / Cargo / Go fall under deps.dev:version directly," which tells the agent when NOT to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing it as a safe read-only operation. The description adds value beyond annotations by specifying the exact return fields (name, summary, record_count, owner/org, url) and the fact it returns a Feature Service URL, which informs the agent of the output structure. 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: the first front-loads the purpose and scope, the second details return fields and downstream usage. Every word contributes value, with no filler or redundancy. Ideal 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?

Given three optional parameters and no output schema, the description adequately covers what the tool does, what it returns (explicitly listing fields), and how the returned URL is used with sibling tools. It does not explain pagination or sorting behavior, but those are not critical for a search tool where the schema covers limit. The description is sufficiently complete for an agent to use 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 coverage is 100% for all three parameters, each with meaningful descriptions (query keywords, limit range, optional org_id). The description adds minimal extra parameter semantics; it simply restates 'by keyword' which aligns with the query parameter. Baseline 3 is appropriate because the schema already handles parameter documentation.

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

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

The description clearly states a specific verb ('Search') and resource ('Lorain County GIS open geospatial datasets') with concrete examples of searchable content (parcels, addresses, zoning). It distinguishes itself from sibling tools by explicitly noting it returns Feature Service URLs for query_layer/layer_info, which is an effective differentiator.

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 clear usage context: use this to discover datasets by keyword, then pass the returned URL to query_layer or layer_info for further operations. It does not explicitly state when not to use this tool or name alternative search methods, but the downstream guidance is a strong usage signal. Slightly below a 5 because exclusions are not 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?

Even though annotations already declare readOnly, idempotent, and not destructive, the description adds valuable behavioral details: the embedding model (BGE-base-en), cosine similarity over 500-char windows, the 200K char cap with truncation flagging, and the return format (passages with offsets and similarity scores). These details go well beyond the annotations and help the agent predict output and edge cases.

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 bit long (5 sentences) but every sentence contributes: purpose, usage, pairing, and technical implementation. It front-loads the core purpose and then adds supporting detail. No filler words; the structure is logical and efficient.

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

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

Despite lacking an output schema, the description explains the return format ('top-N passages with character offsets and similarity scores'), the underlying algorithm, and the character cap. It also covers the integration with ask_pipeworx_grounded, making it a complete picture for the agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the semantics with examples ('SEC 10-K body', 'natural-language query') and mentions 'top-N' passages, but it does not add significant new meaning beyond the schema's parameter descriptions. It meets the baseline but doesn't elevate it.

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

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

The description clearly states the tool's function as 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). It distinguishes itself from siblings by framing it as a tool for searching within an already-fetched record, and even names ask_pipeworx_grounded as a complementary tool, making its unique purpose explicit.

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

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

The description gives explicit guidance: 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded. This tells the agent exactly when to use this tool and how it fits into a larger workflow, effectively differentiating it from alternatives.

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

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

Annotations already declare readOnly=false and idempotentHint=true, and the description adds useful behavioral context: it requires OAuth, returns the new subscription ID, notes that SMS has a 10/day cap and requires phone verification. However, it omits the webhook delivery channel entirely (including its HMAC signing and auto-disable behavior), which is a significant gap when the schema supports it.

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 then organized by requirements, types, and delivery channels. It is fairly efficient, but somewhat redundant with the schema (e.g., repeating SMS verification and 10-day cap), and what it omits (webhook, two types) might require the agent to consult the schema. Overall, it is concise enough 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?

The tool is moderately complex with nested params and no output schema, so the description carries a heavy burden. It covers OAuth requirements, return ID, and some delivery details, but omits webhook as a delivery channel and two of the five subscription types (patent_grant, clinical_trial). It also does not mention that the response includes a webhook signing secret when webhook is specified. These are clear gaps that could cause an agent to under-utilize or misunderstand the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples and interpretations (e.g., 'items:["5.02"] = officer change') and clarifying the 'polymarket_edge' topic parameter. However, it only covers three of the five allowed types, leaving patent_grant and clinical_trial undocumented in the description, though the schema covers them.

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

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

The description clearly states what the tool does: 'Create a proactive monitoring subscription to a live-data event stream.' It uses the verb 'create' with a specific resource, and the rich detail about supported types and delivery channels distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides clear context on prerequisites ('Requires a Pipeworx OAuth account') and how to consume the always-on feed ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). However, it does not explicitly state when to use this tool versus alternatives (e.g., list_subscriptions for viewing), nor does it explain when not to use it beyond the OAuth 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context: that it returns category-bucketed examples with exact tool + argument shape, drawn from a live catalog, and that it works with no arguments or with an optional topic. This goes beyond 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 long but every sentence serves a purpose: it lists query phrasing, explains the return value, gives concrete categories, clarifies the optional parameter, and explicitly states when to use it. The structure is front-loaded with the entry-point intent, then details, and ends with usage guidance. 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?

Given the tool's simplicity (1 optional param, no output schema, read-only), the description is complete. It covers what the tool returns, the categories, the parameter behavior, and use cases. The output is fully characterized (category-bucketed examples with tool + argument shape), so no output schema is needed. This is a complete description for the tool's complexity.

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

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

Schema coverage is 100% and the `topic` parameter is documented with enum-like values. The description reinforces the parameter by listing examples and explaining the effect of omitting it (full spread). This adds value by contextualizing what 'focus' means and by providing example values not fully captured in the concise schema description.

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

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

The description uses specific verbs ('onboarding entry point') and explicitly states resource ('Pipeworx') and scope ('category-bucketed example questions'). It distinguishes from siblings by naming the meta-tools (ask_pipeworx, entity_profile, compare_entities) as the things it teaches, making the purpose clear and 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?

It says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This is explicit guidance on when to use, and it implicitly excludes other tools by redirecting to them. It also offers a clear alternative: call with `topic` to focus, or omit for the full spread.

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, the description discloses ownership enforcement (only your own subscriptions) and the deactivation behavior (row not deleted, historical events remain in recent_alerts). This aligns with the destructiveHint=false annotation and adds significant behavioral context.

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

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

Two sentences, front-loaded with the primary action, and no redundant information. Every sentence earns its place by covering purpose, constraints, and side effects.

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 low-complexity tool with one parameter and annotations, the description is complete: it states the purpose, ownership rule, deactivation behavior, and where historical events can be found (recent_alerts). No output schema is necessary for a void operation.

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 provides 100% coverage for the single parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description adds no additional parameter-level detail, 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 begins with a specific verb and resource: 'Cancel a subscription by id.' It clearly differentiates from sibling tools like subscribe and list_subscriptions, and additionally clarifies that the operation deactivates rather than deletes.

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

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

The description implies when to use the tool (when you need to cancel a subscription) and provides important context about ownership and soft-deletion. It does not explicitly name alternatives or exclusions, but the context is unambiguous given the sibling tool names.

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

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

The description adds substantial behavioral context beyond annotations: it explains the meaning of each verdict, especially the critical distinction that 'could_not_verify' means the check failed and must not be interpreted as evidence. It also discloses routing logic and the exact pipeline behavior, which annotations like readOnlyHint and openWorldHint do not cover.

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

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

The description is fairly long but well-structured, front-loading the core purpose and using a clear format with returns, caveats, and a summary of replaced calls. Some phrases are slightly redundant (e.g., 'routed to the right live source, answered with verbatim evidence, then judged'), but overall the length is justified by 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?

This tool has no output schema, so the description carries full responsibility for explaining return values and behaviors. It covers the verdict set, citation mechanism, reasoning, and the important error semantics, making the description self-sufficient for an agent to understand the tool's full contract and edge cases.

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

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

While the schema fully documents both parameters, the description enriches the semantics of tolerance_pct with concrete guidance (e.g., set 1–2 for hallucination detection) and the default behavior. It also provides examples for the claim parameter, giving real-world clarity beyond the schema's type-only description.

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

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

The description clearly identifies the tool's function: verifying natural-language factual claims against authoritative sources. It uses specific trigger phrases and lists concrete example intents, and it distinguishes itself from sibling tools by explaining that it replaces multiple sequential calls with a single end-to-end verification flow.

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

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

It explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and clarifies the two distinct pathways for financial vs. other claims. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of the exhaustive 'when-not/alternatives' bar.

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