Arcgis Peoria

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it discloses that probing Anthropic requires a BYO key and that 'you pay Anthropic directly for those calls,' implying external network calls with cost implications. It also details the default model (Workers AI Llama-3.3-70b free) and the return structure, providing transparency about side effects and 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 three sentences long, front-loaded with the core purpose, followed by key configuration details and return format. Every sentence provides necessary information without fluff or redundancy.

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

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

The tool has no output schema, so the description compensates by explicitly listing the return shape: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also explains the default behavior and cost implications of using Anthropic. It is nearly complete, but could add a note about potential rate limits or error handling, though these are not critical for a read-only probe.

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 each parameter already having a descriptive comment (e.g., `_apiKey` explains it is passed straight through to api.anthropic.com). The description adds little beyond the schema, mainly clarifying the default model. Baseline 3 is appropriate as the schema carries the parameter 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 clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb (probe), resource (LLMs), and output (visibility score). This distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on cross-model visibility scoring rather than competitor-specific scanning.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives context on when to use the tool. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5 but is above a 3.

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

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

Beyond the readOnly/idempotent annotations, it discloses internal behavior: routing across 5,501 tools, argument filling, stable citation URIs, and single-call speed. It also states tier availability and that it already covers live news for breaking-news queries.

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

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

The description is lengthy but each part serves a purpose: orientation to prefer it, domain list, trigger examples, escalation paths. The structure is front-loaded with the strongest directive and every sentence earns its place.

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

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

For a tool without an output schema, it explains the structured answer with citations and addresses edge cases like breaking news and broad research. Combined with rich annotations, it leaves no major operational gap.

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

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

The schema already documents the 'question' parameter and its six aliases at 100% coverage. The description does not add parameter-specific semantics beyond examples, so it stays at the baseline.

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

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

The description clearly identifies the tool as a question-answering router for authoritative structured data with citations, listing concrete domains and example queries. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default fast entry point.

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 instructs to prefer this over web search, provides trigger phrases like 'what is', 'look up', and 'get the latest', and names specific alternatives for grounded answers and multi-part research. It also clarifies coverage of breaking news and when to use deep_research.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds crucial context about live candidate routing improvements and that no candidate is currently active, so it currently matches ask_pipeworx exactly. This goes beyond the safety profile to explain dynamic 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 somewhat longer than necessary but front-loads the key purpose and is well-structured with clear progression: beta variant, identical behavior, current status, usage, and fallback. Every sentence contributes relevant 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?

Despite having no output schema, the description fully covers what the tool does, its relationship to ask_pipeworx, current behavior (no active candidate), and how to use it. It is complete enough for an agent to select and invoke it correctly.

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

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

The input schema has 100% coverage with descriptions for all 6 parameters, including aliases. The description only says 'same arguments' without adding new param details, so the schema carries the full 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 opens with 'Beta version of ask_pipeworx' and immediately clarifies it is 'identical universal router (same 5,501 tools, same arguments, same response shape)'. This clearly identifies the tool as a variant of the sibling ask_pipeworx, distinguishing it as the experimental version.

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

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

Explicitly tells the agent to 'Use it exactly like ask_pipeworx when you want the newest routing', and notes results are compared against the stable router to decide merges. This provides clear when-to-use guidance, though it does not explicitly state when not to use it.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavioral traits: it extracts answers using only tool result content, may return explicit refusals with enumerated reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and includes evidence quotes and confidence scores. It also explains the extra LLM call cost and routing behavior, adding significant context beyond structured annotations.

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

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

The description is front-loaded with the core value proposition ('Hallucination-resistant answer mode'), then logically sequences what it does, what it returns, when to use it, and the cost tradeoff. Every sentence provides essential information, with no superfluous content. The structured refusal reason enumeration is efficiently packed into a compact list.

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 that there is no output schema, the description thoroughly explains the return format: success returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, and failure returns an explicit refusal object with all possible refusal reasons. It also covers routing scope, use cases, and cost, providing complete context for an agent to decide when and how to use this tool.

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

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

The input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds context that the question will be used to 'fill arguments' for routing across 5,501 tools, which enriches the semantic understanding of how the question parameter is utilized. This goes slightly beyond the schema description by clarifying the question's role in the tool's internal workflow.

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 is a 'hallucination-resistant answer mode' for high-stakes reads, explicitly contrasting with sibling ask_pipeworx by emphasizing extraction only from tool results and explicit refusals. It names the specific resource (Pipeworx tools/sources) and behavior (routing, fetching, extracting), making it easily distinguishable from siblings.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists examples (financial verdicts, legal claims, medical lookups, public statements). It also states when not to use it ('prefer ask_pipeworx for casual lookups') and notes the cost tradeoff ('Costs one extra LLM call'), directly addressing alternatives.

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

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

