Arcgis Harrisburg

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

The description adds valuable behavioral context beyond the annotations: default model (Workers AI Llama-3.3-70b), free/default versus paid Anthropic calls ('BYO key — you pay Anthropic directly'), and the return structure. Annotations already cover read-only/idempotent safety, so the extra cost and model selection details meaningfully round out the behavior.

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

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

Four sentences deliver purpose, model options, cost, output format, and use cases. Every sentence earns its place; there is no filler or repetition of schema details.

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

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

With no output schema, the description appropriately summarizes the return payload (per-model {score, confidence, signals, raw_response} + combined view). It also covers model selection and cost. It could detail what 'signals' or 'combined view' contain, but that is minor for invoking 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 covers all parameters with descriptions, giving a baseline of 3. The description goes further by clarifying cost implications and the default model, which is not in the schema. It also reinforces the relationship between `models` and `_apiKey`, making parameter usage more intuitive.

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 ('Probe one or more LLMs'), target ('business / brand / product / topic'), and measurable outcome ('score visibility (0-100) per model'). This clearly distinguishes it from sibling research tools like deep_research or entity_profile by centering on LLM knowledge and visibility scoring.

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 use cases are listed: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it does not name alternative tools or exclusion criteria, the stated contexts give a clear sense of when to reach for 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: it is a fast default router that fills arguments, returns stable pipeworx:// citation URIs, and works on every tier. 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 dense but every sentence earns its place: it enumerates covered domains, lists trigger phrases, gives examples, states default status, and explicitly names escalation paths. The structure flows from what → when → how → alternatives, making it easy to parse despite length.

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

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

With one required parameter and no output schema, the description is exceptionally complete: it explains the type of questions, the routing behavior, the return format (structured with citations), covers content domains, and clarifies when to use sibling tools. Nothing important is missing.

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

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

Schema coverage is 100% and all parameters are clearly defined as aliases for the question. The description provides example questions but adds no additional parameter-level meaning beyond what the schema already states. 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 routes questions to thousands of verified sources and returns structured answers with citations. It positions itself as the default entry point and explicitly contrasts with ask_pipeworx_grounded and deep_research, making it unambiguous what this tool does and how it differs.

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

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

Provides explicit triggers ('what is', 'look up', 'find', 'get the latest', etc.) and examples. It also states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant evidence, deep_research for broad/multi-part questions), covering both when to use and when not to use.

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

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

The description goes well beyond the readOnly/openWorld/idempotent/non-destructive annotations by explaining that no routing candidate is active, behavior currently matches ask_pipeworx, and that it is a fully functional router rather than a degraded fallback. This gives the agent useful expectations about mutability and operational behavior.

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

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

The description is front-loaded with the key beta-vs-stable distinction and remains informative without excessive padding. It could be slightly tighter, but every sentence contributes to usage, current state, and operational expectations.

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-required-parameter tool with no nested objects, the description provides the needed operational context: experimental status, current equivalence to ask_pipeworx, use case, and the fully functional guarantee. It leans on ask_pipeworx for response shape details, but the description itself is clear about the shared response shape.

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

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

Schema description coverage is 100%, and the schema fully explains all six parameter aliases. The description adds no parameter-level detail beyond 'same arguments' as ask_pipeworx, which is marginal since the schema already documents the accepted aliases and question field.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, specifying it is a universal router with the same 5,564 tools, arguments, and response shape. It also explains that it currently matches ask_pipeworx exactly, which distinguishes it from the stable sibling tool while clarifying 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?

It gives explicit guidance: use it exactly like ask_pipeworx when the newest routing behavior is desired, and notes that results feed comparative routing decisions. It does not explicitly list alternatives or strict when-not-to-use conditions, but the stable ask_pipeworx sibling is implicitly the fallback/alternative.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral detail: refusal reasons (not_in_source, no_tool_match, etc.), return structure with evidence/quotes, and the guarantee that answers are extracted ONLY from tool results. 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 dense but every sentence adds distinct value: core value prop, mechanism, return format, refusal cases, use cases, and cost trade-off. It is well-structured and front-loaded with the most important information. No fluff.

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

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

Given the tool's complexity and lack of an output schema, the description fully covers return values, refusal behavior, use cases, and when to avoid. It also mentions cost and alternatives. This is a complete picture for an 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 coverage is 100% and the params are just aliases for 'question'. The description adds semantic value by explaining the tool automatically routes and fills arguments, meaning the user only needs to provide a natural language question. This goes beyond the schema and clarifies the mental model.

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 this is a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from tool results. It explicitly differentiates itself from the sibling ask_pipeworx by emphasizing grounded, evidence-based responses. The verb 'ask' is implied through the answer mode framing and use cases.

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

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

Explicitly provides when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off (one extra LLM call). This is ideal usage guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing detailed behavioral traits: low-confidence short-circuit with status 'low_confidence_match', closed-market handling via 'market_closed_or_inactive', tradeability warnings for wide spreads, news fallback fields (_fallback_attempted), and resolution-rule risk categories (refund_50_50, resolves_no_on_cancel). This provides a comprehensive safety profile and operational behavior.

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

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

The description is extremely long and detailed, but it is well-structured with capital-letter section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is front-loaded with a clear summary. However, it lists 16 classifiers and gives verbose examples that may exceed what an agent needs for tool selection, making it less concise than ideal.

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

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

With no output schema, the description must explain return values and edge cases. It does this exhaustively: response shapes for result.market/analysis/evidence, resolver contract with match confidence and suggestions, parent_event extractor, news fallback behavior, safety statuses, and cancellation rule risk. This is a highly complete description covering complex behavior comprehensively.

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

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

The input schema already provides detailed descriptions for all three parameters (market, depth, include_raw) with 100% coverage. The tool description adds some context (e.g., market can be slug, URL, or question), but this is also in the schema. No additional parameters are clarified beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a clear, specific statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details the core workflow (resolve, classify, fan-out, return evidence packet + comparison) and explicitly differentiates use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from sibling tools like polymarket_edges or deep_research.

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

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

The description provides explicit 'Use for' guidance with example query phrases and extensive fan-out examples, showing when the tool is appropriate. However, it does not explicitly mention alternatives or state when NOT to use the tool, so it falls short of a 5. The context is strong enough that an agent can infer appropriate usage.

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 specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This enriches the readOnlyHint and idempotentHint annotations with concrete operational details.

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 trigger phrases and usage priority, making the core purpose instantly clear. It is somewhat long but every sentence delivers value (data sources, fiscal year handling, sorting, return format). Minor redundancy in trigger examples, but still well-structured.

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 two entity types and no output schema, the description covers all essential aspects: accepted ranges, data sources, special edge cases (fiscal years), result ordering, and return format (paired data + URIs). It is sufficiently complete for a tool of this complexity.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains what each 'type' value actually retrieves (financial metrics for company, regulatory counts for drug) and gives concrete examples for 'values' (tickers vs drug names). This goes well beyond the bare schema definitions and helps the agent construct valid invocations.

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 a single parallel call, with explicit trigger phrases like 'X vs Y' and 'which is bigger'. It distinguishes itself from siblings by emphasizing the parallel nature and scope (companies/drugs), which is specific and unambiguous.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it replaces 8–15 sequential lookups. This directly tells the agent when to choose this tool over alternatives, making the usage context 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 richly discloses behavior: parallel routing to 5,564 tools, decomposition into facets, returns evidence with confidence/source/fetched_at, gaps[] for unanswerable facets, contradictions[], citations always fetchable, and timing. This goes well beyond the annotations, which only state read-only/idempotent/open-world.

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

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

While long, the description is information-dense with no filler; each sentence conveys a distinct constraint or behavior. It's front-loaded with the critical login requirement and ends with operational timing.

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 comprehensively covers return format, latency, failure modes (gaps[]), and dependencies (sign-in/plan). It also addresses edge cases like news topics and citation resolvability, leaving little ambiguity 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?

Both parameters are already fully described in the schema (100% coverage), but the description adds practical examples and clarifies that multi-part natural-language questions are acceptable. It also reiterates depth semantics in plain terms, reinforcing the schema and adding the paid-plan restriction not present in the schema.

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

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

The description clearly identifies the tool as a multi-source structured-data research engine, using action verbs like 'research', 'decomposes', and 'routes'. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its purpose unambiguous.

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

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

It provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also names alternatives: use ask_pipeworx for single lookups or breaking news, and notes account/plan requirements that direct to ask_pipeworx if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds meaningful behavioral context: it returns top-N results ready to call directly without a second schema lookup, and frames the tool as a first-step discovery mechanism. 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 front-loaded with the core purpose, followed by usage context, return value, and a strategic call-to-action. The list of data domains is somewhat long but informative for query formulation. No filler or redundancy, though it could be slightly trimmed without losing value.

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

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

Given the tool's simple yet meta-purpose, the description covers all necessary aspects: what it does, when to use it, what it returns (top-N tools with full schemas and examples), and how it fits into the broader tool ecosystem. With no output schema, the description explicitly explains return value. Annotations already cover safety, so nothing 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 description coverage is 100% with every parameter (query, q, task, limit, search, description) fully documented, including alias relationships. The description does not add parameter-level details beyond the schema; it mentions the domains the query can describe, but that's query guidance rather than new parameter semantics. Baseline of 3 applies when schema does the heavy lifting.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly states the verb (find), resource (tools), and mechanism (describing data/task). It also differentiates from siblings by positioning this as a meta-tool for discovery, listing a broad set of domains it covers.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and even hints at a when-not (when you want a single answer rather than the option set).

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?

It discloses concrete behavioral details beyond the annotations: fans out across multiple sources, returns specific fields, soft-fails due to USPTO PatentsView sunset, and falls back from GDELT to GNews. This gives the agent a realistic picture of side effects and failure modes.

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 intent examples and every sentence carries operational value. It is somewhat verbose, but the complexity of the multi-source fan-out justifies the length.

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

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

Since there is no output schema, the description enumerates the returned fields (cik, recent_filings, fundamentals, patents, news, LEI) and includes limitations and fallback behavior. This is thorough and sufficient for an agent to anticipate the tool's full behavior.

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

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