Even with annotations already declaring readOnlyHint and idempotentHint, the description goes far beyond them by detailing fan-out behavior, resolver confidence states, low-confidence short-circuiting, closed-market status, illiquidity warnings, and cancellation-rule parsing. This gives agents a thorough map of how the tool behaves and what can go wrong, with no contradictions.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, RESOLUTION-RULE RISK) that make it scannable. Every major section adds necessary operational detail, but it is verbose enough that a more concise version could preserve the same 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 complexity and the absence of an output schema, the description is exceptionally complete. It documents the response shape, resolver contract, parent_event extraction, news fallback behavior, blocking conditions, and cancellation-rule implications. This gives an agent everything needed to invoke the tool and interpret results safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description largely restates the schema's parameter semantics (market accepts slug/URL/question text, depth defaults to thorough, include_raw default false) and does not add significant new meaning beyond the schema. Some useful context around fan-out examples exists, but it does not materially enrich parameter understanding.

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 specifies a clear verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides concrete query intents ('should I bet on X', 'what does the data say about Y'), which distinguishes it from generic research tools. However, it does not explicitly name sibling tools or contrast itself with alternatives like ask_pipeworx or deep_research, so it stops short of a full 5.

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

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

Usage context is explicit: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' plus numerous domain examples (crypto, Fed, sports, elections). It gives clear when-to-use signals, but it lacks explicit when-not-to-use guidance or named alternatives, so it misses the top score.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral detail: pulls from SEC EDGAR/XBRL for companies and FAERS for drugs, correctly handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. 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 dense but every sentence earns its place: trigger phrases, entity types, data sources, sorting, output format, and efficiency gains. It is front-loaded with the most relevant usage signals and contains no filler.

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

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

For a tool with two parameters and no output schema, the description is thorough. It covers when to use, input format, data sources, edge cases (off-calendar fiscal years), and return format (paired data + citations). This is sufficient for an agent to select 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%, so both parameters are already described. The description adds meaningful context beyond the schema: examples for each type (AAPL/MSFT, ozempic/mounjaro), what data is pulled per type, and behavior like fiscal-year handling. This enriches understanding above the baseline.

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

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

The description clearly states the tool's purpose: comparing 2–5 companies or drugs in one parallel call. Trigger phrases like 'X vs Y' and 'which is bigger' make it easy to identify when this tool applies. It also distinguishes itself from sequential lookups, making it distinct from sibling tools such as 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 provides strong when-to-use guidance: any comparison request (e.g., 'X vs Y', 'rank these companies') and explicitly says to prefer this over 8–15 sequential lookups. It implies when not to use (for a single entity) by limiting to 2–5 entities, but does not explicitly name alternative tools like entity_profile for single-entity 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 annotations (readOnly, openWorld, idempotent), the description discloses account tiers, output packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), hop semantics, semantic excerpting behavior, and expected latency (15-90s). This fully discloses how the tool behaves and what it returns.

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

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

The description is long but well-structured, with each sentence adding substantive information about purpose, usage, limits, output, and timing. It front-loads the critical account note and then flows logically through function, use cases, alternatives, and behavior. While lengthy, the density of valuable detail justifies the size.

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 is remarkably complete: it covers prerequisites, intended use, alternatives, return format, error/gap behavior, contradictions, hop progression, citation resolvability, and performance expectations. This leaves the agent fully informed for selection and invocation.

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

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

The input schema already covers both parameters with descriptions. The description adds meaningful depth by explaining how 'depth' levels differ ('standard' adds gap recovery, 'thorough' chases leads) and clarifies that the question is decomposed into facets. This goes beyond the schema's enum descriptions, so it earns above baseline.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' and explicitly contrasts it with open-web search. It also differentiates from sibling tools by saying 'For a single lookup use ask_pipeworx' and names when to prefer ask_pipeworx for current news, making its purpose and scope unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and gives clear alternatives with rationale: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and for breaking/news topics 'prefer ask_pipeworx'. It also notes account requirements and the fallback to ask_pipeworx when 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, idempotentHint, and non-destructive behavior, so the description does not need to restate those. It adds valuable behavioral context by disclosing that results include names, descriptions, and full input schemas with curated examples, and that each result is ready to call directly with no second lookup. This informs the agent of the exact response structure and immediate actionability, beyond what annotations provide.

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

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

The description is front-loaded with the core purpose, followed by a scannable domain list, then return-behavior details, and a clear 'call this FIRST' instruction. It is somewhat long due to the enumerated domains, but every sentence contributes useful information. It strikes a good balance between completeness and length, though the domain list could be seen as slightly verbose.

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

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

With no output schema, the description appropriately explains what the tool returns: top-N tools with names, descriptions, and full input schemas. It also sets expectations with 'ready to call directly' and 'no second schema lookup'. It does not mention pagination or error handling, but for a discovery tool with clear annotations and a well-documented limit parameter, the description covers the essential 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 with detailed descriptions for query, its aliases (q, task, search, description), and limit. The description adds only high-level context ('describing the data or task', 'top-N') that maps closely to existing schema descriptions. Therefore, the description adds minimal value beyond the schema, 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 opening sentence 'Find tools by describing the data or task' uses a specific verb and resource, clearly distinguishing this as a meta-tool for discovery rather than a data-access tool. The scope is further clarified with a long list of domains (SEC filings, FDA drugs, etc.), and the 'Discover Tools' title is reinforced. This clearly separates it from sibling tools like search_datasets or query_layer.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available...'. It also implies a boundary with 'not just one answer', indicating it is for exploring options rather than directly retrieving a known answer. However, it does not explicitly identify when not to use it or name alternative tools, 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?