The input schema already provides 100% coverage for both parameters, including examples and the 'names not supported' caveat. The description repeats this information without adding new semantic depth, so it stays at the schema-driven 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 uses specific verbs and clearly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by naming resolve_entity as the correct alternative when only a name is available, and contrasts with chaining single-pack SEC/XBRL/news 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?

The description explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, giving clear when-to-use guidance. It also provides a when-not-to-use rule: names are not supported and resolve_entity should be used instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat those. It adds context about clearing sensitive data and implying the action affects previously saved agent memory, which is useful 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?

Two sentences: the first states the purpose, the second provides usage context and sibling pairing. Every word earns its place, with no redundancy or unnecessary detail.

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

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

For a simple single-parameter deletion tool with strong annotations (destructive, idempotent) and no output schema, the description completely covers what it does, when to use it, and how it relates to siblings. Nothing essential is missing.

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

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

The schema already fully describes the only parameter 'key' with its description 'Memory key to delete' (100% coverage). The description adds no additional parameter meaning beyond what the schema provides, 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 the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory by key), and distinguishes it from sibling memory tools like 'remember' and 'recall'.

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

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

Explicitly tells when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools ('Pair with remember and recall'), providing clear alternative guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior; the description adds that it fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. This helps the agent understand the process and output without contradicting annotations.

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

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

The description is three sentences: what it does, how it works, and when to use it. It's front-loaded with the core function and contains no filler or 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?

The description covers purpose, process, output format, and typical use cases. Since there's no output schema, it correctly describes the single text blob result. It's sufficient for this moderately simple tool, though mentioning alternatives would make it complete.

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

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

The input schema fully covers both parameters (url and max_links) with descriptions, so the schema does the heavy lifting. The tool description doesn't add param-specific details beyond what's already in the schema, making the baseline 3 appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file for any URL'), clearly distinguishing this from sibling tools by focusing on the llms.txt standard. It also explains the purpose: helping AI crawlers index a site cleanly.

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 lists concrete use cases: getting a client's site indexed, drafting llms.txt for your own project, or auditing competitive AI visibility. It doesn't explicitly name alternatives or exclusions, but the context is clear enough to differentiate from sibling research 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 declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds value by specifying what the schema includes—fields with names/types, geometry type, record count, and capabilities—giving the agent a precise mental model of the response. It doesn't cover potential errors, but the read-only nature is fully disclosed.

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

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

The description is a single, front-loaded sentence that wastes no words. It states the action, resource, and delivery method, making it optimal for quick parsing.

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 a single parameter and no output schema, the description carries the burden of explaining the return value. It explicitly lists all major schema components, leaving no ambiguity about what the tool produces. The inclusion of both Feature and Map Services broadens applicability without adding bulk.

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 of the 'url' parameter with a brief description and example. The tool description reinforces that the parameter is the URL but adds no new syntax or format details beyond the schema. Thus a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Get' and names the resource 'ArcGIS Feature/Map Service layer's schema', clearly distinguishing it from sibling data-querying tools like query_layer. It lists the exact contents returned (fields, geometry type, record count, capabilities), making the tool's purpose unmistakable.

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

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

The description implies usage when a layer's schema is needed, given a service URL. It doesn't explicitly name alternatives like query_layer, but the focus on schema rather than data provides clear context. No exclusions are stated, but the tool's scope is well-scoped to metadata retrieval.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds the default behavior of only including active subscriptions (via 'active' and later schema default) and lists return fields, which provides useful context beyond annotations.

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

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

Two concise sentences. The first explains the function and return fields; the second gives practical usage. Every word earns its place, with no redundancy or filler.

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

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

For a simple listing tool with no output schema, the description lists expected return fields and provides usage context. It lacks explicit mention of pagination or rate limits, but these are not critical for a read-only, idempotent tool with a single optional parameter.

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%, with the only parameter include_inactive fully described in the schema ('Include cancelled subscriptions in the response (default false)'). The description adds no further parameter semantics, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('List'), clearly identifies the resource ('subscriptions'), and scopes it to 'the caller's active' subscriptions. It also distinguishes itself from siblings like subscribe/unsubscribe by focusing on read-only listing.

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

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

Explicitly states when to use: 'before adding more' (linking to subscribe) and 'to find an id to cancel' (linking to unsubscribe). This gives clear context for the tool's role among siblings, though it doesn't mention alternatives.

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

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

Annotations are all false, offering no safety hints. The description fills this gap thoroughly: it discloses rate-limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token mechanism for anonymous reports, follow-up behavior, and team review process. This is rich behavioral context well beyond the annotations.

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

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

The description is detailed but every sentence earns its place: purpose, when-to-use, exclusions, formatting rules, follow-up mechanism, rate limits, and quota. The structure front-loads the purpose and then layers usage constraints and operational details logically. It is long but not wasteful.

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

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