Beyond the readOnlyHint, openWorldHint, idempotentHint safe profile, the description adds behavioral context: it fans out across multiple sources in parallel, soft-fails for the patent API (noting a May 2025 sunset), and limits recent_filings to 'up to 5'. It also clarifies the input limitation on names. 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 and packed with useful examples, directives, and caveats, but it is structured as a long run-on sentence. It could be improved with bullet points or clearer segmentation; however, every part earns its place and the key 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?

The tool is complex and has no output schema, so the description carries the burden of explaining returns. It enumerates the main fields (cik, filings, fundamentals, patents, news, LEI) and includes important caveats (patent soft-fail, name limitation). It does not detail exact output schemas or error behavior, but for this complexity it is largely sufficient.

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

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

Schema description coverage is 100%, and the schema already explains the ticker/CIK format and name limitation. The description repeats this information without adding substantially new parameter semantics beyond the examples already present in the schema, 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 explicitly states 'full cross-source profile of a US public company in ONE parallel call' and enumerates specific output components (cik, recent_filings, fundamentals, patents, news, LEI). It provides multiple example queries and clearly distinguishes itself from sibling tools like resolve_entity and single-pack lookups.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and states that names are not supported, directing to 'use resolve_entity first if you only have a name.' This clearly indicates when to use versus alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds that it deletes 'previously stored memory' and mentions clearing sensitive data, but does not disclose behavior like handling non-existent keys or side effects. The criteria say to credit added context; this adds minimal but non-contradictory context.

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

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

The description is two sentences: the first defines the action clearly, the second provides usage guidance. No wasted words, 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 one-parameter delete tool with annotations covering safety, the description covers purpose and usage well. It lacks mention of return values, but no output schema exists and the tool is straightforward.

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

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

The input schema has 100% coverage with a description for key and an example. The tool description only repeats 'by key' without adding semantic detail, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb-resource pair. It distinguishes itself from sibling tools like remember and recall by explicitly mentioning them as counterparts.

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

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

It provides explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and references remember/recall. However, it does not explicitly state when not to use the tool or name a specific alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context beyond annotations: it fetches the page, extracts title/description/key links, and emits a single text blob ready to drop at site-root/llms.txt. This clarifies the operation's nature without contradicting annotations.

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

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

The description is two sentences plus a 'Useful for' list. It is front-loaded with the main purpose and outcome, and every sentence adds value: what it does, how it works, output format, and use cases. 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?

Despite having no output schema, the description explicitly states the output is 'a single text blob ready to drop at site-root/llms.txt'. Combined with clear process description, parameter schema coverage, and annotations, the description is fully complete for the tool's moderate complexity.

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

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

Schema description coverage is 100%, so the description does not need to add much parameter-level detail. The description mentions 'URL' and 'max_links' implicitly through the fetch/extract behavior, but the schema already handles parameter documentation. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states a specific verb ('Generate'), resource ('llms.txt file'), and scope ('for any URL'), and explains the core actions (fetch, extract, emit standard format). It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on the generation of the llms.txt artifact rather than analysis.

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 use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it falls just 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds specific behavioral details about the return content (fields, geometry type, record count, capabilities) beyond annotations, without contradicting them. It does not discuss error handling or access prerequisites, but the annotation coverage lowers the burden.

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 conveys all key information without waste. Every clause contributes meaning: the resource type, the URL input, and the specific schema elements returned.

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

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

Given the tool's simplicity (one parameter, no output schema), the description lists the expected return components (fields, geometry type, record count, capabilities), which is sufficient for an agent to understand the tool's output. It does not cover error scenarios or URL accessibility, but these are less critical for a read-only metadata tool.

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

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

Schema description coverage is 100%, so the baseline applies. The description mentions 'by url' but adds no meaningful semantic beyond the schema's parameter description. The schema already fully documents the single required parameter.

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

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

The description specifies a clear verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), listing specific outputs (fields, geometry type, record count, capabilities). It differentiates from siblings like query_layer and search_within by focusing on schema/metadata rather than data retrieval.

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

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

The description implies when to use the tool (when you need schema information for an ArcGIS layer by URL) but does not explicitly mention alternatives or exclusions. The sibling tool list includes query_layer and search_within, but no direct comparison is provided in the description.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by specifying that it lists the caller's active subscriptions and detailing the exact fields returned. This is useful behavioral disclosure, though it does not mention rate limits or pagination.

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

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

The description is two sentences: the first states the action and return fields, the second provides usage guidance. It is front-loaded, concise, and every sentence earns its place 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 list tool with one optional parameter and no output schema, the description is complete. It explains what it returns, the scope (active subscriptions), and when to use it. The schema covers the parameter, and annotations cover safety, so no critical information is missing.

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

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