This is a feedback tool with no output schema, yet the description adequately explains the return behavior (claim_token and later status via that token). It covers what to report, prerequisites (none), follow-up, and constraints. Given the schema already documents parameters thoroughly, the description provides all necessary operational context.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining the special usage of claim_token (pass it back to read resolution) and giving guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.'). This adds semantic value for two of the four parameters beyond schema 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 clear verb-object statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is specific about the resource (Pipeworx team) and the action (submitting feedback), and it clearly distinguishes this tool from sibling tools like 'ask_pipeworx' or 'discover_tools'—it is explicitly for reporting issues/praise to the team.

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 when to use the tool (bug, feature/data_gap, praise) and, importantly, when NOT to use it: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This provides direct alternative guidance and eliminates 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?

The description adds significant behavioral context beyond annotations: 'derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h.' This covers data provenance, privacy, and caching, which is valuable and not redundant with the annotation hints.

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

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

Three dense sentences with no wasted words. The core function is front-loaded, followed by specific use cases and then data provenance/caching details. 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?

For a simple tool with one optional parameter and no output schema, the description adequately covers return contents, use cases, and data characteristics. It could include a more explicit output structure example, but is largely complete.

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

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

Schema description coverage is 100% for the single 'window' parameter, including default and comparative behavior. The tool description simply repeats the same information without adding new syntax or format details, so the baseline 3 applies.

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

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

The description explicitly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It clearly distinguishes itself from siblings like discover_tools by focusing on what other AI agents are calling, with a self-aggregating signal.

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 three concrete use cases under 'Useful for:'. However, it does not explicitly mention when not to use the tool or name alternative tools, so it lacks exclusionary 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 (readOnly, idempotent, non-destructive), the description discloses critical runtime behavior: fill check pricing against live CLOB depth, the realizable_edge_pp <=0 warning, Jaccard similarity threshold, and placeholder filtering. These details prevent misuse and set correct expectations, with no contradiction to annotations.

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

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

The description is long but efficiently organized: opening summary, mode breakdown, semantic anchor, partition filter, response format, fill check. Every sentence carries specific operational detail; 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?

The tool has no output schema, but the description compensates by listing the response fields (opportunities[], partition_check{sum_yes_prices, gap_from_1, ...}) and explaining edge cases like thin_legs. It also covers input modes, filters, and safety checks, making it fully contextualized.

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 documents both parameters (100% coverage), the description enriches them with concrete examples ('fed-decision-may-2026'), mode-specific behavior, and expected outputs. This far exceeds schema descriptions and gives the agent actionable semantics.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which clearly states the tool's function. It further distinguishes modes (trending_scan, event, topic) and contrasts with sibling tools, making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative for a related task: 'For custom sizing use polymarket_fill_risk', and explains why cross-event mode is valuable.

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 the tool as read-only, open-world, and idempotent, the description adds valuable behavioral context: caching ('Cached 1h at the KV level keyed on all knobs'), Kelly caps (0.25), the fact that partition kelly_fraction_half is always 0 at parent level by design, the warning about 24h moves, and the diagnostics for why segments may be empty. This significantly exceeds the 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 long and dense, with extensive technical details and acronyms (GDELT, EFFR, OIS/SOFR). While it is front-loaded with the core purpose and internally sectioned, the sheer volume may hinder quick scanning by an agent. Some information could be condensed, but every sentence does add value for 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?

With no output schema provided, the description compensates by fully describing the response structure: by_segment, fed_candidates/fed_note, and _diagnostics. It also covers edge cases (empty segments, stale markets, knob interactions) and explains limitations (e.g., Fed signal reliability). This makes the tool's behavior and output expectations clear, so it is very complete.

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

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

The schema descriptions already cover all 9 parameters, but the description goes far beyond by providing rationale and real-world context: slippage_pp is presented with Polymarket fee structure and typical spread observations, min_liquidity and max_spread_pp are explained as 'tradeable-edge' filters with concrete examples, and min_partition_leg_kelly clarifies the non-obvious behavior of partitions. This is a substantial enrichment over the schema.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes from siblings by naming the three model families and response segments, making the tool's unique function clear.

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

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

The description explicitly states the intended use case ('Built for "what should I bet on today"') and explains how it avoids paging hundreds of markets. It also clarifies exclusions (e.g., Fed bets excluded from ranking) and provides pragmatic knob suggestions (e.g., 'Set to 2 to require tight books'). However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so a small gap remains.

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, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: snapshot TTL limits, cache-miss snapshot creation, data-gap meaning, decay calculation from daily closes net of default slippage, and non-intraday nature. It also details the response shape and semantics, far exceeding what annotations alone convey.

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

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

The description is front-loaded with the core purpose, then structured into Args, RESPONSE, and LIMITS sections. Every sentence adds specific, useful information, and the formatting makes the lengthy content scannable. It is appropriately dense for a tool with this complexity.

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

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

With no output schema, the description fully compensates by specifying the response structure (tracked[], expired[], snapshot_dates[]) and key details like lifespan_days and decay_pp_per_day. It also explains historical depth limitations and calculation methodology, making the tool's behavior and outputs adequately 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 description coverage is 100%, so the baseline is 3. The description largely restates the schema defaults and constraints (days lookback default 14 max 30, window snapshot family default 1wk) without adding new parameter-level meaning. It does add a small amount of context by tying parameters to snapshot families, but no significant extra semantics.

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

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