The schema has 100% coverage for the single parameter (include_inactive), so the baseline is 3. The description does not mention the parameter, but the schema already explains its meaning and default value. The description adds no additional parameter 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 uses the specific verb 'List' with a clear resource ('the caller's active subscriptions') and explicitly enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly ties to the actions of subscribing and unsubscribing, providing clear context and alternatives.

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

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

Annotations provide no read-only/idempotent/destructive hints, so the description carries full burden. It discloses the claim_token workflow, rate limit (5 per identifier per day), free usage (doesn't count against quota), and that the team reads digests daily. This enables the agent to predict side effects and follow up correctly.

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

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

The description is longer than average but every sentence adds operational value: scope, exclusions, workflow, rate limits, and practical examples. It's front-loaded with the primary purpose and uses clear, scannable sentences. Minor redundancy with schema descriptions (e.g., message length) but overall efficient.

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

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

Given there is no output schema, the description thoroughly covers what the agent can expect (claim_token, status updates, resolution info). It also addresses the full context: which tools to report, how to describe issues, rate limiting, and what happens after filing. This is complete for a feedback tool with nested parameters and follow-up 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 schema already describes all 4 parameters at 100% coverage, so the baseline is 3. The description adds value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and elaborating on the context structure (which tool, pack, vertical). It enhances but doesn't reinvent schema information.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx feedback) and purpose (reporting bugs, feature gaps, praise). This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which serve different purposes.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and when NOT to use: 'if the tool came from a different MCP server in your client... file it with that server instead.' Also gives criteria for uncertain cases ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary 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 adds substantial context beyond the annotations: it explains the data is self-aggregating from CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached for 5min–1h depending on the window. These details inform the agent about data provenance, privacy, freshness, and output shape, which are not available from the annotations alone.

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

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

The description is front-loaded with the core purpose and then organized with a clear 'Useful for' list and technical notes. It is slightly verbose but every sentence earns its place; the structure aids comprehension without excessive 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, read-only tool with one optional parameter, the description is complete. It states what is returned (top tools, top packs, call volume), the exact data shape (pack, tool, count), and the caching behavior. No output schema exists, but the description sufficiently covers return values and edge considerations.

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

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

The input schema already fully describes the single 'window' parameter, including enum values and their semantic differences (short vs. long windows). The description only repeats this information, adding no new insight, so the baseline score of 3 is appropriate for complete schema coverage.

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

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

The description clearly states the tool's function: it returns trending information about what AI agents are calling on Pipeworx, specifically top tools, packs, and call volume over selectable windows. This is a specific resource (Pipeworx trending data) with a clear scope, and it distinguishes itself from siblings like discover_tools by focusing on real-time usage trends.

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 use cases (discovering hot data sources, confirming canonical tools, aligning with agent behavior) that tell the agent when to invoke it. However, it lacks explicit 'when not to use' or alternatives, so it does not fully meet the highest bar for 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds rich behavioral context: the fill check (realizable_edge_pp ≤ 0 means don't trade), the Jaccard similarity anchor (≥0.30), the placeholder filter (>20% returns null), and the response structure (opportunities[], partition_check). This goes well beyond what annotations convey, with no contradictions.

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

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

The description is long but well-structured and front-loaded. The first sentence states the core function. Subsequent sections clearly separate event mode, topic mode, semantic anchor, partition filter, response, and fill check. While every sentence adds value, the length is near the upper bound for a tool description, so it doesn't reach a 5.

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

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

Considering the tool's complexity (multiple modes, subtle fill-check logic, response fields) and the lack of an output schema, the description is exceptionally complete. It explains the full decision pipeline: how modes are chosen, what filters apply, what the response contains, and how to interpret the fill check. No important aspect appears missing.

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

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

Schema description coverage is 100% (both event and topic have detailed schema descriptions), so baseline is 3. The description adds extra meaning by providing concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explaining behavior per parameter (walks child markets, flattens markets), and clarifying that no args triggers trending_scan. This exceeds the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and the method (monotonicity + partition-sum). It also distinguishes itself from siblings like polymarket_fill_risk by mentioning custom sizing as a separate tool, and from polymarket_edges/edge_tracker by focusing on arbitrage rather than edge tracking.

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 is provided: 'Call with NO args' for trending_scan, 'event (recommended for a specific market)' with example slugs, and 'topic' for cross-event scanning with example seed questions. It also names an alternative tool: 'For custom sizing use polymarket_fill_risk.' This fully addresses when and how to use the tool versus alternatives.

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

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

The annotations already mark it read-only/idempotent, but the description adds significant behavioral detail: 1h KV caching keyed on all knobs, response diagnostics with funnel counters, model-specific mechanics (e.g., partition overround with per-sport α, placeholder-slug filters), and a 24h-move warning that the edge may already be priced in. This goes well beyond what annotations provide.

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

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

The description is long but front-loaded with purpose and organized into capital-letter sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL). Every sentence carries technical specificity with no filler or redundancy. Given the tool's complexity (9 params, multi-segment response, diagnostics), the length is appropriate and 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?

With no output schema, the description fully explains the response structure: top-level fields (by_segment, fed_candidates/fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume). It also documents caching, filtering logic, and caveats (e.g., rare-by-design for longshot, Fed signal unreliability), making it fully actionable 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?

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds practical rationale for the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), explains slippage assumptions, and clarifies why min_kelly does not apply to partition arbs. This exceeds the schema, though not every parameter (limit, window) is addressed outside 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 specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It enumerates the three model families and distinguishes itself as an opportunity-discovery tool, separating it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The phrase 'Built for "what should I bet on today"' provides an explicit use case, and 'without paging hundreds of markets' indicates it's for aggregate discovery. It also cautions against Fed bets at meeting-month horizons, which is an exclusion. However, it does not explicitly name alternative tools or conditions for switching, stopping short of full 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 richly discloses behavioral details beyond the annotations: the 60-day snapshot TTL, that snapshot gaps mean no scan occurred, that decay is computed on daily closes not intraday, and the response structure with has semantics for tracked/expired/snapshot_dates. Annotations already indicate read-only/idempotent, and the description adds significant context 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 long but every sentence is dense with meaningful information. It is front-loaded with the core purpose, then structured into Args, RESPONSE, and LIMITS sections. No wasted words; the length is justified by the lack of an output schema and the need to explain nuanced response semantics.

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

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

The tool has no output schema and only 2 parameters, yet the description fully explains the response structure (tracked, expired, snapshot_dates) with field-level detail, including signed edge_pp_net and median lifespan as a 'competition clock'. It also covers edge cases such as snapshot gaps, TTL limits, and computation methodology. This is exceptionally complete for the given complexity.

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

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

The schema covers 100% of parameter descriptions, giving baseline 3. The description adds meaning beyond the schema by clarifying that 'days' is a lookback with default 14 and max 30 (schema also mentions clamp 2-30), and that 'window' is a 'snapshot family' with examples 24hr/1wk/1mo. This adds useful nuance, pushing above baseline.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?'. It explicitly distinguishes itself from a current-edge view by contrasting fresh vs. old wide edges. This is a specific verb+resource+scope, differentiated from sibling tools like polymarket_edges.

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

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

The description provides clear usage context: it is for assessing edge persistence/decay, with the contrast 'a fresh wide edge and a 3-week-old wide edge are different trades' implying when to use it instead of a current-edge tool. However, it does not explicitly name alternative tools or say 'use X instead', so it falls short of full explicit when/when-not guidance.

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

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

Despite annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: it walks the CLOB ladder, returns a verdict, and highlights the danger of partial basket fills converting an arb into an unhedged directional position. This goes far 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 a single dense paragraph, but every sentence carries necessary information. It is front-loaded with the core purpose and mode definitions. Length is justified by the tool's complexity, though a bulleted mode breakdown would improve scanability; 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 no output schema, the description thoroughly lists return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs[], etc. for basket). It also covers defaults, requirements, and risk implications, making it self-sufficient for correct invocation.

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

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

Schema coverage is 100%, but the description enriches the parameters significantly. It explains that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S' in basket mode. It also clarifies that side defaults to 'auto' in basket mode based on partition sum, which is not 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 opens with a specific verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges), establishing unique purpose.

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

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

The description states exactly when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two mode-specific contexts (single-market vs. basket) and gives the risk rationale, making usage conditions explicit.

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

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

Beyond the read-only/idempotent annotations, the description discloses significant behavioral nuances: compatibility_warning conditions, temporal_alignment requirements, skipped_cross_type/cross_subtype counters, and the realistic limitation that most macro shortcuts currently return warnings. This greatly exceeds what annotations alone convey and contains 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 longer than average, but every sentence adds necessary detail for a complex cross-venue tool. It is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), though the density of technical caveats makes it slightly heavy to parse quickly.

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 provides remarkably complete context: response contents, spread direction (Kalshi − Polymarket), safety field semantics, skipped-pair accounting, and temporal alignment meaning. Given the complexity and nuance, 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?