The description opens with a specific verb and resource: 'edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes this tool from its sibling polymarket_edges by focusing on historical persistence and decay rather than current edges, and it frames the core question it answers.

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 contrasting a fresh wide edge with a 3-week-old wide edge, saying they are different trades. It provides strong contextual guidance but does not explicitly name alternative tools or state when not to use this one, so it stops short of a full 5.

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

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

Annotations declare read-only/open-world/idempotent/non-destructive. The description adds operational context: walking the ladder, return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), basket-level concepts (capture_ratio, thin_legs, forced_directional_risk), and the risk of partial fills. No contradiction.

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

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

The description is dense but well-structured: leads with the core purpose, then partitions single-market vs basket, enumerates outputs, and closes with explicit usage guidance. Every sentence carries necessary information for a complex two-mode tool; no filler.

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

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

Despite no output schema, the description lists all major return fields for both modes, explains the interpretation of size and side, describes the risk scenario, and names the sibling tools. It is fully self-contained for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but description enriches each parameter: side gains mode-specific meaning (default auto in basket based on partition sum), size_usd is interpreted differently for buys vs sells and as settlement notional in basket mode. It also clarifies the requirement to pass exactly one of market or event. This adds significant meaning beyond schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two clear modes (single-market and basket) and contrasts itself from sibling tools by targeting fill risk rather than opportunity discovery.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills cause directional risk), giving clear when/when-not direction.

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 extensively discloses behavioral nuances beyond the read-only/idempotent annotations: it explains compatibility_warning conditions (matched_pairs vs skipped_cross_type), temporal_alignment semantics, skipped_cross_type/subtype counters, and the fact that syntactic matches do not imply economic equivalence. This is rich, actionable context that fully informs the agent of 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 long and dense, but every sentence carries operational value—purpose, modes, response contents, and important safety semantics. It is front-loaded with the core purpose and uses clear structural cues (TWO MODES, RESPONSE, SAFETY FIELDS). It is not as terse as ideal, but the complexity of the tool justifies the length.

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

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

With no output schema, the description fully covers the return value semantics: leg-by-leg prices, top_spreads_pp, compatibility_warning with two distinct scenarios, temporal_alignment, and skipped counter meanings. It also explains the two invocation paths and the practical limitation that most pre-mapped topics are not tradeable, making it a complete guide for an agent.

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

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

The schema already covers 100% of parameters, but the description adds meaningful context: it enumerates the 10 topic shortcuts, explains that kalshi_event_ticker and polymarket_event_slug override the topic mapping, and clarifies the two-mode invocation pattern. This goes beyond the schema's baseline, meriting a 4.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the verb (compare), the resource (cross-venue spread), and the two specific venues, distinguishing it from intra-Polymarket tools. It also details two operational modes (topic shortcuts and explicit event identifiers), 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?

Clear context is provided on how to invoke the tool (topic vs explicit pairings) and there is a valuable warning that pre-mapped topics are often not tradeable, which guides appropriate use. However, it does not explicitly name alternative tools or state when to use another sibling (e.g., polymarket_arbitrage), 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns attribute rows and geometry, and suggests a sampling technique, which are useful behavioral details beyond the annotations. No contradictions.

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

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

The description is concise (three short sentences) and front-loaded with the core purpose. The parameter list is redundant with the schema but still serves as a quick overview; 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 a fully documented schema, comprehensive annotations, and a description covering purpose, URL origin, return shape, and sampling, the tool is well-specified for invocation. No output schema exists, but the description sufficiently clarifies the return type.

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

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

Schema coverage is 100% with detailed descriptions and examples for all parameters. The description lists the same parameters without deeper semantics; the sampling trick is a minor addition. Baseline 3 is appropriate since the schema carries the semantic burden.

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

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

The description clearly states the tool queries an ArcGIS Feature Service or Map Service layer by URL, sourced from search_datasets. This specific verb+resource+origin distinguishes it from siblings like layer_info (metadata) or search_within (spatial 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?

It implies a workflow by referencing search_datasets and provides a concrete sampling example (where='1=1' + out_fields='*'). However, it doesn't name alternative tools or explicitly state when not to use it, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the listing behavior when key is omitted. No contradictions.

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

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

Three sentences, front-loaded with the core action. Every sentence provides distinct information: the operation, the use case, and scoping/relationships. No redundant 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, annotations, and no output schema, the description covers the operation, usage context, scoping, and sibling tool relationships. No critical gaps remain.

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

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

Schema coverage is 100% (the key parameter is described in the schema). The description adds meaning beyond the schema by explaining the value types stored (ticker, address, notes), the 'omit to list all' behavior, and the relationship to remember/forget, going beyond the schema's one-line 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 opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools by explicitly naming remember and forget and contrasting retrieval with saving and deleting.

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

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

It states when to use the tool: 'Use to look up context the agent stored earlier', with concrete examples. It references sibling tools ('Pair with remember to save, forget to delete') but does not explicitly state when not to use it or name alternative non-memory 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?

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds critical behavioral nuance: mark_read:true triggers a side effect (marking events read, affecting future calls). It also describes the persisted feed, return payload composition, and the external HTTP mirror. No contradiction with annotations — the readOnly hint is qualified.

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

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

Four sentences, each earning its place: purpose, return contents, filtering and state flag, and polling/alternative. Front-loaded with 'Pull fired events' and no fluff.

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

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

For a read-style tool with no output schema, the description covers the return shape (source, citation_uri, raw payload), filtering, mark_read side effect, and alternative access. The annotations and 100% parameter descriptions fill the rest. No significant gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning for type (concrete example 'sec_8k'), since (ISO timestamp semantics), and mark_read (effect on future calls). It doesn't elaborate on limit or unread_only, but those are straightforward from 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 'Pull fired events from your subscription feed' — a specific verb and resource. It further clarifies it returns alerts from the evaluator's persisted feed with source, citation_uri, and raw payload, which distinguishes it from sibling tools like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes).

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 offers explicit usage context: 'Polls work fine' tells agents the tool is safe to poll, and 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards' provides an alternative for non-interactive use. It does not explicitly name when to avoid this tool in favor of a sibling, but the filtering and mark_read guidance clarifies common use cases.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses fan-out to SEC EDGAR, GDELT→GNews fallback logic, PatentsView API sunset causing soft-fail, and the structured return format. This is rich behavioral context that annotations alone don't 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?

Despite being long, every sentence is substantive: example queries, source fan-out, fallback, soft-fail, parameter syntax, return structure, and alternative tool. It is front-loaded with practical examples and avoids fluff.

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

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

For a complex multi-source tool with no output schema, the description explicitly specifies return format (changes[], total_changes, citation URIs), covers all input parameters, and explains failure modes. It also mentions when to use a sibling tool, making it highly complete.

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

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

Schema covers all three parameters with descriptions (100% coverage). The tool description reinforces `since` syntax and value formats but adds extra context by explaining how `since` drives filings, news window, and patents. It doesn't introduce new parameter details beyond the schema, but its examples improve usability.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific example queries. It explicitly contrasts with sibling entity_profile ('Use entity_profile instead when you want the static profile'), distinguishing it from a related tool.

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

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

Gives explicit usage scenarios with example natural-language queries and specifies when to use entity_profile instead. Also describes fallback behavior (GDELT→GNews, USPTO soft-fail), providing 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?

Annotations already convey idempotency and non-destructiveness, and the description adds persistence details (persistent for authenticated users, 24-hour retention for anonymous sessions) and key-value scoping. This goes beyond annotations, though overwrite behavior on existing keys is not explicitly stated (but implied by idempotency).

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

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

Three sentences, front-loaded with the primary action, followed by usage context and storage specifics. Every sentence adds value without redundancy.

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

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

For a simple two-parameter tool with no output schema and non-destructive annotations, the description covers purpose, usage, persistence, and sibling relationships. It omits explicit mention of overwrite behavior, but the idempotent hint implies this, making it adequate for an AI agent.

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

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

Schema coverage is 100% with descriptions for both 'key' and 'value', including examples. The description repeats the key-value concept but does not add new parameter-level information, so the baseline of 3 applies.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'save' and resource 'data'. It distinguishes from siblings by naming 'recall' for retrieval and 'forget' for deletion, avoiding confusion.

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 when to use: 'Use when you discover something worth carrying forward' with concrete examples like resolved ticker or user preference. It also points to alternatives by saying 'Pair with recall to retrieve later, forget to delete,' so the agent knows which tool to pick for related operations.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), the description adds rich behavioral detail: 'LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return', 'Each call cascades through several lookup endpoints internally', and 'every identifier is labelled with the source that established it, and an identifier that could NOT be resolved is stated explicitly under `unresolved`'. This fully discloses the tool's behavior and error handling.

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

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

The description is comprehensive but could be more concise. It front-loads the key purpose with examples, but the single paragraph format is dense and repeats some information (e.g., the list of supported types is mentioned both in examples and in the type explanation). However, every sentence adds value, and the structure is logically organized from examples to supported types to edge cases. Still, it's slightly longer than ideal for quick scanning.

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

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

Given the tool has no output schema, the description compensates by thoroughly explaining what the return data contains (identifiers with source labels, unresolved list). It covers edge cases (degradation of LEI/FIGI, ISIN-to-LEI mapping for non-US issuers). For a two-parameter tool with complex resolution logic and two entity types, the description is remarkably complete, leaving no major gaps for an AI agent to guess.

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%, but the description adds substantial meaning beyond the schema. For the `type` parameter, it explains what each enum value resolves ('company' gives a cross-source identity spine; 'drug' gives RxCUI + ingredient + brand). For the `value` parameter, it provides accepted formats (ticker, CIK, ISIN, name for company; brand/generic names for drug) and explains special case: 'an ISIN like

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

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