The input schema already covers all three parameters with clear descriptions, so the baseline is 3. The description adds contextual semantics by explaining how topic shortcuts map to both venues and how explicit kalshi_event_ticker/polymarket_event_slug override the mapped defaults, which helps agents choose the right parameter combination.

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, unambiguous statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates from siblings by naming the two modes and emphasizing safety checks that other spread tools likely lack.

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

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

The description explicitly explains when to use the tool, enumerates the two invocation modes (mapped topic vs explicit ticker/slug), and provides detailed guidance on interpreting compatibility warnings. It even cautions that pre-mapped topics may not be tradeable, giving clear when-to-use and when-not-to-trust signals.

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, and idempotentHint, so the safety profile is clear. The description adds valuable context by noting that it returns attribute rows and geometry, and that the where clause is SQL-like (not full SQL), which informs agent expectations beyond structured fields.

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

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

Two sentences, no filler. The first sentence front-loads the verb and resource, and the second offers a concrete usage tip. Every word earns its place, making it highly efficient and easy to parse.

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

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

Given the tool's simplicity, strong annotations, and comprehensive schema, the description covers the essential return behavior (rows and geometry) and the provenance of URLs (from search_datasets). It omits only minor details like pagination limits, but those are in the schema and not critical for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description reinforces the meaning of `where` as SQL-like and `out_fields` as comma-separated, but adds no substantive new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with a specific verb and resource. It distinguishes from siblings by enumerating the SQL-like query parameters (where, out_fields, order_by, limit, offset) and mentions it is sourced from search_datasets, positioning it distinctly against layer_info 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 provides clear usage context: it is meant for querying layers found via search_datasets, and includes a practical sampling tip (`where="1=1" + out_fields="*"`). It does not explicitly name alternatives or exclusions, but the intended workflow is implied well enough for an agent to decide when to use this tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable scoping context (anonymous IP, BYO key hash, or account ID) and explains the dual behavior of retrieving a value or listing all keys when omitted. It does not mention return format or missing-key handling, but this is acceptable given 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?