The description uses specific verbs ('resolve', 'look up', 'find') and resources ('ticker', 'CIK', 'LEI', 'RxCUI') and clearly states the tool's purpose: converting user-spoken names to canonical/official identifiers. It distinguishes itself from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID', positioning it as a prerequisite for other entity tools like `entity_profile`.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID', providing clear context for when to invoke this tool. It implies when not to use (e.g., if you already have an ID, use other tools like `entity_profile`). While it doesn't name alternative tools directly, the sibling list and the phrase 'replaces 2-3 manual lookups' give strong usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context beyond annotations by noting it 'Probes each entity ... with ai_visibility_check' and returns a ranked list with score, confidence, and signal density. This reveals its composite nature and output format, which is valuable additional transparency.

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

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

The description is two sentences, front-loaded with the core action ('Compare AI visibility...'), and every clause adds value. It avoids fluff and efficiently covers purpose, method, use case, and output.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description is fairly complete. It states the output shape ('ranked list with score, confidence, signal density per entity') and provides usage context. Potential gaps like limits on entity count are covered in the schema, so the description suffices.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond what the schema already provides; for instance, the entities parameter description already mentions 'First entry treated as the subject.' The schema itself is comprehensive, so the description's parameter-related contribution is minimal.

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.' It uses specific verbs (compare, ranks, surfaces) and resource (AI visibility), and explicitly distinguishes itself from the sibling ai_visibility_check by noting it probes each entity with that tool. This makes the purpose unambiguous.

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

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

The description provides clear usage context by stating 'Useful for competitive AI-marketing audits' and gives a concrete example query. It implies when to use this tool versus a single-entity check but doesn't explicitly name alternatives or provide exclusions. The guidance is adequate but not exhaustive.

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

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

The description discloses substantial behavior beyond the annotations: it fans out to two external services, returns a summary block with 10 named fields, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30s with sources_failed listing timeouts. It also clarifies ecosystem scope. This aligns with the readOnly/idempotent hints without contradicting them.

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

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

The description is structured in five sentences, each earning its place: purpose, usage triggers, return fields, ecosystem scope, and failure handling. It is front-loaded with the core purpose and remains information-dense without fluff. The length is justified given the composite nature and multiple behavioral nuances.

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 services, partial failures, timeouts, return schema not provided), the description covers all essential aspects: what it does, what it returns, when to use it, edge cases (first measurement delay), and compatibility limits. It is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

The input schema already provides 100% coverage for both parameters (package name, version) and includes notes on scoped packages and default version. The description adds little new param meaning beyond what the schema already states, so the baseline of 3 applies. It does mention the composite nature but that is not param-specific.

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

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

The description opens with a specific verb and resource: "Composite 'should I add this npm package to my project' check in ONE call". It clearly states the tool scans an npm package across deps.dev and bundlephobia, and lists the exact return fields. This distinguishes it from sibling tools like scan_competitor_ai_presence and search_within.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', giving clear trigger conditions. It also states an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative path for non-npm packages.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description supplements this by detailing the return fields (name, summary, record_count, owner/org, url) and the data source scope, which are behavioral traits not captured by annotations or schema.

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

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

Two sentences, no wasted words. The first sentence states the core purpose and scope; the second states the output and actionable next step. Both sentences carry essential information, and the description is front-loaded with the action verb.

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 search tool with fully documented params and strong annotations, the description is complete. It explains what the tool returns, the domain (Harrisburg GIS), and how the output connects to sibling tools. No output schema is needed because the description explicitly lists the return 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 description coverage is 100%, so the schema fully documents all three parameters. The description does not add parameter-specific meaning beyond mentioning keyword search, which is already covered by the query parameter description. It meets the baseline of 3 but adds no extra value.

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

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

The description uses a specific verb ('Search') and identifies a clear resource ('City of Harrisburg GIS open geospatial datasets') and scope ('by keyword'). It lists example dataset categories and explicitly distinguishes the tool from siblings by stating that the returned URL can be passed to query_layer/layer_info.

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

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

The description provides clear context for when to use this tool (discovering geospatial datasets) and gives concrete downstream guidance ('pass that url to query_layer / layer_info'). It does not explicitly state when not to use it or compare with alternatives, but the workflow context is strong.

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?

Description adds implementation details beyond annotations: returns top-N passages with character offsets/similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char windows, and has a 200K char cap with truncation flagging. No contradiction with readOnly/idempotent hints.

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

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

Concise 3-sentence structure: definition, use case, technical specifics. Every sentence serves a purpose; front-loaded with the core function.

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

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

Despite no output schema, the description mentions return contents (offsets, scores). It covers algorithm, limits, and integration with a sibling tool, making it complete for an agent to decide and use.

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

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

Schema already covers all 3 parameters at 100% coverage, so baseline is 3. Description enriches by giving concrete examples of what 'text' can be (SEC 10-K body, article, tool result) and clarifying the query style, which adds value over 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?

Clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. Distinguishes from siblings by emphasizing it operates on already-fetched text and references ask_pipeworx_grounded as a paired tool.

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

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

'Use when the record is too big to cram into the prompt' is explicit when-to-use guidance. Also suggests a workflow pairing with ask_pipeworx_grounded, showing how to combine 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?