Three sentences, each carrying necessary information: the core action, the lookup purpose, and scoping plus sibling tools. No fluff or repetition; key details are front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: what it does, when to use it, how scoping works, and how it relates to remember and forget. The annotations handle the safety profile, so no further disclosure is needed.

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

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

The schema description for the only parameter 'key' is fully descriptive: 'Memory key to retrieve (omit to list all keys).' The tool description reinforces this behavior but introduces no additional semantic details such as format constraints or defaults. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description uses specific verbs ('retrieve', 'list') and identifies the resource (values saved via remember). It clearly distinguishes itself from sibling tools by explaining the counterpart tools for saving (remember) and deleting (forget), and immediately clarifies the listing capability.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier' and provides direct alternatives: 'Pair with remember to save, forget to delete.' This gives clear guidance on appropriate use cases and related 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 reveals a state-changing behavior: 'Set mark_read:true to flag returned events read' which modifies the feed state. This directly contradicts the annotation readOnlyHint=true, which declares the tool as read-only. The annotation misleads agents into assuming no side effects, while the description discloses a conditional mutation. This is an annotation 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 compact and front-loaded with the core purpose. It covers return fields, filter options, mark_read behavior, polling note, and an alternative endpoint in just three sentences, with no redundant or filler content.

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

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

For a tool with 5 optional parameters and no output schema, the description provides essential return structure (source, citation_uri, raw payload), filtering guidance, mark_read side effects, and polling advice. It lacks a mention of unread_only, but the schema covers it. However, the annotation contradiction reduces trust and completeness, so it's not a perfect score.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema, especially for mark_read: 'so the next call only shows newer ones' explains the consequence of flagging read. It also gives a concrete example for type ('sec_8k') and mentions ISO timestamp for since, enhancing the schema's descriptions.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes itself from siblings like recent_changes and list_subscriptions by focusing on alerts with citation_uri and raw event payloads. It also mentions the persisted feed, making the tool's scope unambiguous.

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

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

The description provides usage context: 'Polls work fine' indicates suitability for repeated checks, and the alternative GET endpoint offers a non-polling option for scripts/dashboards. However, it does not explicitly contrast with sibling tools like recent_changes or list_subscriptions, though the unique functionality is clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, and the description goes far beyond by disclosing multi-source fan-out (SEC, GDELT, GNews, USPTO), fallback logic, rate-limit handling ('GNews when rate-limited or 5xx'), and the PatentsView sunset causing soft-fail. It also describes the output structure (changes[], total_changes, citation URIs) 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 long but each sentence earns its place, covering user triggers, sources, fallbacks, parameter formats, output summary, and alternative tool. It's front-loaded with query examples and flows logically from purpose to mechanics to differentiation. Slightly verbose, but efficient for the tool's complexity.

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

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

For a multi-source tool with fallbacks and no output schema, the description provides complete context: purpose examples, source breakdown, fallback logic, parameter semantics, output summary, and an explicit pointer to a sibling tool. Nothing essential is missing, making it highly complete for an agent to select and invoke the tool correctly.

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

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

The input schema already covers 100% of parameters, so the baseline is 3. The description adds meaningful value by clarifying the 'since' parameter with relative shorthand examples and a recommended default ('Use "30d" or "1m" for typical monitoring'), and by explaining that 'value' can be a ticker or zero-padded CIK with an example. This goes beyond the schema's 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 explicitly states the tool is a 'change feed for a company in the last N days/weeks/months' and provides natural-language triggers like "What's new with X" and "updates on Acme." It also distinguishes itself from the sibling entity_profile tool by telling the agent to use entity_profile for static profile queries, making the purpose and differentiation crystal 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 gives specific when-to-use guidance with example queries and explicitly states when to use an alternative ('Use entity_profile instead when you want the static profile'). It also details fallback behavior (GDELT→GNews, USPTO soft-fail) and source-specific caveats, providing thorough usage context beyond what annotations offer.

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

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

Beyond annotations (idempotentHint true, readOnlyHint false), the description discloses scoping ('scoped by your identifier') and durability ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). This adds significant behavioral context that annotations do not cover, 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 four sentences, each earning its place: purpose, usage trigger, storage behavior, and lifecycle pairing. It is front-loaded with the core action and contains no filler, making it optimally concise.

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

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

For a simple 2-parameter tool with full schema coverage and useful annotations, the description covers purpose, usage context, persistence semantics, and related tools. The absence of an output schema is not a concern given the tool's simplicity and the presence of rich annotations, making the description complete for an agent.

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

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

Schema coverage is 100%, so both parameters are fully described in the schema. The description adds value by giving examples of what constitutes a worthwhile value ('a resolved ticker, a target address, a user preference') and reinforces the key-value nature, though it does not introduce meaning beyond the schema's own examples.

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

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

The description states a clear, specific action: 'Save data the agent will need to reuse later' with explicit storage semantics ('Stored as a key-value pair'). It distinguishes itself from sibling tools by naming recall and forget as complementary operations, making the tool's role unmistakable.

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

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

Explicit guidance is given for when to use the tool: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also mentions pairing with recall and forget, providing clear context relative to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond these: it cascades through several internal endpoints, auto-disambiguates company inputs, and returns specific citation URIs. This enriches the agent's understanding of the tool's operation 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 well-structured and front-loaded with the core use case and examples. It then provides a concise breakdown of supported types and return values. Every sentence adds meaningful information, with no fluff or repetition of schema/annotation content.

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

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

Given the tool's simplicity (2 params, no output schema), the description is remarkably complete. It explains what the tool returns for each type, including specific identifiers and citation URIs, and provides clear usage context. Combined with strong annotations, the agent has everything needed to select and invoke this 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% for both parameters, so the baseline is 3. The description adds extra value by providing concrete examples for 'value' (ticker, CIK, brand/generic names) and clarifying that company input can be ticker, CIK, or name with auto-disambiguation. This goes beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It gives concrete examples of queries and the specific resources ('company', 'drug') and identifiers (ticker, CIK, RxCUI) it returns, making it unambiguous and distinct from sibling tools like entity_profile or search tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use instruction. It also explains that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by explaining the internal mechanism (probes each entity with ai_visibility_check), ranking logic, and output structure (score, confidence, signal density). This exceeds the baseline given the strong annotation coverage.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence earns its place: purpose, usage context with example, and return values. No wasted words.

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

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

Given the tool's moderate complexity (4 params, 1 required, no output schema), the description fully covers purpose, usage, parameter semantics, and expected return format. It is complete for an AI agent to select and invoke correctly without additional documentation.

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

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

Schema coverage is 100% with descriptive parameter docs. The description adds extra semantic value by explaining that the first entity is treated as the subject for the narrative and the rest as competitors, and by noting the shared context use case. This goes beyond the schema, so a 4 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 a specific verb ('Compare AI visibility') and resource ('multiple entities side-by-side'), and explicitly distinguishes itself from related tools like ai_visibility_check by framing it as a comparative audit across brands/competitors. The example query further clarifies the purpose.

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

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

The description provides clear context for when to use the tool ('Useful for competitive AI-marketing audits') and implies it is an alternative to running ai_visibility_check individually for each entity. It does not explicitly state exclusions or when not to use it, but the example and mention of ai_visibility_check give sufficient guidance.

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

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

The description adds substantial context beyond annotations: it reveals the composite fan-out to two external services, mentions that the first bundlephobia measurement can take 5-30s, and explains that partial failures degrade gracefully with sources_failed listing timeouts. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false).

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

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

The description is dense but every sentence earns its place: purpose, usage triggers, return structure, ecosystem scope, and failure behavior are all covered efficiently. It front-loads the core purpose 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?

With no output schema, the description compensates by explicitly listing the summary block fields, per-advisory detail, links, and alternative versions. It also covers limitations (NPM-only), timing, and graceful degradation, making it complete for a composite 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 100% of parameters with descriptions, so baseline is 3. The description adds value by clarifying that 'package' accepts scoped packages (e.g. '@types/node') and that 'version' defaults to latest when omitted. This is meaningful 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 a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It also distinguishes itself from alternatives by specifying NPM-only in v1 and directing other ecosystems to deps.dev:version directly.

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

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

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a clear exclusion: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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, covering the safety profile. The description adds value by disclosing the exact return payload (name, summary, record_count, owner/org, Feature Service url), providing behavioral transparency beyond the annotations without any contradiction.

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

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

Two sentences, front-loaded with the action and scope, and includes examples in parentheses. Every clause adds value: what it searches, examples, return fields, and downstream usage. No redundant or filler text.

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 is complete for a search/discovery tool: it states the purpose, return structure, and chaining to sister tools. Given the tool has no output schema and the annotations cover safety, this is sufficient. It could mention default limit or behavior when no query is provided, but the schema already covers those details.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description enhances parameter understanding by explaining how the returned Feature Service url is meant to be used with query_layer/layer_info, which clarifies the purpose of the query and the result's role in the workflow.

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 'Search' and clearly identifies the resource as 'City of Peoria GIS open geospatial datasets' with concrete examples (parcels, zoning). It also states the returned fields and names downstream tools (query_layer/layer_info), which differentiates this discovery tool from data querying tools.

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

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

The description implies a workflow by instructing to pass the returned Feature Service URL to query_layer/layer_info, giving clear context for when to use this tool. However, it does not explicitly exclude alternatives or state when not to use it, so it's slightly short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral detail: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagging. This richly informs the agent about execution semantics 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?

Three sentences with clear structure: purpose first, usage scenario second, technical mechanics third. Every sentence adds value with no fluff or repetition. It is front-loaded and appropriately sized for the tool's complexity.

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

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

The description covers what the tool returns (passages with offsets and scores), the technical approach (embeddings, windows), the input cap, truncation behavior, and how it pairs with sibling tools. With good annotations and complete schema, this is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The schema already describes all parameters in detail (text max length, query examples, limit range/default). The description reinforces these but doesn't add new parameter-level meaning. It mentions top-N and offsets, but that's return value context, not param 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: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from sibling tools by emphasizing that it operates on text the agent already has, not fetching new data. The examples (SEC 10-K, article) and pairing with ask_pipeworx_grounded further clarify its unique role.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It names a complementary alternative (ask_pipeworx_grounded) and explains the workflow: fetch with the gateway, then ground over relevant passages. This gives clear usage context and an implied when-not (when the record fits in the prompt).

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

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