The description adds behavioral context beyond annotations by disclosing the OAuth requirement, SMS phone verification and daily cap, and the always-on feed. It also notes the return of a subscription id. While annotations indicate idempotentHint=true, the description does not directly address idempotency, but this is a minor gap given the useful context provided.

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 substantive and well-structured, opening with the core purpose and then covering requirements, types, and delivery channels in a logical order. Each sentence carries useful information, though the length is relatively high. It avoids redundancy and tautology.

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

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

Given the tool's complexity (multiple subscription types, nested params, delivery options) and lack of output schema, the description covers the essential operational details: OAuth requirement, return value, supported types, delivery channels with limitations, and how to pull the feed. It does not address error handling or idempotency, but overall it is adequately complete for a create-type 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 has full coverage, giving a baseline of 3. The description enriches parameter understanding by explaining type-specific params with concrete examples (e.g., sec_8k items:["5.02"] = officer change, fred_series series_id:"UNRATE") and clarifying delivery channel semantics beyond the schema. This adds practical meaning to how the params are used.

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 action: "Create a proactive monitoring subscription to a live-data event stream." It specifies the resource (live-data event stream), the return value (new subscription id), and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist), explains supported subscription types with examples, and describes delivery channels including an always-on feed. It provides a clear exclusion (anonymous users) and hints at consumption via recent_alerts. However, it does not explicitly name alternative tools for related tasks (e.g., listing or unsubscribing).

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive, so the bar is lower. The description adds valuable context: it returns category-bucketed examples with exact tool+argument shapes, and explains the optional topic parameter's effect. 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 dense but well-structured: front-loaded with natural language query examples, followed by return format, parameter usage, and guidance. Every sentence contributes, though it's slightly lengthy for a simple one-parameter 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 simple tool with one optional parameter and no output schema, the description is thorough: it explains return structure, covers the no-argument case, provides the topic variants, and connects to broader workflow (learning meta-tools). Nothing critical is missing.

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

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

Schema already documents the topic parameter, so baseline is 3. Description enhances this by providing concrete example values ('finance', 'pharma', 'betting') and clarifying that omitting it yields a cross-category spread, which adds meaning beyond the schema's brief 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 as the onboarding entry point with specific verbs ('returns category-bucketed example questions') and resource ('live catalog of thousands of tools'). It distinguishes from siblings by explicitly positioning it as the first tool to use when unfamiliar with Pipeworx, and even references the meta-tools it teaches.

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

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

Provides explicit context for when to use ('Use this FIRST when you do not yet know what Pipeworx can do for you') and what it teaches (how to call meta-tools). It doesn't explicitly list when-not-to-use or name alternatives like discover_tools, but the 'FIRST' directive effectively excludes other discovery 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 cover the write, open-world, idempotent, and non-destructive hints, but the description adds valuable context: ownership is enforced, the row is deactivated (not deleted), and historical events remain available via recent_alerts. This goes beyond the annotations to explain side effects and persistence semantics.

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

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

The description is three concise sentences, each adding distinct value: the action, the ownership constraint, and the behavioral consequence. There is no redundancy or fluff; the most important information is front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: operation, precondition, and post-cancellation behavior. It does not elaborate on error handling or return values, but given the tool's simplicity and the rich annotations, this is sufficient.

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

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

The schema already fully describes the 'id' parameter as a subscription uuid returned by subscribe. The description adds an important semantic constraint: ownership is enforced; you can only cancel your own subscriptions. This enriches the parameter's meaning beyond the schema.

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

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

The description clearly states the verb 'Cancel', the resource 'subscription', and the method 'by id'. It also distinguishes from siblings by mentioning ownership enforcement and the consequence (deactivation, historical events remain), leaving no ambiguity about its function.

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 conveys a clear use case: cancel a subscription when you want to stop alerts. It also notes ownership is enforced, which is a precondition. However, it does not explicitly contrast with alternatives like subscribe or list_subscriptions, though these are obviously different operations.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: the two processing paths (SEC EDGAR/XBRL and grounded pipeline), the return verdicts, and important edge-case semantics (could_not_verify means the check didn't happen, not evidence; unsupported means no source exists). This adds significant behavioral context not present in annotations.

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

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

The description is dense but every sentence earns its place: examples, usage, routing, output, edge-case warnings, and efficiency note. It is appropriately sized for a complex tool and well-structured with clear flow from definition to 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 no output schema, the description thoroughly explains return values (verdicts, value, citation) and error handling (verification_error). It covers both financial and non-financial paths, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches both parameters: it gives concrete claim examples and explains tolerance_pct's range, override effect, and default behavior. This exceeds what the schema provides, making parameter usage much clearer.

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 purpose: natural-language claim verification against authoritative sources, with clear trigger examples ("fact check", "verify the claim that..."). It distinguishes itself from sibling tools by focusing on fact-checking with verdicts and citing the structured/grounded pipeline, and notes it replaces sequential calls.

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

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

It provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the routing for company-financial vs. any other factual claims, effectively telling when to use this tool vs. alternatives. Though it doesn't name specific sibling tools, the context of fact-checking is unambiguous.

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