With annotations present (readOnlyHint: false, idempotentHint: true, destructiveHint: false), the description adds useful context: OAuth account requirement, feed always-on, SMS verification and 10/day cap. However, it uses the phrase 'new subscription id' which could be misinterpreted as non-idempotent, creating ambiguity with the idempotentHint annotation. No outright contradiction, but idempotency is not explained.

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 structured: purpose, return value, auth requirement, supported types, and delivery channels. Each sentence provides necessary information without fluff. It is longer than minimal but justified given the variety of options.

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 auth, return value, and several delivery channels, but omits the webhook delivery channel (present in schema) and two subscription types (patent_grant, clinical_trial). Since these are valid options, the description is incomplete. Output schema is absent, but the tool returns an id, which is explained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for parameters (e.g., items: ["5.02"] meaning officer change) and clarifying delivery options like email and SMS. The webhook parameter is only in the schema, but the description still enriches the understanding.

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

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

The description clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream' and mentions 'Returns the new subscription id.' It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on subscription 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 clear context for when to use the tool: for proactive monitoring of specific event types. It lists supported types and delivery channels. However, it does not explicitly say when not to use it (e.g., for one-time data queries) or direct users to alternatives like list_subscriptions for viewing existing subscriptions.

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

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

Annotations already declare safe read-only, idempotent behavior, so the burden is lower. The description adds useful behavioral detail: results are 'drawn from the live catalog of thousands of tools,' it returns category-bucketed examples, and behavior changes based on the optional topic parameter. This goes beyond what annotations alone convey, though it does not describe internal side effects or performance characteristics, which are not critical here.

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 natural-language example prompts, then quickly explains purpose, return content, parameter usage, and when to use. It is somewhat dense with category lists, but every part earns its place by teaching the agent how to interact with the meta-tools and what to expect. The structure moves from user intent to tool behavior to invocation details efficiently.

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

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

For a single-optional-parameter tool with no output schema, the description is remarkably complete: it states purpose, return format (category-bucketed examples with tool + argument shape), input behavior, and when to prefer this tool. Without a formal output schema, the description adequately covers return values. It also contextualizes this tool among sibling tools, satisfying the need for contextual completeness.

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

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

The input schema already describes the single optional parameter with 100% coverage, listing valid topic values and the default behavior. The description enriches this by giving concrete examples ('finance', 'pharma', 'betting'), explaining that omitting the topic yields a cross-category spread, and clarifying how the parameter focuses the returned suggestions. This adds meaningful guidance beyond the schema.

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

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

The description clearly identifies suggest_questions as the onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings like discover_tools and ask_pipeworx by framing its specific role: showing what to ask and how to call meta-tools.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to call with no arguments versus passing a topic, and names related meta-tools such as ask_pipeworx, entity_profile, and compare_entities, giving clear context for when this tool is appropriate.

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

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

The description goes beyond annotations by disclosing that cancellation deactivates rather than deletes the row and that historical events remain accessible. This adds meaningful behavioral context not present in the 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?

Three brief sentences, front-loaded with the primary verb and resource. Every sentence contributes a distinct valuable point: the action, the ownership constraint, and the behavioral consequence. No unnecessary words.

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

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

For a simple single-parameter mutation tool with good annotations, the description is complete. It addresses the action, the ownership rule, and the persistence of historical data, which is sufficient given the tool's low complexity and lack of output schema.

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

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

The input schema already documents the id parameter with a clear description and 100% coverage. The description only reiterates that cancellation is by id, adding no additional semantic value beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, distinguishing it from sibling tools like subscribe and list_subscriptions. The deactivation detail further clarifies the intended behavior.

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

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

It provides clear context by specifying ownership enforcement and the effect on historical events via recent_alerts. It does not explicitly name alternatives or list when-not-to-use cases, but the purpose and constraints are evident from the description and sibling tool 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?

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds meaningful behavior beyond this: the exact verdict categories, the structured vs grounded fallback logic, the tolerance override behavior, and the inclusion of citations and reasoning. It does not contradict annotations.

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

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

The description is longer than the average tool description, but it is well-structured: starts with query examples, states the use case, explains routing, and lists expected outputs. Every sentence contributes value, though some redundancy exists in the example list.

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

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

Despite having no output schema, the description thoroughly explains the return value structure (verdict types, actual value, citation, reasoning) and covers routing and edge cases. It gives enough context for an agent to know exactly what to expect and how to interpret results.

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

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

Schema descriptions cover both parameters, but the description adds practical usage details for tolerance_pct (default implied by wording, capped at 5, recommended range for hallucination detection) that are not in the schema. This enhances parameter understanding beyond the structured definitions.

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

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

The description clearly specifies the tool's function with a specific verb-resource pair ('validate claim', 'fact check', 'verify the claim that') and gives concrete examples. It distinguishes itself from siblings by describing the structured path for company-financial claims versus grounded pipeline for other claims, and notes it replaces 4-6 sequential calls.

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

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

Provides explicit when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details routing criteria (company-financial vs other claims) and mentions it replaces multiple sequential tool calls, clearly signaling when to invoke this tool instead of a chain.

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